Form Based AuthenticationHandler
The Form Based AuthenticationHandler has two authentication phases: The first phase is presenting a login form to the user and passing the entered user name and password to the server. The second phase is storing successful authentication in a Cookie or an HTTP Session.
The implementation of the Form Based Authentication Handler follows the guidelines of the Servlet API 2.4 specification for Form Based Authentication in section SRV.12.5.3. Specifically the following requirements are implemented:
- For the initial form submission, the request URL must end with
/j_security_checkand the user name and password names must be
- The authentication type as returned by
HttpServletRequest.getAuthType()is set to
The Form Based Authentication Handler is maintained in the Sling SVN
extractCredentials-- Prepares credentials for the form entered data or from the Cookie or HTTP Session attribute. Returns
nullif neither data is provided in the request
requestCredentials-- Redirects the client (browser) to the login form
dropCredentials-- Remove the Cookie or remove the HTTP Session attribute
authenticationFailed-- Remove the Cookie or remove the HTTP Session attribute
authenticationSucceeded-- Set (or update) the Cookie or HTTP Session attribute
Phase 1: Form Submission¶
The login form submitted in phase 1 to validate the user name and password must be provided in an HTTP
POST request to an URL whose last segment is
j_security_check. The request is ignored as a form submission if either the method is not
POST or the last segment is no
The form is rendered by redirecting the client to the URL indicated by the
form.login.form configuration parameter. This redirection request may accompanyied by the following parameters:
resource-- The resource to which the user should be redirected after successful login. This request parameter should be submitted back to the server as the
j_reason-- This parameter indicates the reason for rendering the login form. If this parameter is set, it is set to
INVALID_CREDENTIALSindicating a previous form submission presented invalid username and password or
TIMEOUTindicating a login session has timed out. The login form servlet/script can present the user with an appropriate message.
The Form Based Authentication Handlers supports the following request parameters submitted by the HTML form:
j_username-- Name of the user to authenticate
j_password-- Password to authenticate the user
j_validate-- Flag indicating whether to just validate the credentials
resource-- The location to go to on successful login
sling.auth.redirect-- The location to redirect to on successful login
j_password parameters are used to create a JCR
SimpleCredentials object to log into the JCR Repository.
j_validate parameter may be used to implement login form submission using AJAX. If this parameter is set to
true (case-insensitive) the credentials are used to login and after success or failure to return a status code:
||Authentication succeeded; credentials are valid for login; the Cookie or HTTP Session attribute is now set|
||Authentication failed; credentials are invalid for login; the Cookie or HTTP Session attribute is not set (if it was set, it is now cleared)|
j_validate parameter is not set or is set to any value other than
true, the request processing depends on authentication success or failure:
|Success||Client is redirected to the authenticated resource; the Cookie or HTTP Session attribute is now set.|
|Failure||The request is redirected to the login form again; the Cookie or HTTP Session attribute is not set (if it was set, it is now cleared)|
sling.auth.redirect parameters provide similar functionality but with differing historical backgrounds. The
resource parameter is based on the
resource request attribute which is set by the login servlet to indicate the original target resource the client desired when it was forced to authenticate. The
sling.auth.redirect parameter can be used by clients (applications like cURL or plain HTML forms) to request being redirected after successful login. If both parameters are set, the
sling.auth.redirect parameter takes precedence.
Phase 2: Authenticated Requests¶
After the successful authentication of the user in phase 1, the authentication state is stored in a Cookie or an HTTP Session. The stored value is a security token with the following contents:
securetokennumber are related in that an table of secure tokens is maintained where the
securetoken is an entry in the table and the
securetokennumber is the index in of the token in the table.
The secure tokens are refreshed periodically causing the authentication state stored in the Cookie or the HTTP Session to be updated peridocally. This periodic update has two advantages:
- Login sessions time out after some period of inactivity: If a request is handled for an authentication state whose expiry time has passed, the request is considered unauthenticated.
- If a Cookie would be stolen or an HTTP Session be hijacked, the authentication state expires within a reasonable amount of time to try to prevent stealing the authentication.
The authentication state may be transmitted with a Cookie which is configured as follows:
- Cookie Path -- Set to the servlet context path
- Domain -- See below
- Age -- Set to -1 to indicate a session Cookie
- Secure -- Set to the value returned by the
If the authentication state is kept in an HTTP Session the setup of the session ID cookie is maintained by the servlet container and is outside of the control of the Form Based AuthenticationHandler.
The Form Based Authentication Handler is configured with configuration provided by the OSGi Configuration Admin Service using the
org.apache.sling.formauth.FormAuthenticationHandler service PID.
||The URL (without any context path prefix) to redirect the client to to present the login form.|
||The type of storage used to provide the authentication state. Valid values are
||The name of the Cookie or HTTP Session attribute providing the authentication state.|
||The number of minutes after which a login session times out. This value is used as the expiry time set in the authentication data.|
||The name of the
||The name of the file used to persist the security tokens.|
||The domain on which cookies will be set, unless overridden in the
form.token.file parameter currently refers to a file stored in the file system. If the path is a relative path, the file is either stored in the Authentication Handler bundle private data area or -- if not possible -- below the location indicated by the
sling.home framework property or -- if
sling.home is not set -- the current working directory. In the future this file may be store in the JCR Repository to support clustering scenarios.
Form Based Authentication has some limitations in terms of security:
- User name and password are transmitted in plain text in the initial form submission.
- The Cookie used to provide the authentication state or the HTTP Session ID may be stolen.
To prevent eavesdroppers from sniffing the credentials or stealing the Cookie a secure transport layer should be used such as TLS/SSL, VPN or IPSec.