documentation:2.0:securetoken
Keywords: documentation,2.0,securetoken

# Secure Token Handler

## Presentation

The Secure Token Handler is a special Handler that creates a token for each request and send it to the protected application. The real user identifier is stored in a Memcached server and the protected application can request the Memcached server to get user identifier.

This mechanism allows one to protect an application with an unsafe link between Handler and the application, but with a safe link between the Memcached server and the application.

## Configuration

### Virtual host

#### Apache

VirtualHost has to be configured like other protected virtual hosts but by using Secure Token Handler instead of default Handler.

    PerlModule Lemonldap::NG::Handler::Specific::SecureToken
    <VirtualHost *:80>
           ServerName secure.example.com

           # Load SecureToken Handler
           PerlHeaderParserHandler Lemonldap::NG::Handler::Specific::SecureToken

           ...

    </VirtualHost>

#### Other web servers

This handler uses Apache2Filter Module to hide token, prefer Handling server webservice calls for other servers.

### Handler parameters

SecureToken parameters are the following:

- Memcached servers: addresses of Memcached servers, separated with spaces.
- Token expiration: time in seconds for token expiration (remove from Memcached server).
- Attribute to store: the session key that will be stored in Memcached.
- Protected URLs: Regexp of URLs for which the secure token will be sent, separated by spaces
- Header name: name of the HTTP header carrying by the secure token.
- Allow requests in error: allow a request that has generated an error in token generation to be forwarded to the protected application without secure token (default: yes)

Due to Handler API change in 1.9, you need to set these attributes in `lemonldap-ng.ini` and not in Manager, for example:

    [handler]
    secureTokenMemcachedServers = 127.0.0.1:11211
    secureTokenExpiration = 60
    secureTokenAttribute = uid
    secureTokenUrls = .*
    secureTokenHeader = Auth-Token
    secureTokenAllowOnError = 1