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.
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.
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.
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.
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:
|Tip:||Remember to replace
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:
The latter VM option specifies the URL to which users will be redirected when they click Logout in the Collaborator web interface.
In that case, users would manually perform logging out from the SSO server.
Restart the Collaborator server to apply changes in VM options.
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
To apply all changes, restart the Collaborator 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:
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
Log out from the Collaborator web client and CAS server.
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.