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.
Before you begin!
- To ensure you get the full understanding of this tutorial, the sample travelocity applciation is used in this use case. Therefore, make sure to download the samples before you begin.
- Download Tomcat 7.x. The samples are written on Servlet 3.0. Therefore, they need to be deployed on Tomcat 7.x.
- Install Apache Maven. For more information, see Installation Prerequisites.
Configuring the SSO web application
To obtain and configure the single sign-on travelocity sample, follow the steps below. 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 terminal, navigate to After successfully building the sample, a 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. If you edit the 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.
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.
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
.war file named travelocity.com can be found inside the
target directory. Deploy this sample web app on a web container. To do this, use the Apache Tomcat server.
file to the
travelocity.com/WEB-INF/classes directory. If the service provider is configured in a tenant you can use the
QueryParams property to send the tenant domain. For example,
A unique identifier for this SAML 2.0 Service Provider application.
The URL of the SAML 2.0 Assertion Consumer.
The URL of the SAML 2.0 Identity Provider.
file, you must restart the Apache Tomcat server for the changes to take effect.
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 terminal, navigate to
After successfully building the sample, a
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.
If you edit the
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.
- Select the Main menu that is on the left side of the management console and click Add under Service Provider.
travelocity.comas the value for the Service Provider Name field and click Register.
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.
- 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.
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.
- 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://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.
- 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.
- 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
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).
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.
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.
After providing consent, you are redirected to the travelocity application home page.
If you need to view the SAML request and response, 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.