SAML 2.0 based single sign-on and logout for web applications deployed in Apache Tomcat-Part Two
Using WSO2's Apache Tomcat extension for SAML 2.0 based single sign-on and logout
This article provides a detailed, practical guide on configuring WSO2’s Apache Tomcat extension for SAML 2.0 based single sign-on and logout alongside WSO2 Identity Server, acting as the identity provider.
The GitHub source repository for the discussed Tomcat extension provides a good quick start, practical guide on configuring this extension. But it was understood that a detailed description especially on the associated configurations, workflow and etc. was missing. Thus, it was realized that this article would be a valuable contribution.
Note: Please see part one of this article, for a concise introduction to single sign-on and logout, with directions to appropriate reference guides, where necessary.
Configuration files
It was understood that a thorough understanding on the configurations involved will be vital especially, when it is needed to manipulate them according to our needs. Hence, before moving on to the practical guide, it was felt that a brief introduction to the files involved during the configuration process was necessary.
Throughout this article, the following assumption has been made.
— Root directory of the unpacked Apache Tomcat distribution as the <CATALINA_HOME>.
- Apache Tomcat specific configuration files
- <CATALINA_HOME>/conf/server.xml — This is Tomcat’s main configuration file. In the current context, this file will be used to configure Tomcat components such as, the discussed extension Valve, server life-cycle Listener for loading WSO2 specific configurations at server level and SSL/TLS Connector which needs to be up and running during server startup.
- <CATALINA_HOME>/conf/context.xml — This file is used to configure the context/web application life-cycle Listener for loading WSO2 specific configurations at context/web application level.
This reference guide provides a more detailed understanding of Apache Tomcat’s primary configuration files and concepts.
- WSO2 specific configuration files
- <CATALINA_HOME>/conf/wso2/wso2as.xml — This file acts as a server descriptor for WSO2 specific configurations for SAML 2.0 single sign-on and logout. The configurations defined in this file are configurable only at server level and cannot be overridden per context/web application. The server life-cycle Listener required to read these configurations at Tomcat server startup is configured at <CATALINA_HOME>/conf/server.xml file (as mentioned before).
- <CATALINA_HOME>/conf/wso2/wso2as-web.xml — This file acts as a context/web application descriptor for WSO2 specific configurations for SAML 2.0 single sign-on and logout. This global context descriptor configurations are common to all deployed contexts/web applications. The configurations defined in this file are configurable at context level, as well. This means that any defined configuration in the global context descriptor can be overridden at context level, by introducing a context level descriptor (i.e. <CATALINA_HOME>/webapps/<context>/META-INF/wso2as-web.xml). The context/web application life-cycle Listener for loading these configurations before starting the context/web application, is configured at <CATALINA_HOME>/conf/context.xml file (as mentioned before).
A practical guide to configuring SAML 2.0 based single sign-on and logout
This section provides a detailed explanation on configuring SAML 2.0 based single sign-on and logout using the discussed Tomcat extension in Apache Tomcat version 9.0.1 (latest at the time of writing this article) with WSO2 Identity Server version 5.3.0. The steps are as follows:
- Download and unpack Apache Tomcat and WSO2 Identity Server.
As mentioned earlier, the web application resources or service providers will be deployed in the Apache Tomcat web container and WSO2 Identity Server will act as the identity provider, which enables single sign-on and logout.
- Checkout the source code and perform a Maven build.
— Clone the source code.
git clone https://github.com/wso2-extensions/tomcat-extension-samlsso.gitLet’s assume, the root directory of the cloned project as <PROJECT_ROOT>.
— Move to the root directory of the cloned project (<PROJECT_ROOT>) and build it using Apache Maven.
cd <PROJECT_ROOT>mvn clean install
- Copy WSO2 specific configuration files to Apache Tomcat.
Copy the <PROJECT_ROOT>/modules/samlsso/src/main/Resources/wso2 directory to <CATALINA_HOME>/conf directory.
cp -avr <PROJECT_ROOT>/modules/samlsso/src/main/Resources/wso2 <CATALINA_HOME>/conf- Configure Apache Tomcat server level configurations.
Make the following changes to <CATALINA_HOME>/conf/server.xml.
— Configure SAML 2.0 single sign-on and logout Apache Tomcat Valve. By default, SAML 2.0 single sign-on and logout Tomcat Valve has not been configured under any of the Host containers. Therefore, add the following line under default ‘localhost’ Tomcat Host container tag.
<Valve className="org.wso2.appserver.webapp.security.saml.SAML2SSOValve"/>— Configure Apache Tomcat server life-cycle Listener for loading WSO2 specific, server level configurations. For this purpose, add the following line under the Server tag.
<Listener className="org.wso2.appserver.configuration.listeners.ServerConfigurationLoader"/>— Configure SSL/TLS Apache Tomcat Connector. To setup this Connector in order to activate HTTPS within Tomcat, add the following line under ‘Catalina’ Tomcat Service tag.
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" maxThreads="150" SSLEnabled="true" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" keystoreFile="<CATALINA_HOME>/conf/wso2/wso2carbon.jks" keystorePass="wso2carbon" />Note: The attribute keystoreFile points to the default WSO2 specific key store file available under the directory containing WSO2 specific configuration files, copied earlier.
Make sure that the following WSO2 key store configurations in the <CATALINA_HOME>/conf/wso2/wso2as.xml server descriptor have been configured, as follows:
<KeyStore>
<Location>${catalina.base}/conf/wso2/wso2carbon.jks</Location>
<Type>JKS</Type>
<Password>wso2carbon</Password>
<KeyAlias>wso2carbon</KeyAlias>
<KeyPassword>wso2carbon</KeyPassword>
</KeyStore>As you may have already observed, the following configurations under KeyStore tag in WSO2 specific server descriptor file and SSL/TLS Tomcat Connector attributes should match.
- Configure web application level configurations.
Before proceeding forward, we need to enable an Apache Tomcat context/web application life-cycle Listener for loading WSO2 specific, context/web application level configurations. Open the file <CATALINA_HOME>/conf/context.xml and add the following line under Context tag.
<Listener className="org.wso2.appserver.configuration.listeners.ContextConfigurationLoader"/>- Add libraries and web applications.
— Copy <PROJECT_ROOT>/modules/samlsso/target/samlsso-1.0.1-SNAPSHOT-fat.jar artifact to <CATALINA_HOME>/lib. This fat Java Archive file contains SAML 2.0 single sign-on and logout Apache Tomcat Valve implementation, the above discussed Tomcat Listener implementation class files and their dependency class files.
cp <PROJECT_ROOT>/modules/samlsso/target/samlsso-1.0.1-SNAPSHOT-fat.jar <CATALINA_HOME>/lib/— Copy <PROJECT_ROOT>/samples/sso-sample-apps/bookstore-app/target/bookstore-app.war and <PROJECT_ROOT>/samples/sso-sample-apps/musicstore-app/target/musicstore-app.war files into <CATALINA_HOME>/webapps. These refer to the sample web applications which can be used to quickly demonstrate the single sign-on and logout processes.
cp <PROJECT_ROOT>/samples/sso-sample-apps/bookstore-app/target/bookstore-app.war <CATALINA_HOME>/webapps/cp <PROJECT_ROOT>/samples/sso-sample-apps/musicstore-app/target/musicstore-app.war <CATALINA_HOME>/webapps/
- Configure the service providers.
Here, a web application deployed in Apache Tomcat which is configured to use single sign-on (and logout, if desired) acts as a service provider. Every web application for which you expect to enable SAML 2.0 single sign-on (and logout, if desired) has to be registered at the identity provider, as a service provider.
Here, we will look at registering the bookstore-app sample web application, as a service provider.
— Login to the WSO2 Identity Server management console.
— Choose Main tab from the sidebar.
— Choose Add from Service Providers. Then enter the Service Provider Name as ‘bookstore-app’ (any identifier for the service provider, of your choice) and choose Register.
— Then choose Inbound Authentication Configuration -> SAML2 Web SSO Configuration -> Configure.
— Register New Service Provider -> Manual Configuration (Select Mode) -> configure the service provider.
Here, perform the following tasks:
- Enter ‘bookstore-app’ as the Issuer ID. For any web application, Issuer ID has to be the name of the context/web application in Tomcat (since, the Tomcat Valve builds up the Issuer ID based on the name of the context/web application).
- Enter ‘https://localhost:8443/bookstore-app/acs’ in the Assertion Consumer URLs field and click Add. Make sure the entered URL remains as the Default Assertion Consumer URL.
- Select ‘wso2carbon’ for the Certificate Alias.
- Select the Enable Response Signing, Enable Signature Validation in Authentication Requests and Enable Single Logout check boxes.
- Click Update in the Register New Service Provider window -> OK -> Update in the Service Providers window.
The above steps would successfully register the bookstore-app sample web application at the identity provider.
Plus, we need to ensure the following are appropriately configured at the global context descriptor <CATALINA_HOME>/conf/wso2/wso2as-web.xml.
- Set enable-sso to true. This enables SAML 2.0 single sign-on for all deployed web applications, by default.
- Set enable-slo to true. This enables SAML 2.0 single logout for all deployed web applications, by default.
Make sure that the following WSO2 configurations in the <CATALINA_HOME>/conf/wso2/wso2as-web.xml context descriptor have been configured, as follows:
<saml2-single-sign-on>
<enable-sso>true</enable-sso>
<http-binding>urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST</http-binding>
<consumer-url-postfix>acs</consumer-url-postfix>
<enable-slo>true</enable-slo>
<slo-url-postfix>logout</slo-url-postfix>
<enable-assertion-encryption>false</enable-assertion-encryption>
<enable-assertion-signing>true</enable-assertion-signing>
<enable-request-signing>true</enable-request-signing>
<enable-response-signing>true</enable-response-signing></saml2-single-sign-on>As you may have realized already, we need to ensure that the WSO2 Identity Provider service provider configurations should match with the configurations defined in the WSO2 specific context/web application descriptor, discussed in section Configuration files. The following table shows a mapping of these configurations.
In addition, make sure that the KeyAlias under KeyStore in the <CATALINA_HOME>/conf/wso2/wso2as.xml server descriptor matches with the Certificate Alias configured, when registering the service provider at the identity server.
For this demonstration, register the musicstore-app sample web application, using the same steps followed to configure the bookstore-app sample web application.
- Configure the identity provider.
Currently, the identity provider is not configurable per web application. Thus, the identity provider configuration will be at server level.
First, let’s configure the identity provider at the WSO2 Identity Server. For this demonstration, the Resident Identity Provider has been used.
— Choose Main tab from the sidebar.
— Choose Resident under Identity Providers.
— Make sure the Resident Realm Configuration and the Inbound Authentication Configuration -> SAML2 Web SSO Configuration have been configured as follows:
The following configurations in the WSO2 server descriptor <CATALINA_HOME>/conf/wso2/wso2as.xml under the SAML2SingleSignOn tag should match with the configurations of the Resident Identity Provider. The configuration mappings in the server descriptor and at the WSO2 Identity Server Resident Identity Provider have been shown in the following table.
SAML 2.0 single sign-on and logout in action
Now, let’s see how SAML 2.0 single sign-on and logout works with the sample Tomcat web applications which were deployed, earlier.
- Start the Apache Tomcat web container.
./<CATALINA_HOME>/bin/catalina.sh run- Open your favorite web browser and try accessing either one or both of the sample web applications, bookstore-app or musicstore-app. Here, the bookstore-app has been accessed, first. Use either one of the following URLs for this purpose:
— http://localhost:8080/bookstore-app: Access through Apache Tomcat’s HTTP Connector. Since, the HTTP Connector cannot handle SSL/TLS requests, this request will be redirected to the previously configured SSL/TLS Apache Tomcat Connector.
— https://localhost:8443/bookstore-app: SSL/TLS request directly addressed by the SSL/TLS Apache Tomcat Connector.
You will encounter the following WSO2 Identity Server sign-in web page.
- Enter your WSO2 Identity Server credentials.
- If you are successfully authenticated, you will be redirected to the index web page of the originally accessed web application resource (in this case, the bookstore-app).
- Try accessing the other web application (in this case, the musicstore-app web application). If you were successfully authenticated in the previous step, you will find yourself able to access the web application without needing any additional authentication.
Thus, you have successfully experienced single sign-on, in action.
- Now choose to logout from any one of the web applications. Let’s choose to logout from the musicstore-app web application (click Logout button at the bottom left-hand side). If successful, you will encounter the following:
- Try accessing the other web application(s), in this case the bookstore-app web application. If you had successfully logged out from the previous web application, then you will be redirected to the WSO2 Identity Server sign-in web page.
Here, you have successfully experienced single logout, in action.
Tips on web application development
This section is focused on providing a few, trivial tips on developing web applications, which are intended to benefit from the discussed Tomcat extension. The source code of the sample web applications, which were deployed during this demonstration can be found from here.
- As you may have observed, every sample Java web application deployed above contains a Java servlet implementation, which addresses the URL pattern ‘/acs’ (e.g. check bookstore-app web application web.xml file). Thus, it can be considered a good practice to address the URL pattern in your web application, which is reminiscent to the consumer-url-postfix, which was configured in the WSO2 specific context/web application descriptor.
- Further, the README.md guide of every sample web application discussed above provides a concise description of the content of each web application (e.g. README.md of bookstore-app web application). It is recommended to follow a similar template as that of these sample web applications, when developing web applications intended to be used with the discussed extension.
Conclusion
It is believed that this article provided a detailed, practical guide on using the WSO2’s Apache Tomcat extension for SAML 2.0 based single sign-on and logout, giving its readers a better understanding of the associated configurations and workflow.