Single-sign-on is one of the key features of the WSO2 Identity Server that enables users to access multiple applications using the same set of credentials. Additionally, the user can access all these applications without having to log into each and every one of them individually. So, if users log into application A, for example, they would automatically have access to application B as well for the duration of that session without having to re-enter their credentials.
The profiles specification for Security Assertion Markup Language 2.0 (SAML 2.0) defines single sign-on based on a web browser. This topic provides instructions on how to use the sample available in the WSO2 Identity Server to demonstrate how to configure SSO using SAML 2.0 with a sample service provider.
Configuring the SSO web application
To start off, you must obtain and configure the single sign-on sample. The following steps provide instructions on how to do this.
Use SVN to check out the source from the repository location that contains the single sign-on sample.
svn co http://svn.wso2.org/repos/wso2/carbon/platform/branches/turing/products/is/5.0.0/modules/samples/sso/
Remove the parent entry in the pom.xml file that comes along with the sample. The contents of the pom.xml file will look similar to the following.
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> <groupId>org.wso2.identity</groupId> <version>5.0.0</version> <modelVersion>4.0.0</modelVersion> <artifactId>wso2is-identity-samples-sso</artifactId> <packaging>pom</packaging> <name>Identity Server : SSO Samples</name> <modules> <module>SSOAgentSample</module> </modules> </project>
Alternatively, you can simply replace the existing pom.xml file with the sample pom.xml file.
In your command line, navigate to
<SAMPLE_HOME>/sso/SSOAgentSample
in the folder you checked out and build the sample using the following command. You must have Apache Maven installed to do this (see Installation Prerequisites for the appropriate version to use).mvn clean install
After successfully building the sample, a .war file named
travelocity.com
can be found inside the<HOME>/sso/SSOAgentSample/
target
folder. Deploy this sample web app on a web container. To do this, use the Apache Tomcat server.Since this sample is written based on Servlet 3.0 it needs to be deployed on Tomcat 7.x.
Use the following steps to deploy the web app in the web container:
- Stop the Apache Tomcat server if it is already running.
- Copy the
travelocity.war
file to the<TOMCAT_HOME>/webapps
folder. - Start the Apache Tomcat server.
Tip: If you wish to change properties like the issuer ID, consumer URL and IdP URL, you can edit the travelocity.properties
file found inside the travelocity.com/WEB-INF/classes
directory. This sample uses the following default values.
Properties | Description |
---|---|
SAML.IssuerID=travelocity.com | A unique identifier for this SAML 2.0 Service Provider application |
SAML.ConsumerUrl=http://localhost:8080/travelocity.com/home.jsp | The URL of the SAML 2.0 Assertion Consumer |
SAML.IdPUrl=https://localhost:9443/samlsso | The URL of the SAML 2.0 Identity Provider |
If you edit the travelocity.properties file, you must restart the Apache Tomcat server for the changes to take effect.
Now that the web app is successfully deployed on a web container; the next step is to configure WSO2 Identity Server as the identity provider.
Configuring WSO2 Identity Server as an identity provider
- Start the Identity Server and access the management console using https://localhost:9443/carbon/
- Log in to the Identity Server using default administrator credentials (the username and password are both "admin").
- In the management console found on the left of your screen, navigate to the Main menu and click Add under Service Provider.
- Expand the Inbound Authentication Configuration section and then expand SAML2 Web SSO Configuration.
- Click Configure. A form appears. Register the new service provider by providing the following values.
Issuer: travelocity.com
This value should be same as the
SAML.IssuerID
value specified inside thetravelocity.com/WEB-INF/classes/travelocity.properties
file.Assertion Consumer URL:
http://localhost:8080/travelocity.com/home.jsp
This value should be same as the
SAML.ConsumerUrl
value mentioned inside thetravelocity.com/WEB-INF/classes/travelocity.properties
file.- NameID format: Enter the default value here (i.e.,
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
) - Use fully qualified username in the NameID: Set this as true by selecting the checkbox
- Enable Response Signing: Set this as true by selecting the checkbox
- Enable Assertion Signing: Set this as true by selecting the checkbox
- Enable Signature Validation in Authentication Requests and Logout Requests: Set this as true
- Certificate Alias: Select wso2carbon here
- Enable Single Logout: Set this as true by selecting the checkbox
- After providing above values click Register.
After successfully registering the service provider, log out from management console. You have now configuring Identity Server as the identity provider. The next step is to run the sample.
Running the sample
- Visit
http://localhost:8080/travelocity.com
. You are directed to the following page:
- Since you need to use SAML2 for this sample, click the first link, i.e., Click here to login with SAML from Identity Server. You are redirected to the Identity Server for authentication.
- Enter the default admin credentials (admin/admin).
- Now you are logged in and you can see the home page of the travelocity.com app.
If you need to view the SAML request and response, please add the following debug log to the
log4j.properties
file found inside<PRODUCT_HOME>/repository/conf
.log4j.logger.org.wso2.carbon.identity=DEBUG
- Since single log out is enabled, if you click the logout button in the travelocity.com home page, you will successfully log out.