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. In your command line, navigate to <SAMPLE_HOME>/sso 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

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

   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. 
4. Enter a Service Provider Name (e.g. "travelocity.com") and click Register. 
5. Expand the Inbound Authentication Configuration section and then expand SAML2 Web SSO Configuration. 

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

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

   Field	Description	Sample Value
   Issuer	This is the entity ID for the SAML2 service provider This value should be same as the SAML2.SPEntityId value specified inside the travelocity.com/WEB-INF/classes/travelocity.properties file.	travelocity.com
   Assertion Consumer URLs	This is the Assertion Consumer Service (ACS) URL of the service provider. The identity provider redirects the SAML2 response to this ACS URL. However, if the SAML2 request is signed and SAML2 request contains the ACS URL, the Identity Server will honor the ACS URL of the SAML2 request.  This value should be same as the SAML2.AssertionConsumerURL value mentioned inside the travelocity.com/WEB-INF/classes/travelocity.properties file.	Enter this value: http://localhost:8080/travelocity.com/home.jsp and click Add.
   Default Assertion Consumer URL	This must be the same value defined above. If you have defined multiple Assertion Consumer URLs, this value must be the same as the SAML2.AssertionConsumerURL value mentioned inside the  travelocity.com/WEB-INF/classes/travelocity.properties  file as that is the default.
   NameID format	The service provider and identity provider usually communicate with each other regarding a specific subject. That subject should be identified through a Name-Identifier (NameID) , which should be in some format so that It is easy for the other party to identify it based on the format. There are some formats that are defined by SAML2 specification. Enter the default value of this format (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress  )	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
   Signing Algorithm	Specifies the ‘SignatureMethod’ algorithm to be used in the ‘Signature’ element in POST binding. The default value can be configured in the<IS_HOME>/repository/conf/identity/identity.xml file, in the SSOService element with SAMLDefaultSigningAlgorithmURI tag. If it is not provided, the default algorithm is RSA­SHA 1, at URI ‘http://www.w3.org/2000/09/xmldsig#rsa­sha1’.	http://www.w3.org/2000/09/xmldsig#rsa­sha1
   Digest Algorithm	Specifies the ‘DigestMethod’ algorithm to be used in the ‘Signature’ element in POST binding. The default value can be configured in the<IS_HOME>/repository/conf/identity/identity.xml file, in the SSOService element with SAMLDefaultDigestAlgorithmURI tag. If it is not provided the default algorithm is SHA 1, at URI ‘http://www.w3.org/2000/09/xmldsig#sha1’.	http://www.w3.org/2000/09/xmldsig#sha1
   Use fully qualified username in the NameID	A fully qualified username is basically the user name with the user store domain. In short, the username must be in the following format: {user store domain}{user name}.	Set as true by selecting the checkbox
   Enable Response Signing	This is used to sign the SAML2 Responses returned after the authentication process is complete.	Set as true by selecting the checkbox
   Enable Assertion Signing	This is done to sign the SAML2 Assertions returned after the authentication process. SAML2 relying party components expect these assertions to be signed by the Identity Server.	Set as true by selecting the checkbox
   Enable Signature Validation in Authentication Requests and Logout Requests	This specifies whether the identity provider must validate the signature of the SAML2 authentication request and the SAML2 logout request that are sent by the service provider.	Set as true by selecting the checkbox
   Enable Assertion Encryption	This defines whether the SAML2 assertion must be encrypted or not.
   Certificate Alias	This is used to validate the signature of SAML2 requests and is used to generate encryption.	Select wso2carbon
   Enable Single Logout	Enable this to ensure that all sessions are terminated once the user signs out from one server.	Set this as true by selecting the checkbox
   Enable Attribute Profile	The Identity Server supports a basic attribute profile where the identity provider can include the user’s attributes in the SAML Assertions as an attribute statement. You can define the claims that must be included under service provider claim configurations. Also, once you select the “Include Attributes in the Response Always” checkbox, the identity provider always includes the attribute values related to selected claims in the SAML Attribute statement.
   Enable Audience Restriction	You can define multiple audiences in the SAML Assertion. Configured audiences would be added into the SAML2 Assertion.
   Enable IdP Initiated SSO	The service provider is not required to send the SAML2 request when this is enabled. Do a GET request following this pattern: https://{Hostname}:{Port}/samlsso?spEntityID={SAML2 SSO Issuer name} If your SAML2 SSO issuer has been configured in any other separate tenant other than super tenant, then you need to append thetenantDomain parameter as well. If the tenant domain is soasecurity.org, the GET request would be as follows: https://localhost:9443/samlsso?spEntityID=travelocity.com&tenantDomain=soasecurity.org	https://localhost:9443/samlsso?spEntityID=travelocity.com
   Enable IdP initiated SLO	The Identity Server facilitates IdP initiated SAML2 single log out requests. The following parameters can be used with the IdP initiated SLO request: slo (mandatory parameter) - Must have the value “true” to mark the request as an IdP initiated log out request spEntityID (optional) - Value of the parameter should be the SAML issuer name as in “Issuer” field in the SAML service provider configuration UI. returnTo (optional) - Value of the parameter should be the URL which needs to be redirected to, after the log out. If this parameter is present in the request, then the ‘spEntityID’ parameter must also be present. Since this needs to be a trusted location, the value that comes with the request must match with one of the assertion consumer URLs or returnTo ULRs of the service provider.	returnTo URL: https://localhost:8080/avs.com/slo

   Note: To add the correct tenant domain with the username as the subject identifier in tenant mode,

   Expand the Local & Outbound Authentication Configuration section and do the following. 
   

   • Select Use tenant domain in local subject identifier to append the tenant domain to the local subject identifier.
   • Select Use user store domain in local subject identifier to append the user store domain that the user resides in the local subject identifier.

   For super tenant mode, this step is not required and the two options mentioned above should remain disabled by default.

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.