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 application 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 profile 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 travelocity sample, follow the steps below. 

1. Add the following entry to the /etc/hosts file of your machine to configure the hostname.

   Why is this step needed?

   Some browsers do not allow you to create cookies for a naked hostname, such as localhost. Cookies are required when working with SSO. Therefore, to ensure that the SSO capabilities work as expected in this tutorial, you need to configure the etc/host file as explained in this step.

   The etc/host file is a read-only file. Therefore, you won't be able to edit it by opening the file via a text editor. To avoid this, edit the file using the terminal commands.
   For example, use the following command if you are working on a Mac/Linux environment.

   sudo nano /etc/hosts

   127.0.0.1 	wso2is.local

2. Open the travelocity.properties file found in the is-samples/modules/samples/sso/sso-agent-sample/src/main/resources directory of the samples folder you just checked out. Configure the following property with the hostname (wso2is.local) that you configured above. 

   #The URL of the SAML 2.0 Assertion Consumer
   SAML2.AssertionConsumerURL=http://wso2is.local:8080/travelocity.com/home.jsp

3. In your terminal, navigate to is-samples/modules/samples/sso/sso-agent-sample folder and build the sample using the following command. You must have Apache Maven installed to do this

   mvn clean install

4. After successfully building the sample, a .war file named travelocity.com can be found inside the is-samples/sso/sso-agent-sample/ target directory. 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 directory.
   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). If you need to create the service provider in a tenant space, you need to login with tenants user.
3. Select the Main menu that is on the left side of the management console and click Add under Service Provider. 
4. Enter travelocity.com as the value for the Service Provider Name field and click Register. 

5. The Service Providers screen appears. Copy the content in the .pem file of your service provider application certificate and paste it as the value for Application Certificate. In WSO2 IS versions prior to WSO2 IS 5.5.0, the certificates were stored in the keystore file. From 5.5.0 onwards, the certificate is stored in the database and can be directly added via the management console using the Application Certificate field.  

   Note:  If the  Application Certificate  field is left blank, WSO2 IS is backward compatible and follows the previous implementation to locate the certificates in the keystore.
   This means that in the SAML SSO flow, the certificate alias mentioned in SAML inbound authentication configuration is used if the Application Certificate field is left blank.

   

   More on Application Certificate

   For more information on Application Certificate and its usage, click here.

6. Expand the Inbound Authentication Configuration section and then expand SAML2 Web SSO Configuration. 

7. Click Configure.

8. Select Manual Configuration.
   

9. Register the new service provider by providing the following values. See the table below for more information about the fields in this form.

    Click here for more information on each attribute

   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
   Service Provider Qualifier	To configure Service Provider Qualifier described below, apply the 5083 WUM update to WSO2 IS 5.7.0 using the WSO2 Update Manager (WUM). To deploy a WUM update into production, you need to have a paid subscription. If you do not have a paid subscription, you can use this feature with the next version of WSO2 Identity Server when it is released. For more information on updating WSO2 Identity Server using WUM, see Getting Started with WUM in the WSO2 Administration Guide. This value is needed only if you have to configure multiple SAML SSO inbound authentication configurations for the same Issuer value. When a Service Provider Qualifier is defined here, it will be appended to the end of the Issuer value when registering the SAML SP in the Identity Server.  For example, if you specify travelocity.com as the Issuer and sp1 as the Service Provider Qualifier, the configuration will be registered in IS as travelocity.com:urn:sp:qualifier:sp1  You can configure a number of SAML SPs with the same Issuer and different Service Provider Qualifiers. When a Service Provider Qualifier is defined, the issuer of the SAML SSO authentication request is the value specified as the Issuer in the configuration (ex : travelocity.com). The service provider qualifier value should be sent as a query parameter, spQualifier with the HTTP request in the following format. https://{Hostname}:{Port}/samlsso?spQualifier={Service Provider Qualifier} In Travelocity sample SP, this query parameter can be set by modifying SAML2.IdPURL value mentioned in the travelocity.com/WEB-INF/classes/travelocity.properties file as https://localhost:9443/samlsso?spQualifier=sp1.	sp1
   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://wso2is.local: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
   Certificate Alias	This is used to validate the signature of SAML2 requests and is used to generate encryption. From WSO2 IS 5.5.0 onwards, the .pem certificate can be updated via the Service Provider screen in the management console UI using the Application Certificate field. If the certificate has been entered in the Application Certifiate field, the system will use the certificate given there and override the certificate alias field. However, if the Application Certificate field has been left blank, the certificate specified in Certificate Alias will be used.	Select wso2carbon In a tenant : Select the Certificate Alias with tenant domain name
   Response 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#rsasha1 ’.	http://www.w3.org/2000/09/xmldsig#rsasha1
   Response 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
   Assertion Encryption Algorithm	The algorithm that the SAML2 assertion is encrypted. The default value can be configured in the<IS_HOME>/repository/conf/identity/identity.xml  file, in the  SSOService  element with the SAMLDefaultAssertionEncryptionAlgorithmURI tag. If it is not provided the default algorithm is aes256-cbc , at URI http://www.w3.org/2001/04/xmlenc#aes256-cbc .	http://www.w3.org/2001/04/xmlenc#aes256-cbc
   Key Encryption Algorithm	The algorithm that the SAML2 key is encrypted.  The default value can be configured in the <IS_HOME>/repository/conf/identity/identity.xml  file, in the  SSOService  element with the SAMLDefaultKeyEncryptionAlgorithmURI tag. If it is not provided the default algorithm is rsa-oaep-mgf1 , at URI http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p .	http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p
   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 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.	Leave unchecked for travelocity sample
   Enable Assertion Encryption	This defines whether the SAML2 assertion must be encrypted or not.	Leave unchecked for travelocity sample
   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
   SLO Response URL	If the service provider has a different endpoint which accepts single logout response other than the assertion consumer URL, you can provide that endpoint value here.
   SLO Request URL	If the service provider has a different endpoint which accepts single logout requests from the identity server other than the assertion consumer URL, you can provide that endpoint value here.
   Logout Method	To configure SAML Back-Channel Logout and SAML Front-Channel Logout described below, apply the 4062 WUM update to WSO2 IS 5.7.0 using the WSO2 Update Manager (WUM). To deploy a WUM update into production, you need to have a paid subscription. If you do not have a paid subscription, you can use this feature with the next version of WSO2 Identity Server when it is released. For more information on updating WSO2 Identity Server using WUM, see Getting Started with WUM in the WSO2 Administration Guide. SAML single logout is supported by both SAML Back-Channel Logout and SAML Front-Channel Logout methods. By default, when you select Enable Single Logout, it will enable Back-Channel Logout . In order to enable SAML Front-Channel Logout, you can either select Front-Channel Logout (HTTP Redirect Binding) or Front-Channel Logout (HTTP POST Binding) .	Select Back-Channel Logout for travelocity sample
   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.	Leave unchecked for travelocity sample
   Enable Audience Restriction	You can define multiple audiences in the SAML Assertion. Configured audiences would be added into the SAML2 Assertion.	Leave unchecked for travelocity sample
   Enable IdP Initiated SSO	Depending on your application flow you can choose whether to enable IdP initiated SSO. The IdP initiated SSO profile enables to start an authentication flow by sending a GET request to the Identity server with the following format. 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 the tenantDomain  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	Leave unchecked for travelocity sample
   Enable IdP initiated SLO	The Identity Server facilitates IdP initiated SAML2 single logout requests. This is useful if the application can not manage the session index received with the SAML response and still wants to perform log out. 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 the Issuer field in the SAML service provider configuration UI. returnTo (optional) - Value of the parameter should be the URL that the user needs to be redirected to after the logout. If this parameter is present in the request, 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. Example of a returnTo URL:  https://wso2is.local:8080/avs.com/slo	Leave unchecked for travelocity sample
   Enable Assertion Query Request Profile	Enable Assertion Query Request Profile can used for query assertions following SAML2.0 specification. This can query assertions that are persisted to the database when you login to the service provider application. For more information, see Querying SAML Assertions.	Leave unchecked for travelocity sample
   IdP Entity ID Alias	To configure IdP EntityID Alias described below, apply the 5083 WUM update to WSO2 IS 5.7.0 using the WSO2 Update Manager (WUM). To deploy a WUM update into production, you need to have a paid subscription. If you do not have a paid subscription, you can use this feature with the next version of WSO2 Identity Server when it is released. For more information on updating WSO2 Identity Server using WUM, see Getting Started with WUM in the WSO2 Administration Guide. This value can override the value of Identity Provider Entity ID specified under SAML SSO Inbound Authentication configuration in Resident IdP. The Identity Provider Entity ID is used as the issuer of the SAML responses generated from IS. By default, all the SAML responses issued by IS will have the issuer value similar to the Identity Provider Entity ID in Resident IdP’s SAML SSO inbound authentication configuration. But if you want that value to be unique for your SAML SP configuration, you can specify the value here, so that the IdP Entity ID will be overridden with this IdP Entity ID Alias value. In Travelocity sample SP, this value can be set by modifying SAML2.IdPEntityId value mentioned in the travelocity.com/WEB-INF/classes/travelocity.properties file, so that it reflects the value of the IdP Entity ID Alias you define in the SAML SP configuration.	any valid URL/URI

   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.

   
   

   

10. Click Update to register. 

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://serviceprovider.org/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 or a Mandatory Claim. For more information, see Configuring Claims for a Service Provider. 
      
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://wso2is.local: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. Once you have provided the correct credentials, you are redirected to the consent request screen for approval. 

   Note:  This screen will appear at this point if WSO2 Identity Server has all the mandatory claim values of the user in the system. If not, the user will be redirected to the relevant screen and prompted to provide the missing mandatory claim values before providing consent.

   For more information about user consent in the SSO authentication flow, see Consent Management with Single-Sign-On.

   
   

5. Select the claims that you consent to share with the Travelocity application and click Approve. You have to provide consent for all the mandatory claims at a minimum to complete authentication. 

6. After providing consent, you are redirected to the travelocity application home page.