Single Sign-on with SAML 2.0

Single sign-on (SSO) allows users, who are authenticated against one application, gain access to multiple other related applications as well without having to repeatedly authenticate themselves. It also allows the web applications gain access to a set of back-end services with the logged-in user's access rights, and the back-end services can authorize the user based on different claims like user role.

WSO2 API Manager includes Single Sign-On with SAML 2.0 feature, which is implemented according to the SAML 2.0 web browser-based SSO support that is facilitated by WSO2 Identity Server (IS) version 4.1.0 onwards. WSO2 Identity Server acts as an identity service provider of systems enabled with single sign-on, while the web applications such as API Manager apps act as SSO service providers. Using this feature, you can configure SSO across the two API Manager web applications, which are API Publisher and API Store as well as other Web applications in your organization. After configuring, users will be able to access API Store or API Publisher in a single authentication attempt.

Before moving to configuration, point both WSO2 IS and WSO2 API Manager to a single users-store using the instructions given in section Configuring User Stores.

Let us take the example of using a common JDBCUserStore for both the IS and API Manager. See steps below for configuring the User Store.

1. Open <AM_HOME>/repository/conf/datasources/master-datasources.xml file and add the datasource configuration for the relevant database. For example,

   <datasource>
        <name>WSO2_UM_DB</name>
        <description>The datasource used for registry and user manager</description>
        <jndiConfig>
                 <name>jdbc/WSO2UMDB</name>
        </jndiConfig>
        <definition type="RDBMS">
                 <configuration>
                     <url>jdbc:mysql://localhost:3306/410_um_db</url>
                     <username>username</username>
                     <password>password</password>
                     <driverClassName>com.mysql.jdbc.Driver</driverClassName>
                     <maxActive>50</maxActive>
                     <maxWait>60000</maxWait>
                     <testOnBorrow>true</testOnBorrow>
                     <validationQuery>SELECT 1</validationQuery>
                     <validationInterval>30000</validationInterval>
                 </configuration>
          </definition>
   </datasource>

   • Place the relevant database driver JAR file in <AM_HOME>/repository/components/lib directory.
   • To create the database schema, you can use the relevant script found in <AM_HOME>/dbscripts directory.

2. Add the same datasource configuration in <IS_HOME>/repository/conf/datasources/master-datasources.xml file.

   Place the relevant database driver JAR file in <IS_HOME>/repository/components/lib directory.

3. Open <AM_HOME>/repository/conf/user-mgt.xml file and change its dataSource property to the jndiConfig name given above (jdbc/WSO2UMDB). For example,

   <Property name="dataSource">jdbc/WSO2UMDB</Property>

4. Have the same configuration as above in the <IS_HOME>/repository/conf/user-mgt.xml file as well.
5. The WSO2 Identity Server has an embedded LDAP user store by default. Follow the instructions on Internal JDBC User Store Configuration to disable the default LDAP and to use the JDBC User Store instead.
6. Open <IS_HOME>/repository/conf/security/application-authenticators.xml and change the loginPage IP and port in <AuthenticatorConfig name="BasicAuthenticator" enabled="true"> accordingly.

SSO configuration instructions are given below.

Configuring WSO2 Identity Server as a SAML 2.0 SSO Identity Provider

1. Download and set up WSO2 Identity Server (version 4.6.0 is used here). See https://docs.wso2.org/display/IS460/Getting+Started in the IS documentation for installation instructions. 
2. Start the IS server and log in to its Management Console UI.  
3. Select the SAML SSO menu under the Main menu in the left pane.
   
    
4. The SAML SSO window opens. Add the following configurations under section Register New Service Provider to register the API Manager applications as SSO service providers. Use the exact same values, which were used to configure the API Manager web applications.
   
   To register API Publisher as an SSO service provider:
   
   • Issuer : API_PUBLISHER
   • Assertion Consumer URL : https://localhost:9443/publisher/jagg/jaggery_acs.jag. Change the IP and port accordingly. This is the url for the acs page in your running publisher app.

   • Select the options Use fully qualified username in the SAML Response, Enable Response Signing, Enable Assertion Signing and Enable Single Logout.

   • Click Register once done.

   To register API Store as an SSO service provider:

   • Issuer : API_STORE
   • Assertion Consumer URL : https://localhost:9443/store/jagg/jaggery_acs.jag. Change the IP and port accordingly. This is the url for the acs page in your running store app.

   • Select the options Use fully qualified username in the SAML Response, Enable Response Signing, Enable Assertion Signing and Enable Single Logout.

   • Click Register once done.

   For example:

   

Configuring WSO2 API Manager Apps as SAML 2.0 SSO Service Providers

1. Navigate to <AM_Home>/repository/deployment/server/jaggeryapps/publisher/site/conf/site.json, and modify the following configurations found under section ssoConfiguration.
   
   • enabled : Set this value to true to enable SSO in the application.
   • issuer : API_PUBLISHER. This value can change depending on the Issuer value defined in WSO2 IS SSO configuration.
   • identityProviderURL : https://localhost:9444/samlsso. Change the IP and port accordingly. This is the redirecting SSO url in your running WSO2 IS server instance.
   • keyStoreName : The location for the default key-store, which is wso2carbon.jks used by WSO2 IS (running identity provider). For example, repository/resources/security/wso2carbon.jks
   • keyStorePassword : Password for the above keystore.
   • identityAlias: wso2carbon.
2. Similarly configure the API Store with SSO. The only difference for API Store SSO configurations is setting API_STORE as the issuer.
3. Once done, access the API Publisher application by typing the URL https://localhost:<Port number>/publisher (e.g. https://localhost:9443/publisher) in your browser. Observe the request redirect to the WSO2 IS SAML2.0 based SSO login page. For example,
4. Enter user credentials. If the user authentication is successful against WSO2 IS, it will redirect to the API Publisher web application with the user already authenticated. Next, access the API Store application, and verify that the same user is already authenticated in API Store as well.