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.
You can find more information regarding the SAML2 and SAML2 Web Browser SSO Profile in the saml-core specification and the saml-profile specification.
See the following topics for instructions on how to configure the sample with the WSO2 Identity Server.
When running this sample on AS
If you are running this sample on WSO2 Application Server, note that both SSOAgentSample application and WSO2 Application Server, contain different versions of the same slf4j jar. As a solution you can select ONE of the following approaches.
- Remove log4j-over-slf4j-1.6.1.jar file from travelocity.com.war/WEB-INF/lib directory and deploy.
<AS_HOME>/repository/conf/tomcat/webapp-classloading-environments.xmlto resolve the
slf4jconflict and restart the WSO2 Application Server. This change is done so as not to expose the
org.slf4j.*package from WSO2 Carbon.
<DelegatedEnvironment> <Name>Carbon</Name> <DelegatedPackages>*,!org.springframework.*,!org.slf4j.*</DelegatedPackages> </DelegatedEnvironment>
Configuring the SSO web application
To obtain and configure the single sign-on travelocity sample, follow the steps below. You can check out the repository of the SSO sample from GitHub. Follow the instructions here to checkout the folder. Open a terminal window and add the following entry to the Why is this step needed? Some browsers do not allow you to create cookies for a naked hostname, such as The Open the In your command line, navigate to After successfully building the sample, a .war file named travelocity.com can be found inside the 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: Tip: If you wish to change properties like the issuer ID, consumer URL, and IdP URL, you can edit the travelocity.properties file found in the This sample uses the following default values. The unique identifier for this SAML 2.0 Service Provider application. Note: If you are updating the value, make sure to define the same value for the Identity Provider Entity Id of the Resident IdP. Follow the steps given below: If you edit the travelocity.properties file, you must restart the Apache Tomcat server for the changes to take effect. Now the web application is successfully deployed on a web container.
/etc/hosts file of your machine to configure the hostname.
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.
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
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
<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 (see Installation Prerequisites for the appropriate version to use).
mvn clean install
target folder. Deploy this sample web app on a web container. To do this, use the Apache Tomcat server.
travelocity.com/WEB-INF/classes directory. Also if the service provider is configured in a tenant you can use "QueryParams" property to send the tenant domain. As an example "QueryParams=tenantDomain=wso2.com".
A unique identifier for this SAML 2.0 Service Provider application
The URL of the SAML 2.0 Assertion Consumer
SAML2.IdPEntityId as the value for Identity Provider Entity ID.
The URL of the SAML 2.0 Identity Provider
Set this to send SAML2 passive authentication requests
You can check out the repository of the SSO sample from GitHub. Follow the instructions here to checkout the folder.
Open a terminal window and add the following entry to the
Why is this step needed?
Some browsers do not allow you to create cookies for a naked hostname, such as
In your command line, navigate to
After successfully building the sample, a .war file named travelocity.com can be found inside the
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:
Tip: If you wish to change properties like the issuer ID, consumer URL, and IdP URL, you can edit the travelocity.properties file found in the
This sample uses the following default values.
The unique identifier for this SAML 2.0 Service Provider application.
Note: If you are updating the value, make sure to define the same value for the Identity Provider Entity Id of the Resident IdP. Follow the steps given below:
If you edit the travelocity.properties file, you must restart the Apache Tomcat server for the changes to take effect.
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.
- Start the Identity Server and access the management console using
- 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.
- In the management console found on the left of your screen, navigate to the Main menu and click Add under Service Provider.
- Enter a Service Provider Name (e.g. travelocity.com) and click Register.
- Expand the Inbound Authentication Configuration section and then expand SAML2 Web SSO Configuration.
- Select Manual Configuration.
- Register the new service provider by providing the following values. See the table below for more information about the fields in this form.
This is the entity ID for the SAML2 service provider
This value should be same as the
|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
|Enter this value: |
|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 |
|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 (|
|Certificate Alias||This is used to validate the signature of SAML2 requests and is used to generate encryption.|
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|
|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|
|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 that accepts the 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 that accepts single logout requests from the identity server other than the assertion consumer URL, you can provide that endpoint value here.|
To configure SAML Back-Channel Logout and SAML Front-Channel Logout described below, apply the 3904 WUM update to WSO2 IS 5.3.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 to 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.
If your SAML2 SSO issuer has been configured in any other separate tenant other than the super tenant, then you need to append the tenantDomain parameter as well.
If the tenant domain is
Leave unchecked for travelocity sample
|Enable IdP initiated SLO|
The Identity Server facilitates IdP initiated SAML2 single log out 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:
|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|
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.
9. Click Update to register.
- 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.
- Expand the Claim Configuration section in the service provider form.
- 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.
- 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/emailaddressclaim 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.
- After providing the above information, click Register.
- By default outbound authentication has been set 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.
After successfully registering the service provider, log out from management console. The next step is to run the sample.
Running the sample
http://wso2is.local: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.propertiesfile found inside
- Since single log out is enabled, if you click the logout button in the travelocity.com home page, you will successfully log out.
- To configure single sign on with different standards or protocols, see the following topics:
- To set up reCaptcha for single sign on, see the following page:
- To configure single sign on for Microsoft Sharepoint web applications with the WSO2 Identity Server, see the following article: