This content is dedicated to our next version. It is work in progress: its content will evolve until the new version is released.

Before that time, it cannot be considered as official.

CAS SSO configuration

Bonita can be configured to use CAS to provide single sign-on (SSO), as long as you already have a working CAS service and all Bonita users are registered in CAS.

For Teamwork, Efficiency, Performance and Enterprise editions only.

The configuration steps detailed in this page include some modifications to the Tomcat configuration and common lib folder. This is not compliant with the Application deployment mode introduced with Bonita 2023.2. If you want your application container to work with a CAS SSO authentication, you will need to build the docker image of the application first and then configure the container (using a volume for example).

This information applies to a Bonita platform deployed from a bundle, not to the Engine launched from Bonita Studio.

CAS configuration is at tenant level. Each tenant can use a different CAS service.

On a system using CAS to manage logins, if a user who is not already logged in tries to access a page in the Bonita Applications by opening the URL link, they are re-directed to the login page. After logging in, the requested page is not displayed automatically. The user must click the link again.

Return URL

When the user visits the bonita web application using a web browser, the Bonita Runtime redirects it to the CAS server. The URL to the CAS server contains the service parameter: the value is an encoded return URL, that the CAS server should use to redirect back the user in case of successful authentication.

The return URL is not set by configuration; the server and port are taken out from the incoming HTTP request which reached the application server. By default, the web application server is configured to use the value of the Host: header (see the HTTP 1.1 standard) when present.

When a reverse proxy is used, the server and port of the HTTP request generated by the reverse proxy are not the same than the ones used in the original HTTP request in the user’s web browser.

As a consequence, configure the reverse proxy to include the Host: header when forwarding the request to the web application server.

The method getRequestURL ot HttpServletRequest is used internally to retrieve the server and port of the HTTP request.

Example

Reverse proxy configuration: use the ProxyPreserveHost property (Apache 2.0.31 or greater).

If you need more fine tuning or if you cannot update the reverse proxy configuration, you can consult the official documentation for Tomcat.

Configure Bonita Engine and Tomcat for CAS

The CAS implementation relies on JAAS, and is defined in the BonitaAuthentication module of the JAAS configuration file.
Set the Java system property java.security.auth.login.config in the Tomcat startup script to point to the JAAS configuration file, BUNDLE_HOME/server/conf/jaas-standard.cfg.

For example, on Linux, edit BUNDLE_HOME/setup/tomcat-templates/setenv.sh, uncomment the line that defines SECURITY_OPTS, and insert the variable SECURITY_OPTS in the line CATALINA_OPTS=...

The BUNDLE_HOME/server/conf/jaas-standard.cfg file contains the following (replace ip_address:port with the relevant IP addresses and port numbers, in two places):

BonitaAuthentication-1 {
  org.apereo.cas.client.jaas.CasLoginModule required
    ticketValidatorClass="org.apereo.cas.client.validation.Cas20ServiceTicketValidator"
    casServerUrlPrefix="http://ip_address:port/cas"
    tolerance="20000"
    service="http://ip_address:port/bonita/loginservice"
    defaultRoles="admin,operator"
    roleAttributeNames="memberOf,eduPersonAffiliation"
    principalGroupName="CallerPrincipal"
    roleGroupName="Roles"
    cacheAssertions="true"
    cacheTimeout="480";
};

module names must be unique (from the example above, BonitaAuthentication-1 is the module name). Therefore, remove the unecessary ones

The JAAS configuration file, jaas-standard.cfg, is sorted by sets of authentication modules. For Bonita, each set matches a tenant configuration and the name is prefixed with BonitaAuthentication-<tenant-id>`. Make sure there is a set of authentication modules for each tenant in your platform. For each tenant, set the CAS service to point to the application login page and set `casServerUrlPrefix to point to the CAS server.

  1. In the CasLoginModule configuration, check that the principalGroupName property is set to CallerPrincipal.
    This is required to retrieve the username from the Bonita application. Bonita uses the CAS LoginModule in the JASIG implementation, so see the CAS LoginModule section of the Jasig documentation for more information.

  2. Copy commons-logging-x.x.x.jar from BonitaSubscription-x.x.x/tools//BonitaSubscription-x.x.x-LDAP-Synchronizer/lib into the BUNDLE_HOME/server/lib directory.

  3. Update bonita-tenant-sp-custom.properties from setup/platform_conf/initial/tenant_template_engine/ if platform has not been initialized yet or setup/platform_conf/current/tenants/[TENANT_ID]/tenant_engine/ and setup/platform_conf/current/tenant_template_engine/.

    If the platform has already been initialized, every update to the configuration files under setup/platform_conf/current must be done using the setup tool:

    • setup pull

    • edit configuration file(s)

    • setup push

    • restart your server to apply the changes

    1. You must perform the following changes:

      • Comment out the authentication.service.ref.name=authenticationService line

      • Add this new line: authentication.service.ref.name=jaasAuthenticationService

    2. Optionally, to enable guest user access, uncomment this lines:

      authenticator.delegate=casAuthenticatorDelegate
authentication.delegate.cas.server.url.prefix=http://ip_address:port
authentication.delegate.cas.service.url=http://ip_address:port/bonita/loginservice

      Specify the relevant IP address and port number. Please note that Guest user access with this configuration has been validated with version 4.2 of CAS server and Bonita 7.10.1.

Configure the Bonita Runtime for CAS SSO

For your active tenant, edit authenticationManager-config.properties to enable the CASRemoteAuthenticationManager and its properties. Edit the authenticationManager-config.properties located in platform_conf/initial/tenant_template_portal for not initialized platform or platform_conf/current/tenant_template_portal and platform_conf/current/tenants/[TENANT_ID]/tenant_portal/.

If the platform has already been initialized, every update to the configuration files under setup/platform_conf/current must be done using the setup tool:

  • setup pull

  • edit configuration file(s)

  • setup push

  • restart your server to apply the changes

Make sure that auth.AuthenticationManager property is set to org.bonitasoft.console.common.server.auth.impl.jaas.cas.CASRemoteAuthenticationManagerImpl Uncomment Cas.serverUrlPrefix and Cas.bonitaServiceURL properties as shown below (specify the relevant IP addresses and ports):

#auth.AuthenticationManager = org.bonitasoft.console.common.server.auth.impl.standard.StandardAuthenticationManagerImplExt
#auth.AuthenticationManager = org.bonitasoft.console.common.server.auth.impl.oauth.OAuthAuthenticationManagerImplExt
# OAuth.serviceProvider = LinkedIn
# OAuth.consumerKey = ove2vcdjptar
# OAuth.consumerSecret = vdaBrCmHvkgJoYz1
# OAuth.callbackURL = http://ip_address:port/loginservice
auth.AuthenticationManager = org.bonitasoft.console.common.server.auth.impl.jaas.cas.CASRemoteAuthenticationManagerImpl
Cas.serverUrlPrefix = http://ip_address:port/cas
Cas.bonitaServiceURL = http://ip_address:port/bonita/apps/appDirectoryBonita
logout.link.hidden=true

Restart your server to apply the changes.

CAS SSO and Java client application

To enable a Java client application to access the engine using CAS authentication, the simplest way is to enable REST authentication on CAS server and have the Java client retrieve the ticket for the bonita service URL.
Then, use the LoginAPI with the java.util.Map having the ticket and service.

Cluster considerations and bonita webapp for Tomcat

If you are configuring Bonita and Tomcat in a cluster environment for CAS, there are some extra steps to do:

  1. Copy commons-logging-x.x.x.jar from BonitaSubscription-x.x.x/tools/BonitaSubscription-x.x.x-LDAP-Synchronizer/lib into the BUNDLE_HOME/server/lib directory.

  2. Remove the BUNDLE_HOME/server/webapps/bonita/WEB-INF/lib/commons-logging-x.x.x.jar file (if it is present).

Troubleshoot

To troubleshoot SSO login issues, you need to increase the log level to ALL in order for errors to be displayed in the log files (by default, they are not).

Configure logout behaviour

Bonita Runtime

If you are using CAS, when users log out of Bonita Runtime, they log out of CAS. Therefore they are logged out of all applications that are using the CAS service. To avoid this, you can hide the logout option of the Bonita Layout. To do this, set the logout.link.hidden=true option in authenticationManager-config.properties located in platform_conf/initial/tenant_template_portal for not initialized platform or platform_conf/current/tenant_template_portal and platform_conf/current/tenants/[TENANT_ID]/tenant_portal/.

If the platform has already been initialized, every update to the configuration files under setup/platform_conf/current must be done using the setup tool:

  • setup pull

  • edit configuration file(s)

  • setup push

  • restart your server to apply the changes

If this option is set, when users navigate away from the Bonita Applications, they are still logged in to CAS.

Bonita Engine

By default, logging out from Bonita Engine logs the user out of CAS. You can change this behavior by implementing your own Authentication Service.

Tenant administrator login

The Tenant administrator (also kwown as the tenant technical user) will always be able to log in without a CAS account. To log with the tenant administrator, use the standard Bonita Runtime login page accessible on http://<bundle host>:<port>/bonita/login.jsp.

Manage passwords

When you are using CAS, the password for a user is managed in your CAS system. However, when you create a user in Bonita Applications, specifying a password is mandatory. This password is ignored.

LDAP synchronizer and CAS

If you are using an LDAP service and the LDAP synchronizer to manage your user data, you can continue to do this and use CAS. The LDAP synchronizer user must be registered in CAS. Alternatively, the LDAP synchronizer could be run with the tenant technical user, because this bypasses the SSO login.

We recommend that you use LDAP as your master source for information, synchronizing the relevant information with your CAS server.

Single sign-on with CAS using the REST API

CAS is a browser-oriented protocol (based on http automatic redirection, cookies, forms, etc…​), therefore, we only have securized browser-oriented resources. This is why only a subset of pages are handled to be automatically SSO CAS-verified but not the whole web application.

The default AuthenticationFilter that manages CAS authentication applies only to the following pages:

  • /mobile/*

  • /portal.js/*

  • /apps/*

  • /services/*

REST API are not part of them, but if an HTTP session already exists thanks to cookies, REST API can be used.

The recommended way to authenticate in the Bonita Runtime, in order to use the REST API, is to use the CAS server REST API.
It allows to retrieve authentication tickets to authenticate in the Bonita Runtime.

For detailed information about the procedure to install Restful access on your CAS SSO server, see the following links:

All calls issued to get the TGT or ST are made to the CAS SSO server.

Getting the Ticket Granting Ticket (TGT)

The Ticket Granting Ticket is an exposed resource. It has a unique URL.

Request for a Ticket Granting Ticket Resource

Request URL

http://www.your_cas_server_url/cas/v1/tickets

Request Method

POST

Form Data

Username: walter.bates
Password: bpm
Response for a Ticket Granting Ticket Resource

Response

201 created

Location: http://www.your_cas_server_url/cas/v1/tickets/{TGT}

Take the TGT response and paste it in the url of the ST request, below

Getting the Service Ticket (ST)

Request for a Service Ticket

Request URL

http://www.your_cas_server_url/cas/v1/tickets/{TGT}

Request Method

POST

Form Data

service={form encoded parameter for the service url}

For instance, in a Bonita Runtime deployed on Tomcat bundle on a server with IP 192.168.1.9, service url can be http://192.168.1.9:8080/bonita/apps/appDirectoryBonita/home. Its form encoded value would be http%3A%2F%2F192.168.1.9%3A8080%2Fbonita%2Fapps%2FappDirectoryBonita%2Fhome.

Response for a Service (ST)

Response

200 OK

{ST}

Take the ST response and paste it in the url of the Bonita Engine login request, below

Logging into Bonita Engine with Rest API using the service ticket

Use the Bonita Runtime URL where the CAS AuthenticationFilter applies for authentication to work.

Prefer GET over POST to authenticate because experience has shown that in some server configuration, POST parameters cannot be retrieved in the CAS authentication web filter.
Authentication to Bonita Engine with GET

The form encoded parameter URL used as service in the previous step must be used as access point because it will be sent to the CAS server to check ticket validation.

Request URL

{service url}

Request Method

GET

HTTP Params

ticket={ST}
Authentication to Bonita Engine with POST

Use a Bonita Runtime SSO protected URL for this action.

Request URL

<bonita service url>

Request Method

POST

Form Data

service={form encoded parameter for the service url}&ticket={ST}
Response for a Service (ST)

Response

200 OK

You are now logged into Bonita Runtime and REST API calls will succeed.

Cookies must be enabled in REST client side for authentication to persist across REST API calls.
Therefore, calling web application root context may not work (e.g. /bonita by default) because session cookie seems not to be set on all web server configurations. Use a protected URL to authenticate to Bonita Runtime when using the ticket parameter with POST method.