GateIn sign in is based on servlet container sign on and by default relies on the the form based authentication. By default the features provided by the servlet container sign in are limited but GateIn adds a few features like the remember me functionality and the capability to trigger the sign in procedure from a form that remains compatible with servlet container authentication. As some part of the login cannot be controlled by the portal (such as the programmatic login until Servlet 3.0), GateIn relies on the HTTP redirection mechanism to leverage the browser to create interactions between the servlet container and the user client browser.

Authenticating with GateIn

GateIn provides several authentication facilities

• Clicking on the sign in links brings a popup where the user can enter his username and password. Optionally he can activate the rememberme of his sign in.
• Targetting a private URL such as /portal/private/classic forces the user to authenticate.
• Using the login servlet directly can authenticate the user. This is useful when developing GateIn and you want to save time when you need to target a private URL. In that kind of situation the login servlet can be invoked directly with
  • http://localhost:8080/portal/login?username=root&password=gtn authenticates with the root user and display the /portal/private/classic page
  • http://localhost:8080/portal/login?initialURI=%2Fportal%2Fprivate%2Fclassic%2Fadministration%2Fregistry&username=root&password=gtn authenticates with the root user and displays the /portal/private/classic/administration/registry page. Note that the initialURI parameter must be encoded properly.

Sign in servlets

Three special servlets are deployed in the portal that are used by GateIn to implement triggered login and remember me login.

Login servlet

The login servlet defined by the class org.exoplatform.web.login.PortalLoginController is mapped via the /login path and is responsible for triggering the servlet container sign in procedure. The servlet is parameterized by several servlet parameters (either query parameters or form based parameters)

Servlet parameters

• username: the mandatory user name
• password: the mandatory password
• initialURI: an optional uri that the browser will be used for login, note that this URI must be an authenticating URI usually starting with /portal/private. If no URI is provided then the /portal/private/classic is used instead. This uri will also be shown once authentication is successful.
• rememberme: an optional boolean value. When this value is true then the login will trigger the creation of a cookie that will be used for the rememberme feature.

Servlet steps

1. The servlet looks for the username and password parameters. If any of them is not present then a 400 error is sent to the browser, otherwise they are stored in a credential object in the http session for later use by the servlet initiating the login.
2. The initial uri is computed either from the initialURI request parameter or by using the /portal/private/classic value.
3. If the rememberme parameter is set to true then the servlet use the CookieTokenService to obtain a token that will be sent as a cookie the next response. The token is associated with the user credentials for performing authentication later.
4. The response is a 302 http redirection on the uri computed in step 2

Initial login servlet

This servlet is defined by the class org.exoplatform.web.login.InitiateLoginServlet. The role of this servlet is to perform interactions with the web browser to trigger a servlet container login.

Servlet configuration

The servlet is mapped on the path /initiatelogin but it should never be used directly instead it is defined as the form login page of the portal web application

<login-config>
  <auth-method>FORM</auth-method> 
  <realm-name>gatein-domain</realm-name> 
  <form-login-config>
    <form-login-page>/initiatelogin</form-login-page> 
    <form-error-page>/errorlogin</form-error-page>
  </form-login-config>
</login-config>

Servlet steps

1. The servlet first looks for any credential object in the http session.
2. When credentials are found the servlet interacts with the transient token store service to create a token. That token is associated with the credentials found in the session and will be stored until the interaction with the browser to perform authentication is done. The role of the token is to avoid sending the username and password to the client in clear text. After that, the servlet redirects the browser to the j_security_check URL with the username found in the credentials and the token value as password.
3. When no credential is found, the servlet looks for an existing rememberme cookie. When a valid remember cookie is found, the servlet redirects the browser to the j_security_check URL with the username found in the credentials and the token value as password. If the token exist but is not valid the request is dispatched to the JSP login servlet /login/jsp/login.jsp that will display the login form, the invalid rememberme cookie is also cleared.
4. When no credential nor a token is found, the servlet dispatches to the JSP login servlet /login/jsp/login.jsp to display the login form to the user.

Error login servlet

The error login servlet defined by the class org.exoplatform.web.login.ErrorLoginServlet clears any rememberme token and displays the JSP login page /login/jsp/login.jsp to the user. It is mapped on the /errorlogin path. It is usually accessed when the web authentication fails during the servlet container sign in.

Remember me filter

The remember me filter's role is to activate auto login when a remember me cookie is present on the incoming request. It performs an http redirection on a public URL changing the public part to the private part.