Configuring Single Sign-On

Single-sign-on is a key feature 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. For instance, if users log into application A, 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 configure SSO using SAML 2.0 with a sample service provider.

See the following topics for instructions on how to configure the sample with the WSO2 Identity Server.

Configuring the SSO web application

To obtain and configure the single sign-on sample, follow the steps below.

1. You can check out the repository of the SSO sample from GitHub. Follow the instructions here to checkout the folder. 

2. Completely replace the contents of the pom.xml file that is in the <is-samples>/modules/samples/sso directory with the following code snippet.

   <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.1.0</version> <modelVersion>4.0.0</modelVersion> <artifactId>wso2is-identity-samples-sso</artifactId> <packaging>pom</packaging> <name>Identity Server : SSO Samples</name> <modules> <module>sso-agent-sample</module> </modules> </project>

3. If you haven't navigated to the sso directory via the terminal in step 2, navigate to the sso directory 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).

   cd <is-samples>/modules/samples/sso mvn clean install

4. After successfully building the sample, a .war file named travelocity.com can be found inside the <is-samples>/modules/samples/sso/sso-agent-sample/target directory. Deploy this sample web app on a web container. To do this, use the Apache Tomcat server.

   Use the following steps to deploy the web app in the web container:

   1. Stop the Apache Tomcat server if it is already running.

   2. Copy the travelocity.com.war file to the <TOMCAT_HOME>/webapps folder.

   3. Start the Apache Tomcat server.

Now the web application is successfully deployed on a web container. 

Configuring the service provider

The next step is to configure travelocity.com as the service provider. The following steps instruct you on how to do this.

1. Start the Identity Server and access the management console using https://localhost:9443/carbon/

2. Log in to the Identity Server using default administrator credentials (the username and password are both "admin").

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

1. Click Configure. The following form appears. The values entered in the screen below are configurations for the sample. 
   

2. Register the new service provider by providing the following values. See Configuring Inbound Authentication for a Service Provider for more information on the fields available in this form.
   
   

Configuring Claims

1. Configure claims for the service provider. To do this, do the following. For more information on configuring this, see Configuring Claims for a Service Provider.

   1. Expand the Claim Configuration section in the service provider form. 

   2. You can select the claims that must be sent to the service provider. If you just want to send them as claim URIs, select Use Local Claim Dialect.

   3. Alternatively, if you want to define new claim URIs for the attributes that are sent, you can define any values for them and map these values with the claim URIs local to WSO2. 
      
      For example, you want to set the email address of the user as http://testclaims.com/claims/emailaddress  claim URI, you can define it here and map it in to http://wso2.org/claims/emailaddress. To specify this, select the Define Custom Claim Dialect option and click Add Claim URI. Enter the Service Provider Claim URIs and select the matching local claim from the dropdown. You can also mark them as a Requested Claim.
      

2. Configure outbound authentication as Default authentication type. This specifies that the identity provider authenticates the users with the username/password by validating with the identity provider's user store.

3. After providing the above information, click Register.

After successfully registering the service provider, log out from management console. The next step is to run the sample.

Running the sample

1. Visit http://localhost:8080/travelocity.com. You are directed to the following page:
   

    

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

3. Enter the default admin credentials (admin/admin).

4. Now you are logged in and you can see the home page of the travelocity.com app.