Single sign-on integration using Java servlet for Tomcat is deprecated and will be removed in future releases. Please consider implementing single sign-on using SAML or Atlassian Crowd OpenID instead.

This topic describes how to establish single sign-on between an SSO server and Collaborator using Java servlet for Tomcat. To learn general principles of how single sign-on operates, see Single Sign-On.

Below we describe how to establish single sign-on between Collaborator and Apereo Central Authentication Service (CAS). Integration with single sign-on servers of other vendors is performed in a similar manner.

Enable HTTPS Connections

Most Single Sign-On servers use HTTPS connections, thus you will likely need to enable it for Collaborator server as well. For instructions, please see Configure HTTPS. Do not forget to restart the Collaborator server to apply changes.

Install SSO Server and Client Components

In Apereo Central Authentication Service, SSO server component is implemented as a Java servlet, and SSO clients are provided for different platforms and technologies (Java, .NET, PHP, Python and so on). Since Collaborator is a Java application, we will use Java CAS client.

Notes:

To simplify the example, we will install both CAS server and CAS client on the same instance of Tomcat server.
Not all versions of CAS server and CAS client are compatible with each other. For example, CAS server 4.0 does not work with CAS client 3.3. In this integration, will use CAS server 3.5.2 and CAS client 3.1.12.

To install and prepare the necessary software:

Download the CAS server archive and unzip it to temporary folder.
Copy the modules/cas-server-webapp-3.5.2.war file to the <Collaborator Server>/tomcat/webapps folder.
Download the CAS client archive and unzip it to another temporary folder.
Copy all files from the cas-client-3.1.12/modules/ folder to the <Collaborator Server>/tomcat/webapps/ROOT/WEB-INF/lib folder.

Add Filters to Collaborator Tomcat Server

In this step, we will add several filters to Tomcat server. These filters would detect unauthenticated users, redirect them to SSO server, validate users, and perform single logout. To learn more about filter configuration, see The Essentials of Filters on the Oracle website.

Open the <Collaborator Server>/tomcat/webapps/ROOT/WEB-INF/web.xml file and append the following lines to it:

<filter>
  <filter-name>CAS Authentication Filter</filter-name>
  <filter-class>org.jasig.cas.client.authentication.AuthenticationFilter</filter-class>
  <init-param>
    <param-name>casServerLoginUrl</param-name>
    <param-value>https://yourcollabserver:8443/cas-server-webapp-3.5.2/login</param-value>
  </init-param>
  <init-param>
    <param-name>serverName</param-name>
    <param-value>https://yourcollabserver:8443</param-value>
  </init-param>
  <init-param>
    <param-name>gateway</param-name>
    <param-value>false</param-value>
  </init-param>

</filter>
<filter-mapping>
  <filter-name>CAS Authentication Filter</filter-name>
  <url-pattern>/ui/*</url-pattern>
  <url-pattern>/go/*</url-pattern>
</filter-mapping>

<filter>
  <filter-name>CAS Validation Filter</filter-name>
  <filter-class>org.jasig.cas.client.validation.Cas20ProxyReceivingTicketValidationFilter</filter-class>
  <init-param>
    <param-name>casServerUrlPrefix</param-name>
    <param-value>https://yourcollabserver:8443/cas-server-webapp-3.5.2/</param-value>
  </init-param>
  <init-param>
    <param-name>serverName</param-name>
    <param-value>https://yourcollabserver:8443</param-value>
  </init-param>

</filter>
<filter-mapping>
  <filter-name>CAS Validation Filter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

<filter>
  <filter-name>CAS HttpServletRequest Wrapper Filter</filter-name>
  <filter-class>org.jasig.cas.client.util.HttpServletRequestWrapperFilter</filter-class>
</filter>
  <filter-mapping>
  <filter-name>CAS HttpServletRequest Wrapper Filter</filter-name>
</filter-mapping>

<filter>
  <filter-name>CAS Single Sign Out Filter</filter-name>
  <filter-class>org.jasig.cas.client.session.SingleSignOutFilter
</filter-class>
</filter>
<filter-mapping>
  <filter-name>CAS Single Sign Out Filter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>
<listener>
  <listener-class>org.jasig.cas.client.session.SingleSignOutHttpSessionListener</listener-class>
</listener>

Tip: Remember to replace yourcollabserver with the actual URL of your Collaborator server

Configure Collaborator Server VM Options

In this step, we need to change the VM options of the server to enable SSL connections between the Collaborator and CAS servers and to specify the logout redirect URL.

Open the <Collaborator Server>/ccollab-server.vmoptions file and add the following lines to it:

-Djavax.net.ssl.keyStore=<Collaborator Server>/tomcat/conf/collab.ks
-Djavax.net.ssl.keyStorePassword=<collab-keystore-password>
-Djavax.net.ssl.trustStore=<Collaborator Server>/tomcat/conf/cacerts
-Djavax.net.ssl.trustStorePassword=<truststore-password>
-Dsmartbear.ccollab.sso.logout.redirect.url=https://yourcollabserver:8443/cas-server-webapp-3.5.2/logout

The latter VM option specifies the URL to which users will be redirected when they click Logout in the Collaborator web interface.

Alternatively, you can remove the Logout link from Collaborator web interface by setting the VM option as follows:

-Dsmartbear.ccollab.sso.logout.redirect.url=hide

In that case, users would manually perform logging out from the SSO server.

Restart the Collaborator server to apply changes in VM options.

Configure CAS Properties for Logout Requests

In this step, we will configure how CAS server should handle logout requests.

Open the Collaborator Web Client.
Open the <Collaborator Server>/tomcat/webapps/cas-server-webapp-3.5.2/WEB-INF/ folder and wait until a file named cas.properties is created in this folder. The cas.properties file is deployed from the cas-server-webapp-3.5.2.war web application archive, so it can take some time till it is created.
Open the <Collaborator Server>/tomcat/webapps/cas-server-webapp-3.5.2/WEB-INF/cas.properties file and set the value of the cas.logout.followServiceRedirects property to true:

# Specify whether CAS should redirect to the specified service parameter on /logout requests
cas.logout.followServiceRedirects=true

Restart Collaborator Server

To apply all changes, restart the Collaborator server.

Known Issues With CAS Server

Currently, CAS server settings only allow to have coinciding login/password values. That is, the password must have the same value as the login.
Because of cookie handling issues, the CAS server single logout functionality may not work correctly with Collaborator web clients. Namely, logging out from Collaborator web client will not terminate a session on a CAS server. As a result, the subsequent attempts to open any of Collaborator web client /ui pages will not be redirected to CAS server login page but will open the Collaborator standard login page instead. This issue does not affect /go pages of web client, however major part of Collaborator web client pages are /ui pages and are affected. To avoid the problem:
1. Open the <Collaborator Server>/tomcat/webapps/cas-server-webapp-3.5.2/WEB-INF/spring-configuration/ticketGrantingTicketCookieGenerator.xml file and set the value of the p:cookieSecure property to false:
  
  <bean id="ticketGrantingTicketCookieGenerator" class="org.jasig.cas.web.support.CookieRetrievingCookieGenerator"
  p:cookieSecure="false"
  p:cookieMaxAge="-1"
  p:cookieName="CASTGC"
  p:cookiePath="/cas" />
2. Log out from the Collaborator web client and CAS server.
3. Clear browser cookies.
Alternatively, you can disable the Logout link in the Collaborator web interface and perform logout from the CAS server. See above for instructions.

Configure Single-Sign-On via Java Servlet