Redirections

Handler Redirections

Note

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.

Tip

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 through 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

With Nginx, you must add these directives in the location / { section:

# 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 route.

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

Note

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.

  • Skip upgrade confirmation: by default, when upgrade is needed, a confirmation screen is displayed to let user accept the authentication level upgrade. If you enable this option, user will be directly redirected to 2FA page.