# Redirections

## Handler Redirections

When a user access a Handler without a cookie, he is redirected on portal, and the target URL is encoded in redirection URL (to redirect user after authentication process).

### Protocol and port

To encode the redirection URL, the handler will use some Apache environment variables and also configuration settings:

- HTTPS: use https as protocol
- Port: port of the application (by default, 80 for http, 443 for https)

These parameters can be configured in Manager, in `General Parameters` > `Advanced parameters` > `Handler redirections`.

These settings can be overridden per virtual host, see virtual host management.

### Forbidden and Server error

Handler use the default Apache error code for the following cases:

- User has no access authorization: FORBIDDEN (403)
- An error occurs on server side: SERVER_ERROR (500)
- The application is in maintenance: HTTP_SERVICE_UNAVAILABLE (503)

These errors can be catch trough Apache `ErrorDocument` directive or Nginx `error_page` directive, to redirect user on a specific page:

    # Apache: Common error page and security parameters
    ErrorDocument 403 http://auth.example.com/?lmError=403
    ErrorDocument 500 http://auth.example.com/?lmError=500
    ErrorDocument 503 http://auth.example.com/?lmError=503

    # Nginx: Common error page and security parameters
    error_page 403 http://auth.example.com/?lmError=403;
    error_page 500 http://auth.example.com/?lmError=500;
    error_page 503 http://auth.example.com/?lmError=503;

It is also possible to redirect the user without using `ErrorDocument`: the Handler will not return 403, 500, 503 code, but code 302 (REDIRECT).

The user will be redirected on portal URL with error in the `lmError` URL parameter.

These parameters can be configured in Manager, in `General Parameters` > `Advanced parameters` > `Handler redirections`:

- Redirect on forbidden: use 302 instead 403
- Redirect on error: use 302 instead 500 or 503

## Portal Redirections

If a user is redirected from handler to portal for authentication and once he is authenticated, portal redirects him to the redirection URL.

- Redirection message: The redirection from portal can be done either with code 303 (See Other), or with a JavaScript redirection. Often the redirection takes some time because it is user's first access to the protected app, so a new app session has to be created : JavaScript redirection improves user experience by informing that authentication is performed, and by preventing from clicking again on the button because it is too slow.
- Keep redirections for Ajax: By default, when an Ajax request is done on the portal for an unauthenticated user (after a redirection done by the handler), a 401 code will be sentwith a `WWW-Authenticate` header containing "SSO <portal-URL>". Set this option to 1 to keep the old behavior (return of HTML code).
- Skip re-auth confirmation: by default, when re-authentication is needed, a confirmation screen is displayed to let user accept the re-authentication. If you enable this option, user will be directly redirected to login page.