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 Portal authentication scenario
To help understand how user authentication is performed, let’s take a typical case where a user accesses the Bonita Portal for the first time. This scenario is the default (no LDAP authentication, nor CAS).
In a web browser, the user types the URL of Bonita Portal (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.
When asked for the Bonita root, the URL server will provide a
index.htmlfile (you can find the
bonita.warfile). This is defined by the
welcome-fileproperty in the Bonita web application deployment descriptor (a
web.xmlfile located in
index.htmlwill redirect the user to
AuthenticationFilter applied to the HTTP request send to
/portal/homepage. The filter will check if the user is already authenticated. To do so, it will look in the HTTP session for an
apiSessionattribute (see AlreadyLoggedInRule). If an
apiSessionattribute exists, this means a user is already authenticated.
If the attribute
apiSessionis 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
setup/platform_conf/current/tenants/[tenantid]/tenant_portaland updatable using the platform setup tool). The default AuthenticationManager is StandardAuthenticationManagerImpl. Its behavior is to redirect to the
login.jsppage embedded in the webapp. Supporting different implementations enables authentication on an external application (useful for SSO deployement for example).
login.jsppage will ask the user for the username and password (HTML form). When submitting the form, a
POSTrequest 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
/loginserviceis handled by LoginServlet.
loginmethod of LoginManager
LoginManager searches for an AuthenticationManager implementation based on configuration file for current tenant (
authenticationManager-config.properties). The default AuthenticationManager is StandardAuthenticationManagerImpl.
authenticatemethod is called on the AuthenticationManager.
authenticatemethod of StandardAuthenticationManagerImpl implementation of this method does nothing (the subsequent engine login is enough to authenticate the user)
The authentication is considered successful if no Exception is thrown by the
LoginManager will then call engine API LoginAPI.login()
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).
SecuredLoginService calls GenericAuthenticationService. The default implementation is: AuthenticationServiceImpl.
The AuthenticationServiceImpl verifies that your username and password are valid.
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.
SecuredLoginServiceImpl returns an object that represents the session. This is a server side only object (SSession)
Call get back to LoginAPIImpl that converts SSession to APISession.
APISession is provided back up to the LoginManager that will add session information as HTTP session attribute.
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
Information about sessions
Two type of session are involved when using Bonita Portal:
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 on the Bonita Portal request, when the user submits a login page.
If the Engine session has expired and the user tries to reach one of the Bonita Portal pages, an exception will be raised. Bonita Portal 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
If the HTTP session has expired, Bonita Portal 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 your application server (for example, 30 minutes for Tomcat).|
In Bonita Portal, if a user clicks on the logout button, both the Engine session and HTTP session will be invalidated.
How does the Bonita Portal know if a user is authenticated?
The Bonita Portal checks if a valid Bonita Engine session (APISession
object) is found in the
attribute inside the HttpRequest. If the engine session is still valid, the user will have access to the required resource.