= CAS SSO configuration
:description: 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.

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.

[NOTE]
====
For Subscription 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.

NOTE: 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.

[NOTE]
====

The method https://docs.oracle.com/javaee/7/api/javax/servlet/http/HttpServletRequest.html#getRequestURL--[`getRequestURL ot HttpServletRequest`] is used internally to retrieve the `server` and `port` of the HTTP request.
====


=== Example
*Reverse proxy configuration:*  use the http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypreservehost[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 https://tomcat.apache.org/connectors-doc/common_howto/proxy.html[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, xref:bonita-bpm-platform-setup.adoc[`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):
+

[source,conf]
----
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";
};
----

[WARNING]
====
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 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 https://wiki.jasig.org/display/CASC/JAAS+Integration[Jasig documentation] for more information.
. Copy `cas-client-core-x.x.x.jar` from `BonitaSubscription-x.x.x/tools/cas-x.x.x-module/org/jasig/cas/main` into the `BUNDLE_HOME/server/lib` directory.
. 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.
. 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/`.
+
[NOTE]
====
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`
====
+
 .. 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 xref:guest-user.adoc[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.

[discrete]
==== Configure the Bonita Portal for CAS SSO

. For each 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/`.
[NOTE]
====

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`
====

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):

[source,properties]
----
#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
----

[discrete]
==== 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 https://apereo.github.io/cas/4.0.x/protocol/REST-Protocol.html[REST authentication on CAS server] and have the Java client <<cas-rest-api,retrieve the `ticket` for the bonita `service` URL>>. +
Then, use the https://javadoc.bonitasoft.com/api/{javadocVersion}/org/bonitasoft/engine/api/LoginAPI.html#login(java.util.Map)[`LoginAPI`] with the `java.util.Map` having the `ticket` and `service`.

[discrete]
==== 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` from `BonitaSubscription-x.x.x/tools/BonitaSubscription-x.x.x-LDAP-Synchronizer/lib` into the `BUNDLE_HOME/server/lib` directory.
. Remove the `WEB-INF/lib/commons-logging-x.x.x.jar` file from the `BUNDLE_HOME/server/webapps/bonita.war`.
. 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 xref:logging.adoc[log level] to `ALL` in order for errors to be displayed in the log files (by default, they are not).

== Configure logout behaviour

[discrete]
==== 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/`.
[NOTE]
====

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`
====

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

[discrete]
==== 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 xref:tenant_admin_credentials.adoc[Tenant administrator] (also known 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 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 xref:ldap-synchronizer.adoc[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.

[#cas-rest-api]

== 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 secured 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.

[#restricted_cas_urls]
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:

* http://apereo.github.io/cas/4.2.x/index.html[CAS SSO RESTful API]
* xref:rest-api-overview.adoc[Bonita REST API]

[NOTE]
====

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

[discrete]
==== Getting the Ticket Granting Ticket (TGT)

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

[discrete]
===== *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
|===

[discrete]
===== *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

[discrete]
==== Getting the Service Ticket (ST)

[discrete]
===== *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 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`.

[discrete]
===== *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

[discrete]
==== Logging into Bonita Engine with Rest API using the service ticket

Use a *Bonita Portal* URL where the <<restricted_cas_urls,CAS AuthenticationFilter applies>> for authentication to work.

[WARNING]
====

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.
====

[discrete]
===== *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}
|===

[discrete]
===== *Authentication to Bonita Engine* with POST

Use a Bonita Portal SSO protected URL for this action.

|===
|  |

| Request URL
| `<bonita portal url>`

| Request Method
| POST

| Form Data
| service={form encoded parameter for the service url}&ticket=\{ST}
|===

[discrete]
===== *Response for a Service (ST)*

|===
|  |

| Response
| 200 OK
|===

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

[WARNING]
====

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 Portal when using the ticket parameter with POST method.*
====
