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_check and the user name and password names must be j_username and j_password, resp.
• The authentication type as returned by HttpServletRequest.getAuthType() is set to HttpServletRequest.FORM_AUTH.

The Form Based Authentication Handler is maintained in the the Sling repo.

AuthenticationHandler implementation

• extractCredentials -- Prepares credentials for the form entered data or from the Cookie or HTTP Session attribute. Returns null if 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

AuthenticationFeedbackHandler implementation

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

• 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 resource parameter.
• j_reason -- This parameter indicates the reason for rendering the login form. If this parameter is set, it is set to INVALID_CREDENTIALS indicating a previous form submission presented invalid username and password or TIMEOUT indicating 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

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:

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:

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:

• 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 ServletRequest.isSecure() method

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.

Configuration

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.

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.