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 Enterprise, Performance, Efficiency, and Teamwork editions only. |
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 Portal by clicking on a 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 portal 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 internaly to retrieve the server
and port
of the HTTP request.
Reverse proxy configuration:* use the ProxyPreserveHost property (Apache 2.0.31 or greater). |
Configure Bonita Engine and WildFly for CAS
The deploy bundle contains the files needed to use CAS with Bonita platform and a WildFly 10 application server.
They are contained in cas-3.3.1-module
.
You can use this folder to configure CAS for a platform deployed from the WildFly bundle or from the deploy bundle.
The cas-3.3.1-module
folder contains some jar files that are required.
It also contains a configuration file for the module, module.xml
, which defines the jar files to be loaded from the module itself and the dependencies of the module. For example:
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="org.jasig.cas">
<resources>
<resource-root path="cas-client-core-3.3.1.jar" />
<resource-root path="slf4j-api-1.7.1.jar" />
<resource-root path="slf4j-log4j12-1.7.1.jar" />
<resource-root path="log4j-1.2.15.jar" />
</resources>
<dependencies>
<system>
<paths>
<path name="org/xml/sax"/>
<path name="org/xml/sax/helpers"/>
<path name="javax/net/ssl"/>
<path name="javax/xml/parsers"/>
<path name="javax/security/auth/spi"/>
<path name="javax/security/auth/login"/>
<path name="javax/security/auth/callback"/>
<path name="javax/security/auth"/>
</paths>
</system>
</dependencies>
</module>
For a standard installation, it is not necessary to modify this file.
To configure Bonita Engine for CAS:
-
If you do not already have it, download the Subscription edition deploy zip from the customer portal.
-
Add the CAS module. To do this, copy
BonitaSubscription-x.x.x-deploy/cas-x.x.x-module/org
toWILDFLY_HOME/server/modules
to merge the CAS module with the existing modules. -
Make the CAS module global so that it can be used by any application. To do this, edit
WILDFLY_HOME/setup/wildfly-templates/standalone.xml
and change the definition of theee
subsystem to the following:<subsystem xmlns="urn:jboss:domain:ee:1.0"> <global-modules> <module name="org.jasig.cas" slot="main"/> </global-modules> </subsystem>
-
Edit
WILDFLY_HOME/setup/wildfly-templates/standalone.xml
and add the BonitaAuthentication module. Right after the opening<security-domains>
tag, insert these lines (specifying the relevant IP addresses and port numbers):<security-domain name="BonitaAuthentication-1"> <authentication> <login-module code="org.jasig.cas.client.jaas.CasLoginModule" flag="required"> <module-option name="ticketValidatorClass" value="org.jasig.cas.client.validation.Cas20ServiceTicketValidator"/> <module-option name="casServerUrlPrefix" value="http://cas_ip_address:cas_port/cas"/> <module-option name="tolerance" value="20000"/> <module-option name="service" value="http://cas_ip_address:cas_port/bonita/loginservice"/> <module-option name="defaultRoles" value="admin,operator"/> <module-option name="roleAttributeNames" value="memberOf,eduPersonAffiliation"/> <module-option name="principalGroupName" value="CallerPrincipal"/> <module-option name="roleGroupName" value="Roles"/> <module-option name="cacheAssertions" value="true"/> <module-option name="cacheTimeout" value="480"/> </login-module> </authentication> </security-domain>
module names must be unique (from the example above, BonitaAuthentication-1 is the module name). Therefore, remove the unecessary ones
-
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. -
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
|
-
Remove the comment flags from these lines:
authentication.service.ref.name=jaasAuthenticationService
-
Optionally, to enable anonymous user to access a process, 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.
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 propertyjava.security.auth.login.config
in the Tomcat startup script to point to the JAAS configuration file,TOMCAT_HOME/server/conf/jaas-standard.cfg
.For example, on Linux, edit
TOMCAT_HOME/setup/tomcat-templates/setenv.sh
, uncomment the line that definesSECURITY_OPTS
, and insert the variableSECURITY_OPTS
in the lineCATALINA_OPTS=..
.The
TOMCAT_HOME/server/conf/jaas-standard.cfg
file contains the following (replaceip_address:port
with the relevant IP addresses and port numbers, in two places):BonitaAuthentication-1 { org.jasig.cas.client.jaas.CasLoginModule required ticketValidatorClass="org.jasig.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
cas-client-core-x.x.x.jar
fromBonitaSubscription-x.x.x-deploy/cas-x.x.x-module/org/jasig/cas/main
into theTOMCAT_HOME/server/lib
directory. -
Copy
commons-logging-x.x.x.jar
fromBonitaSubscription-x.x.x-deploy/BonitaSubscription-x.x.x-LDAP-Synchronizer/BonitaSubscription-x.x.x-LDAP-Synchronizer/lib
into theTOMCAT_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 |
-
Remove the comment flags from these lines:
authentication.service.ref.name=jaasAuthenticationService
-
Optionally, to enable anonymous user to access a process, 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.
Configure the Bonita Portal for CAS SSO
-
For each tenant, edit
authenticationManager-config.properties
to enable the CASRemoteAuthenticationManager and its properties. Edit theauthenticationManager-config.properties
located inplatform_conf/initial/tenant_template_portal
for not initialized platform orplatform_conf/current/tenant_template_portal
andplatform_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/portal/homepage
logout.link.hidden=true
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-deploy/BonitaSubscription-x.x.x-LDAP-Synchronizer/BonitaSubscription-x.x.x-LDAP-Synchronizer/lib
into theTOMCAT_HOME/server/lib
directory. -
Remove the
WEB-INF/lib/commons-logging-x.x.x.jar
file from theTOMCAT_HOME/server/webapps/bonita.war
. -
Remove the
TOMCAT_HOME/server/webapps/bonita/WEB-INF/lib/commons-logging-x.x.x.jar
file (if it is present).
Troubleshoot
To troubleshoote 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 Portal
If you are using CAS, when users log out of Bonita Portal, 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 portal.
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 Portal, 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 whitout a CAS account. To log with the tenant administrator, use the standard Bonita Portal 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 Portal, 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:
-
/portal
-
/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 to Bonita Portal to use the REST API is to use the CAS server REST API.
It allows to retrieve authentication tickets to authenticate to Bonita Portal.
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 Portal deployed on Tomcat bundle on a server with IP 192.168.1.9
, service url
can be http://192.168.1.9:8080/bonita/portal/homepage
. Its form encoded value would be http%3A%2F%2F192.168.1.9%3A8080%2Fbonita%2Fportal%2Fhomepage
.
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 a Bonita Portal 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 Portal 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 Portal and REST API calls will succeed.
Cookies must be enabled in REST client side for authentication to persist across REST API calls. |