/
Configuring Identity Server as IDP for SSO

This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

Configuring Identity Server as IDP for SSO

Sept 28, 2018

The Single Sign-On with SAML 2.0 feature in the API Manager is implemented according to the SAML 2.0 browser-based SSO support that is facilitated by WSO2 Identity Server (WSO2 IS). This feature is available in any WSO2 IS version from 4.1.0 onwards. We use WSO2 IS 5.7.0 in this guide. WSO2 Identity Server acts as an identity service provider of systems enabled with single sign-on, while the Web applications act as SSO service providers. Using this feature, you can configure SSO across the API Publisher and Store. After configuring, you can access the API Store or API Publisher in a single authentication attempt.

The topics below explain the configurations.

In this documentation, MySQL is used as the database to configure WSO2 API Manager with WSO2 Identity Server. For instructions on replacing the default H2 database with MySQL, see Setting up MySQL.

Sharing the user store

Initially, configure your user store(s), if you have not done so already, by following the instructions in Configuring User Stores. Thereafter, point both WSO2 IS and WSO2 API Manager to your user stores(s) using the instructions given below.You do this to make sure that a user who tries to log in to the API Manager console, the API Store or the Publisher is authorized. When a user tries to log in to either of the three applications, s/he is redirected to the configured identity provider (WSO2 IS in this case) where s/he provides the login credentials to be authenticated. In addition to this, the user should also be authorized by the system as some user roles do not have permission to perform certain actions. For the purpose of authorization, the IS and API Manager need to have a shared user store and user management database (by default, this is the H2 database in the <API-M_HOME>/repository/conf/user-mgt.xml file) where the user's role and permissions are stored.

For example, let's share a JDBC user store (MySQL) with both the WSO2 Identity Server and WSO2 API Manager as follows:

  1. Download WSO2 API Manager from here and unzip it. <API-M_HOME> refers to the root folder where WSO2 API-M was unzipped.

  2. Create a MySQL database (e.g., 410_um_db) and run the <API-M_HOME>/dbscripts/mysql.sql script on it to create the required tables. 

  3. Open the <API-M_HOME>/repository/conf/datasources/master-datasources.xml file and add the datasource configuration for the database that you use for the shared user store and user management information. For example, you can share as single user store as follows. If you are sharing multiple datasources, you need to define a datasource for each of the user stores that you are working with, so that they can be shared.

    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>

  4. Download WSO2 Identity Server (WSO2 IS) 5.7.0 from here and unzip it. <IS_HOME> refers to the root folder where WSO2 IS was unzipped.

  5. Add the same datasource configuration above to <IS_HOME>/repository/conf/datasources/master-datasources.xml file.

  6. Copy the database driver JAR file to the <IS_HOME>/repository/components/lib and <API-M_HOME>/repository/components/lib directories.

  7. Open the <API-M_HOME>/repository/conf/user-mgt.xml file. The dataSource property points to the default H2 database. Change it to the jndiConfig name given above (i.e., jdbc/WSO2UMDB). This changes the datasource reference that is pointing to the default H2 database.

    <Realm> <Configuration> ... <Property name="dataSource">jdbc/WSO2UMDB</Property> </Configuration> ... </Realm>

  8. Add the same configuration above to the <IS_HOME>/repository/conf/user-mgt.xml file.

  9. The Identity Server has an embedded LDAP user store by default. As this is enabled by default, follow the instructions in Internal JDBC User Store Configuration to disable the default LDAP and enable the JDBC user store instead.

Sharing the registry space

In a multi-tenanted environment, by default, the Identity Server uses the key store of the super tenant to sign SAML responses. The API Store and Publishers are already registered as SPs in the super tenant. However, if you want the Identity Server to use the registry key store of the tenant that the user belongs to, you can create a common registry database and mount it on both the IS and the APIM.

  1. Create a MySQL database (e.g., registry) and run the <IS_HOME>/dbscripts/mysql.sql script on it to create the required tables. 
    If you are using a different database type, find the relevant script from the <IS_HOME>/dbscripts  directory.

  2. Add the following datasource configuration to both the <IS_HOME>/repository/conf/datasources/master-datasources.xml and  <API-M_HOME>/repository/conf/datasources/master-datasources.xml files.

    <datasource> <name>WSO2REG_DB</name> <description>The datasource used for registry</description> <jndiConfig> <name>jdbc/WSO2REG_DB</name> </jndiConfig> <definition type="RDBMS"> <configuration> <url>jdbc:mysql://localhost:3306/registry?autoReconnect=true&amp;relaxAutoCommit=true&amp;</url> <username>apiuser</username> <password>apimanager</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> 

  3. Create the registry mounts by inserting the following sections into the <IS_HOME>/repository/conf/registry.xml file.

    <dbConfig name="govregistry"> <dataSource>jdbc/WSO2REG_DB</dataSource> </dbConfig> <remoteInstance url="https://localhost"> <id>gov</id> <dbConfig>govregistry</dbConfig> <readOnly>false</readOnly> <enableCache>true</enableCache> <registryRoot>/</registryRoot> </remoteInstance> <mount path="/_system/governance" overwrite="true"> <instanceId>gov</instanceId> <targetPath>/_system/governance</targetPath> </mount> <mount path="/_system/config" overwrite="true"> <instanceId>gov</instanceId> <targetPath>/_system/config</targetPath> </mount>

  4. Repeat the above step in the <API-M_HOME>/repository/conf/registry.xml file as well.

Next, let us look at the SSO configurations. 

Configuring WSO2 Identity Server as a SAML 2.0 SSO Identity Provider

  1. Start WSO2 Identity Server.

    ./wso2server.sh -DportOffset=1

  2. Sign in to the WSO2 IS Management Console UI ( https://localhost:9444/carbon). 

  3. Select Add under the Service Providers menu.

  4. Give a service provider name and click Register.

  5. You are navigated to the detailed configuration page. Inside the Inbound Authentication Configuratio n section, expand SAML2 Web SSO Configuration and click Configure.

  6. Provide the configurations to register the API Publisher as the SSO service provider. These sample values may change depending in your configuration.

    1.  

      • 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 Assertion Consumer Services (ACS) page in your running publisher app.

      • Select the following options:

        • Enable Response Signing

        • Enable  Single Logout

      • Click Register once done.

    For example:

  7. Similarly, provide the configurations to register the API Store as the SSO service provider. These sample values may change depending in your configuration.

    1.  

      • 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 Assertion Consumer Services (ACS) page in your running Store app.

      • Select the following options:

        • Enable Response Signing

        • Enable Single Logout

      • Click Register once done.

  8. Make sure that the responseSigningEnabled element is set to true in both the following files:

    • <API-M_HOME>/repository/deployment/server/jaggeryapps/publisher/site/conf/site.json

    • <API-M_HOME>/repository/deployment/server/jaggeryapps/store/site/conf/site.json

Configuring WSO2 API Manager apps as SAML 2.0 SSO service providers

  1. Open <API-M_Home>/repository/deployment/server/jaggeryapps/publisher/site/conf/site.json and modify the following configurations found under 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 above.

    • 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 keystore of the running IDP. As you use a remote instance of WSO2 IS here, you can import the public certificate of the IS keystore to the APIM and then point to the APIM keystore. The default keystore of the APIM is <API-M_HOME>/repository/resources/security/wso2carbon.jks. Be sure to give the full path of the keystore here.

    • keyStorePassword: Password for the above keystore. The default keyStorePassword is wso2carbon.

    • identityAlias: wso2carbon

  2. Similarly, configure the API Store with SSO. The only difference in API Store SSO configurations is setting API_STORE as the issuer.

  3. Reduce the priority of the SAML2SSOAuthenticator configuration in the <API-M_HOME>/repository/conf/security/authenticators.xml file. 

    You do this as a workaround for a known issue that will be fixed in a future release. The SAML2SSOAuthenticator handler does not process only SAML authentication requests at the moment. If you set its priority higher than that of the BasicAuthenticator handler, the SAML2SSOAuthenticator tries to process the basic authentication requests as well. This causes login issues in the API Publisher/Store.

    <Authenticator name="SAML2SSOAuthenticator" disabled="false"> <Priority>0</Priority> .... </Authenticator>

  4. Access the API Publisher: https://localhost:<port_number>/publisher (e.g.,  https://localhost:9443/publisher ). Observe the request redirect to the WSO2 IS SAML2.0 based SSO login page. For example,

  5. 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.

  6. Access the API Store application, click its Login link (top, right-hand corner) and verify that the same user is already authenticated in API Store.