User authentication overview

Learn how user authentication is achieved in Bonita. This page can be helpful to troubleshoot and debug authentication issues.

If you want to find out how to customize authentication refer to the dedicated documentation pages:

Bonita Runtime authentication scenario

To help understand how user authentication is performed, let’s take a typical case where a user accesses the Bonita Applications for the first time. This scenario is the default (no LDAP authentication, nor CAS).

user authentication

  1. In a web browser, the user types the URL of Bonita Applications (e.g. http://localhost:8080/bonita) that will initiate a HTTP request handled by the application server that delegates processing to the Bonita web application.

  2. When asked for the Bonita root, the URL server will provide a index.html file (you can find the index.html in the server/webapp/bonita folder). This is defined by the welcome-file property in the Bonita web application deployment descriptor (a web.xml file located in bonita/WEB-INF).

  3. Javascript in index.html will redirect the user to /apps/appDirectoryBonita (e.g. http://localhost:8080/bonita/apps/appDirectoryBonita).

  4. AuthenticationFilter applied to the HTTP request send to /apps/appDirectoryBonita. The filter will check if the user is already authenticated. To do so, it will look in the HTTP session for an apiSession attribute (see AlreadyLoggedInRule). If an apiSession attribute exists, this means a user is already authenticated.

  5. If the attribute apiSession is not set, the user will be redirected to the login page. Note: Information about the original page the user tried to reach is included in a URL parameter named redirectURL. The login page URL is determined by the AuthenticationManager implementation. The implementation to use for the current tenant is configured in a file authenticationManager-config.properties (located in setup/platform_conf/initial/tenant_template_portal or setup/platform_conf/current/tenants/[tenantid]/tenant_portal and updatable using the platform setup tool). The default AuthenticationManager is StandardAuthenticationManagerImpl. Its behavior is to redirect to the login.jsp page embedded in the webapp. Supporting different implementations enables authentication on an external application (useful for SSO deployement for example).

  6. login.jsp page will ask the user for the username and password (HTML form). When submitting the form, a POST request is sent to /loginservice. The request includes the username, password, tenant id (if provided in the URL, only applied to subscription editions), locale (optional, by priority order: provided in the URL, stored in HTTP cookie) and the redirectURL information.

  7. URL /loginservice is handled by LoginServlet.

  8. LoginServlet calls login method of LoginManager

  9. LoginManager searches for an AuthenticationManager implementation based on configuration file for current tenant (authenticationManager-config.properties). The default AuthenticationManager is StandardAuthenticationManagerImpl.

  10. authenticate method is called on the AuthenticationManager. authenticate method of StandardAuthenticationManagerImpl implementation of this method does nothing (the subsequent engine login is enough to authenticate the user)

  11. The authentication is considered successful if no Exception is thrown by the authenticate method.

  12. LoginManager will then call engine API LoginAPI.login()

  13. At this point, operations are processed on Bonita Engine side. Engine (see LoginAPIImpl class) verifies that the username and password are not empty. A verification is also done to validate that the tenant is enabled (use provided tenant id or default one if not provided). Then LoginAPIImpl will call LoginService (one implementation available: SecuredLoginService).

  14. SecuredLoginService calls GenericAuthenticationService. The default implementation is: AuthenticationServiceImpl.

  15. The AuthenticationServiceImpl verifies that your username and password are valid.

  16. After call of the GenericAuthenticationService, SecuredLoginServiceImpl performs an extra check to verify that the provided username exists in the Bonita database (SecuredLoginServiceImpl does not trust AuthenticationServiceImpl). Note: A specific behavior applies for the tenant technical user.

  17. SecuredLoginServiceImpl returns an object that represents the session. This is a server side only object (SSession)

  18. Call get back to LoginAPIImpl that converts SSession to APISession.

  19. APISession is provided back up to the LoginManager that will add session information as HTTP session attribute.

  20. Call get back to LoginServlet that will redirect the user to the requested page.

If you configure your Bonita platform to use CAS, the logical flow of authentication is the same as above. The difference is that at step 7 the CASRemoteLoginManager is used instead of the default loginManager and at step 12 the JAASGenericAuthenticationServiceImpl is called instead of the default authentication service, AuthenticationServiceImpl. The loginManager-config.properties file for a tenant controls which login manager and authentication service (cfg-bonita-authentication-impl.xml) are used.

Information about sessions

Two type of session are involved when using Bonita Runtime:

  • The HTTP session

  • The Bonita Engine session

The session timeout values for these two sessions should be set to the same value.

The HTTP session.

This session is created by the application server and corresponds to one user.

The Bonita Engine session

See APISession class. This session is created by Bonita Engine when the user submits a login page.

Session expiration

If the Engine session has expired and the user tries to reach one of the Bonita Application pages, an exception will be raised. Bonita Applications will catch this exception, invalidate the HTTP session and redirect the user to the login page.

The Bonita Engine default session duration is one hour (default value defined in SessionServiceImpl). You can configure a different session duration by editing the bonita.runtime.session.duration property in bonita-tenant-community-custom.properties. Specify the duration in milliseconds.

If the HTTP session has expired, Bonita Applications will redirect the user to the authentication page. The Bonita Engine session associated with the HTTP session that has just expired will remain active until it reaches the inactivity timeout. A cron job takes care of cleaning up inactive Engine sessions.

The HTTP session default duration depends on the application server (for example, 30 minutes for Tomcat). In cluster (Enterprise and Performance editions only) the application server value is replaced with the property bonita.runtime.cluster.http.session.timeout in the file bonita-platform-sp-cluster.properties (default value is 30 minutes).
The HTTP session Id is stored in a cookie in the user’s web browser for the duration of the HTTP session. Since cookies do not provide isolation by port, it is not advised to have several Bonita installations running on different ports of the same host. This would result in users getting 401 errors when trying to use simultaneously the 2 Bonita instances. This is also true in development with localhost deployments.

Logout

In Bonita Layout, if a user clicks on the logout button, both the Engine session and HTTP session will be invalidated.

How do Bonita Applications know if a user is authenticated?

The Bonita Applications check if a valid Bonita Engine session (APISession object) is found in the apiSession attribute inside the HttpRequest. If the engine session is still valid, the user will have access to the required resource.