/
Configuring Single Sign-On
com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links' is unknown.

Configuring Single Sign-On

Sept 20, 2018

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.

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.

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. 

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

    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.

    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.

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 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, QueryParams=tenantDomain=wso2.com.

This sample uses the following default values.

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.

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

  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.

  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.

  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.

  1. If you need to view the SAML request and response, add the following debug log to the log4j.properties file found inside <PRODUCT_HOME>/repository/conf.

    log4j.logger.org.wso2.carbon.identity=DEBUG

  2. Since single log out is enabled, if you click the logout button in the travelocity.com home page, you will successfully log out.

Related Topics
com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links2' is unknown.