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 |
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.
-
In the
CasLoginModule
configuration, check that theprincipalGroupName
property is set toCallerPrincipal
.
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. -
Copy
commons-logging-x.x.x.jar
fromBonitaSubscription-x.x.x/tools//BonitaSubscription-x.x.x-LDAP-Synchronizer/lib
into theBUNDLE_HOME/server/lib
directory. -
Update
bonita-tenant-sp-custom.properties
fromsetup/platform_conf/initial/tenant_template_engine/
if platform has not been initialized yet orsetup/platform_conf/current/tenants/[TENANT_ID]/tenant_engine/
andsetup/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 thesetup
tool:-
setup pull
-
edit configuration file(s)
-
setup push
-
restart your server to apply the changes
-
You must perform the following changes:
-
Comment out the
authentication.service.ref.name=authenticationService
line -
Add this new line:
authentication.service.ref.name=jaasAuthenticationService
-
-
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
|
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 autentication, 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:
-
Copy
commons-logging-x.x.x.jar
fromBonitaSubscription-x.x.x/tools/BonitaSubscription-x.x.x-LDAP-Synchronizer/lib
into theBUNDLE_HOME/server/lib
directory. -
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
|
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 |
|
Request Method |
POST |
Form Data |
Username: walter.bates |
Response for a Ticket Granting Ticket Resource
Response |
201 created |
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 |
|
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 |
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 |
|
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 |
|
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. |