This documentation is for WSO2 API Manager 2.1.0. View documentation for the latest release.

All docs This doc

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


  1. Download WSO2 API Manager 2.1.0 from here and unzip it. <APIM<API-M_HOME> refers to the root folder where WSO2 APIM 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. 


    There are two MySQL DB scripts available in the product distribution from WSO2 Carbon Kernel 4.4.6 onwards. Click here to identify as to which version of the MySQL script to use. If you are using a different database type, find the relevant script from the <API-M_HOME>/dbscripts directory.

  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.

    Code Block
         <description>The datasource used for registry and user manager</description>
         <definition type="RDBMS">
                      <validationQuery>SELECT 1</validationQuery>

    Modify the username and password parameters in above configuration with your mysql database credentials.


    Refer Configuring master-datasources.xml for descriptive information about each property of the datasource configuration.

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


    To use WSO2 IS as the Key Manager , download the WSO2 Identity Server 5.3.0 as a Key Manager pack, with pre-packaged Key Manager features, from here.

  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.

    Code Block
                <Property name="dataSource">jdbc/WSO2UMDB</Property>
  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.


    In WSO2 API Manager, the JDBC User Store is enabled by default. By changing the default user store of WSO2 Identity server to JDBC User Store, we are pointing both WSO2 API Manager and WSO2 Identity Server to the same user store so that, their user stores are shared.


  1. Start WSO2 Identity Server.

    Code Block
    ./ -DportOffset=1

    You also can change Port offset value by changing <Offset> 1 </Offset> under <Ports> in <IS_HOME>/repository/conf/carbon.xml file.

    titleWhat is port offset?

    The port offset feature allows you to run multiple WSO2 products, multiple instances of a WSO2 product, or multiple WSO2 product clusters on the same server or virtual machine (VM). The port offset defines the number by which all ports defined in the runtime, such as the HTTP/S ports, will be offset. For example, if the HTTPS port is defined as 9443 and the portOffset is 1, the effective HTTPS port will be 9444. 

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


    If you use signin pages that are hosted externally to sign in to the Identity Server, give the absolute URLs of those login pages in the authenticators.xml and application-authenticators.xml files in the <IS_HOME>/repository/conf/identity directory.

  3. Select Add under the Service Providers menu.
  4. Give a service provider name and click Register.


    In a multi tenanted environment, for all tenants to be able to log in to the APIM Web applications, do the following:

    • Click the SaaS Application option that appears after registering the service provider.

      If not, only users in the current tenant domain (the one you are defining the service provider in) will be allowed to log in to the Web application and you have to register new service providers for all Web applications (API Store and API Publisher in this case) from each tenant space separately. For example, let's say you have three tenants as TA, TB and TC and you register the service provider in TA only. If you tick the SaaS Application option, all users in TA, TB, TC tenant domains will be able to log in. Else, only users in TA will be able to log in.

    • Add the following inside the <SSOService> element in the <IS_HOME>/repository/conf/identity/identity.xml file and restart the server.

      Code Block

      If not, you get an exception as SAML response signature verification fails.

    • Because the servers in a multi-tenanted environment interact with all tenants, all nodes should share the same user store. Therefore, make sure you have a shared registry (JDBC mount, WSO2 Governance Registry etc.) instance across all nodes.
  5. You are navigated to the detailed configuration page. Inside the Inbound Authentication Configuration section, expand SAML2 Web SSO Configuration and click Configure.


    To enable tenant specific SSO with IS 5.3.0 for API_PUBLISHER and API_STORE, enable Use tenant domain in local subject identifier under the Local & Outbound Authentication Configuration section.

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

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

      • 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 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


  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.

    Code Block
    <Authenticator name="SAML2SSOAuthenticator" disabled="false">

    You can skip this step if you are using Identity Server 5.3.0 as the IDP.

  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.



To learn more about Single Sign-On with WSO2 Identity Server, see SAML 2.0 Web SSO in the WSO2 Identity Server documentation.