Home » Documentation » The Sling Engine » Authentication » Authentication - AuthenticationHandler

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:

The Form Based Authentication Handler is maintained in the Sling SVN

AuthenticationHandler implementation

AuthenticationFeedbackHandler implementation

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 j_security_check.

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:

The Form Based Authentication Handlers supports the following request parameters submitted by the HTML form:

The j_username and j_password parameters are used to create a JCR SimpleCredentials object to log into the JCR Repository.

The 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:

Status Description
200 OK Authentication succeeded; credentials are valid for login; the Cookie or HTTP Session attribute is now set
403 FORBIDDEN Authentication failed; credentials are invalid for login; the Cookie or HTTP Session attribute is not set (if it was set, it is now cleared)

If the j_validate parameter is not set or is set to any value other than true, the request processing depends on authentication success or failure:

Authentication Description
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)

The resource and 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.

The Form Based Authentication Handler contains a default form servlet and HTML form template.

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:

HmacSHA1(securetoken, <securetokennumber><expirytime>@<userID>)@<securetokennumber><expirytime>@<userID>

The securetoken and 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:

The authentication state may be transmitted with a Cookie which is configured as follows:

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.

Parameter Default Description
form.login.form /system/sling/form/login The URL (without any context path prefix) to redirect the client to to present the login form.
form.auth.storage cookie The type of storage used to provide the authentication state. Valid values are cookie and session. The default value also applies if any setting other than the supported values is configured.
form.auth.name sling.formauth The name of the Cookie or HTTP Session attribute providing the authentication state.
form.auth.timeout 30 The number of minutes after which a login session times out. This value is used as the expiry time set in the authentication data.
form.credentials.name sling.formauth The name of the SimpleCredentials attribute used to provide the authentication data to the LoginModulePlugin.
form.token.file cookie-tokens.bin The name of the file used to persist the security tokens.
form.default.cookie.domain The domain on which cookies will be set, unless overridden in the AuthenticationInfo object.

Note: 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.

Security Considerations

Form Based Authentication has some limitations in terms of security:

  1. User name and password are transmitted in plain text in the initial form submission.
  2. 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.

Rev. 1476875 by dklco on Mon, 29 Apr 2013 01:14:52 +0000
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.