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

All docs This doc

Versions Compared

Key

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

...

Download WSO2 Identity Server 5.6.0.

Tip

For testing purposes if you want to run both the WSO2 API-M and WSO2 IS server on the same server, then you can go to the <IS_HOME>/repository/conf/carbon.xml file and offset the port by 1 as follows:
<Offset>1</Offset>

Step 2 - Download WSO2 API-M

Download WSO2 API Manager 2.5.0.

Tip

For testing purposes if you want to run both the WSO2 API-M and WSO2 IS server on the same server, then you can change the hostname in WSO2 API-M.

Expand
titleClick here for more information on changing the hostname in WSO2 API-M.

Follow the instructions below to change the hostname in WSO2 API-M:

  1. Navigate to the <API-M_HOME>/repository/conf/carbon.xml file.
  2. Change the hostname and the management hostname based on your choice.
    For example:

    Code Block
    <HostName>wso2.am</HostName>
    <MgtHostName>wso2.am</MgtHostName>
  3. Open the /etc/hosts file.

    Code Block
    vim /etc/hosts
  4. Add the new hostname in the /etc/hosts file.

Step 3 - Configure the user database

Configure a database of your choice with SSL support. This example uses a MySQL database. However, you can configure any database of your choice with SSL support. 

Expand
titleClick here to configure a MySQL DB.

Follow the instructions below to configure your user DB if you are using MySQL. For more information, see Installing and Configuring the Databases.

  1. Download and install MySQL Server 5.7.
    For more information on DB compatibility, see Tested DBMSs.
  2. Download the MySQL JDBC driver.
  3. Unzip the downloaded MySQL driver archive, and copy the MySQL JDBC driver JAR (mysql-connector-java-x.x.xx-bin.jar) into the <API-M_HOME>/repository/components/lib directory and in to the <IS_HOME>/repository/components/lib directory.
  4. Access the database.
    Enter the following command in a command prompt, where <username> is the username.

    Code Block
    firstlineFormatlogin
    titleFormat
    mysql -u<username> -p
    Code Block
    firstlineExamplelogin
    titleExample
    mysql -uroot -p
  5. When prompted, specify the password that corresponds to the username that you specified to access the database.
  6. Create the databases using the following commands, where <API-M_HOME> is the path to the WSO2 API Manager instance that you installed, and the username and password are the same credentials that you specified in the previous steps.

    Code Block
    mysql> create database userdb;
    mysql> use userdb;
    mysql> source <API-M_HOME>/dbscripts/mysql5.7.sql;

...

  1. Navigate to the master-datasources.xml file in the following directories.
    • WSO2 IS - <IS_HOME>/repository/conf/datasources 
    • WSO2 API-M - <API-M_HOME>/repository/conf/datasources
  2. Add the WSO2UM_DB related datasource configurations in order to share the user stores between WSO2 API-M and WSO2 IS. 

    Note

    By default, WSO2 API-M uses a JDBC user store, while WSO2 IS uses a LDAP user store. This example uses a JDBC user store and MySQL DB.

    Localtab Group
    Localtab
    activetrue
    idUMDBFormat
    titleFormat
    Code Block
    languagexml
    <datasource>
     <name>WSO2UM_DB</name>
     <description>The datasource used by user manager</description>
     <jndiConfig>
       <name>jdbc/WSO2UM_DB</name>
     </jndiConfig>
     <definition type="RDBMS">
       <configuration>
         <url>jdbc:mysql://[host_name_of_mysql_server]:3306/userdb?autoReconnect=true</url>
         <username>[user]</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> 

    Make sure to replace the following placeholders:

    • [host_name_of_mysql_server]
    • [user]
    • [password]
    Localtab
    idUMDBExample
    titleExample
    Code Block
    languagexml
    <datasource>
     <name>WSO2UM_DB</name>
     <description>The datasource used by user manager</description>
     <jndiConfig>
       <name>jdbc/WSO2UM_DB</name>
     </jndiConfig>
     <definition type="RDBMS">
       <configuration>
         <url>jdbc:mysql://localhost:3306/userdb?autoReconnect=true</url>
         <username>root</username>
         <password>root</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> 
    Tip

    SSL is enabled by default. However, only for testing purposes you can disable SSL by updating the URL as follows in the WSO2 IS and WSO2 API-M <PRODUCT_HOME>/repository/conf/datasources/master-datasources.xml file. However, this is not recommended for a production environment and you need to make sure that SSL is enabled.

    Code Block
    <url>jdbc:mysql://localhost:3306/userdb?autoReconnect=true&amp;useSSL=false</url>
  3. Update the user-mgt.xml file in the <IS_HOME>/repository/conf directory and the  <API-M_HOME>/repository/conf directory. Update the default configurations with the following property configurations.

    Code Block
    languagexml
    <configuration> 
    ...
    	<Property name="dataSource">jdbc/WSO2UM_DB</Property>
    </configuration>
  4. Configure the user store manager properties.
    In this example, as you are using JDBC as the user store, you need to update the <IS_HOME>/repository/conf/user-mgt.xml file as follows: 

    1. Comment out the default LDAP user store details, which are defined in the  <UserStoreManager class="org.wso2.carbon.user.core.ldap.ReadWriteLDAPUserStoreManager"> section.

    2. Uncomment the following code block with regard to the to the JDBC user store.

      Code Block
      languagexml
      		        <UserStoreManager class="org.wso2.carbon.user.core.jdbc.JDBCUserStoreManager">
                  <Property name="TenantManager">org.wso2.carbon.user.core.tenant.JDBCTenantManager</Property>
                  <Property name="ReadOnly">false</Property>
                  <Property name="ReadGroups">true</Property>
                  <Property name="WriteGroups">true</Property>
                  <Property name="UsernameJavaRegEx">^[\S]{3,30}$</Property>
                  <Property name="UsernameJavaScriptRegEx">^[\S]{3,30}$</Property>
                  <Property name="UsernameJavaRegExViolationErrorMsg">Username pattern policy violated</Property>
                  <Property name="PasswordJavaRegEx">^[\S]{5,30}$</Property>
                  <Property name="PasswordJavaScriptRegEx">^[\S]{5,30}$</Property>
                  <Property name="PasswordJavaRegExViolationErrorMsg">Password length should be within 5 to 30 characters</Property>
                  <Property name="RolenameJavaRegEx">^[\S]{3,30}$</Property>
                  <Property name="RolenameJavaScriptRegEx">^[\S]{3,30}$</Property>
                  <Property name="CaseInsensitiveUsername">false</Property>
                  <Property name="SCIMEnabled">false</Property>
                  <Property name="IsBulkImportSupported">false</Property>
                  <Property name="PasswordDigest">SHA-256</Property>
                  <Property name="StoreSaltedPassword">true</Property>
                  <Property name="MultiAttributeSeparator">,</Property>
                  <Property name="MaxUserNameListLength">100</Property>
                  <Property name="MaxRoleNameListLength">100</Property>
                  <Property name="UserRolesCacheEnabled">true</Property>
                  <Property name="UserNameUniqueAcrossTenants">false</Property>
              </UserStoreManager>
      Info

      You could alternatively use the embedded LDAP in the WSO2 Identity Server as your user store. For more information, see Configuring the Primary User Store in the Administration Guide.

Step 5 - Configure the Identity Provider

Configure an Identity Provider of your choice. In this example we use WSO2 IS as the Identity Provider (IdP).

Follow the instructions below to configure WSO2 IS as the Identity Provider ( IdP):

  1. Start WSO2 Identity Server.

    • On Windows: <IS_HOME>/bin/wso2server.bat --run

    • On Linux/Mac OS: sh <IS_HOME>/bin/wso2server.sh

  2. Create a service provider (SP) for the Store. For more detailed information, see Adding and Configuring a Service Provider in the WSO2 Identity Server 5.6.0 documentation.

    1. Create a service provider (SP) as API_STORE with a inbound OAuth/oidc callback URL as https://<APIM-hostname>:9443/store/jagg/jaggery_oidc_acs.jag  and enable the authorization-code grant type, by checking the Code checkbox that corresponds to Allowed Grant Types.
      <APIM-hostname> - Replace this with the hostname of the WSO2 API Manager Server.

    2. Add claim mapping and set the  http://wso2.org/claims/displayName displayName as the local claim and make it a mandatory claim.
      Your configurations should look similar to the following after creating the service provider.
      Image Removed Image Added

  3. Create a service provider for the Publisher.

    1. Create a service provider as API_PUBLISHER with a inbound OAuth/oidc callback URL as https://<APIM-hostname>:9443/publisher/jagg/jaggery_oidc_acs.jag  and enable the authorization-code grant type. 
      <APIM-hostname> - Replace this with the hostname of the WSO2 API Manager Server.

    2. Add claim mapping and set the  http://wso2.org/claims/displayName  as the local claim and make it a mandatory claim.
      Your configurations should look similar to the following after creating the service provider.

      Image RemovedImage Added

Step 6 - Configure WSO2 API-M 

Follow the instructions below to configure Configure WSO2 API-M with the Identity Provider.

Follow the instructions below to configure WSO2 API-M with WSO2 IS, which is the Identity Provider in this example.

  1. Configure the API Store. For more detailed information, see Adding and Configuring a Service Provider in the WSO2 Identity Server 5.7.0 documentation.
    1. Navigate to the <API-M_HOME>/repository/deployment/server/jaggeryapps/store/site/conf/site.json file.
    2. Edit the oidcConfiguration section to point to the IdP that you configured in step 5.

      Localtab Group
      "

      Make sure to replace the following placeholders with actual values.

      •  <client-id> and the <client-secret>  - Replace these with the credentials that you got when creating the API_STORE service provider.

      • <IdP-hostname> - Replace this with the hostname of the IdP.

      • <IdP-port> - Replace this with the IdP port
      • <APIM-hostname> - Replace this with the hostname of the WSO2 API Manager Server.
      • <APIM-port> - Replace this with the WSO2 APIM port
      Localtab
      activetrue
      idstoreformatoidc
      titleFormat
      Code Block
      "oidcConfiguration" : {
          "enabled" : "true",
          "issuer" : "API_STORE",
          "identityProviderURI" : "https://<IS<IdP-hostname>:<IS<IdP-port>/oauth2/token",
          "authorizationEndpointURI" : "https://<IS<IdP-hostname>:<IS<IdP-port>/oauth2/authorize",
          "tokenEndpointURI" : "https://<IS<IdP-hostname>:<IS<IdP-port>/oauth2/token",
          "userInfoURI" : "https://<IS-hostname>:<IS<IdP-port>/oauth2/userinfo",
          "jwksURI" : "https://<IS<IdP-hostname>:<IS<IdP-port>/oauth2/jwks",
          "logoutEndpointURI" : "https://<IS<IdP-hostname>:<IS<IdP-port>/oidc/logout",
          "authHttpMethod": "POST",
          "clientConfiguration" : {
            "clientId" : "<client-id>",
            "clientSecret" : "<client-secret>",
            "responseType" : "code",
            "authorizationType" : "authorization_code",
            "scope" : "phone email address openid profile",
            "redirectURI" : "https://<APIM-hostname>:<APIM-port>/store/jagg/jaggery_oidc_acs.jag",
            "postLogoutRedirectURI" : "https://<APIM-hostname>:<APIM-port>/store/",
            "clientAlgorithm" : "RS256"
          }
        },
      Localtab
      idegstoreformatoidc
      titleExample

      In this example WSO2 IS is port offset by 1.

      Code Block
      titleExample
      Localtab
      idegstoreformatoidc
      titleExample

      In this example WSO2 IS is port offset by 1.

      Code Block
      "oidcConfiguration" : {
          "enabled" : "true",
          "issuer" : "API_STORE",
          "identityProviderURI" : "https://localhost:9444/oauth2/token",
          "authorizationEndpointURI" : "https://localhost:9444/oauth2/authorize",
          "tokenEndpointURI" : "https://localhost:9444/oauth2/token",
          "userInfoURI" : "https://localhost:9444/oauth2/userinfo",
          "jwksURI" : "https://localhost:9444/oauth2/jwks",
          "logoutEndpointURI" : "https://localhost:9444/oidc/logout",
          "authHttpMethod": "POST",
          "clientConfiguration" : {
            "clientId" : "AA5qAA8mr54JJJJI5T56uF9Gvfka",
            "clientSecret" : "itGy_Y_vVaaarDP_9sKKchJgKlwca",
            "responseType" : "code",
            "authorizationType" : "authorization_code",
            "scope" : "phone email address openid profile",
            "redirectURI" : "https://wso2.am:9443/store/jagg/jaggery_oidc_acs.jag",
            "postLogoutRedirectURI" : "https://wso2.am:9443/store/",
            "clientAlgorithm" : "RS256"
          }
        },

      Make sure to replace the following placeholders with actual values.

      •  <client-id> and the <client-secret>  - Replace these with the credentials that you got when creating the  APIAPI_STORE service provider.

      • <IS<IdP-hostname> - Replace this with the hostname of the WSO2 Identity Server.

      • <IdP-port> - Replace this with the WSO2 IS port
      • <APIM-hostname> - Replace this with the hostname of the WSO2 API Manager Server.
      • <APIM-port> - Replace this with the WSO2 APIM port
  2. Configure the API Publisher.
    1. Navigate to the <API-M_HOME>/repository/deployment/server/jaggeryapps/publisher/site/conf/site.json file.
    2. Edit the oidcConfiguration section to point to the IdP that you configured in step 5.

      Localtab Group
      Localtab
      activetrue
      idformatpublisheroidc
      titleFormat
      Code Block
      "oidcConfiguration" : {
            "enabled" : "true",
            "issuer" : "API_PUBLISHER",
            "identityProviderURI" : "https://<IS<IdP-hostname>:9444<IdP-port>/oauth2/token",
            "authorizationEndpointURI" : "https://<IS<IdP-hostname>:9444<IdP-port>/oauth2/authorize",
            "tokenEndpointURI" : "https://<IS<IdP-hostname>:9444<IdP-port>/oauth2/token",
            "userInfoURI" : "https://<IS<IdP-hostname>:9444<IdP-port>/oauth2/userinfo",
            "jwksURI" : "https://<IS<IdP-hostname>:9444<IdP-port>/oauth2/jwks",
            "logoutEndpointURI" : "https://<IS<IdP-hostname>:9444<IdP-port>/oidc/logout",
            "authHttpMethod": "POST",
            "clientConfiguration" : {
              "clientId" : "<client-id>",
              "clientSecret" : "<client-secret>",
              "responseType" : "code",
              "authorizationType" : "authorization_code",
              "scope" : "phone email address openid profile",
              "redirectURI" : "https://<APIM-hostname>:9443<APIM-port>/publisher/jagg/jaggery_oidc_acs.jag",
              "postLogoutRedirectURI" : "https://<APIM-hostname>:9443/publisher/"
            }
          },<APIM-hostname>:<APIM-port>/publisher/"
            }
          },

      Make sure to replace the following placeholders with actual values.

      •  <client-id> and the <client-secret>  - Replace these with the credentials that you got when creating the API_PUBLISHER service provider.

      • <IdP-hostname> - Replace this with the hostname of the IdP.

      • <IdP-port> - Replace this with the IdP port
      • <APIM-hostname> - Replace this with the hostname of the WSO2 API Manager Server.
      • <APIM-port> - Replace this with the WSO2 APIM port
      Localtab
      idexamplepublisheroidc
      titleExample

      In this example WSO2 IS is port offset by 1.

      Code Block
      "oidcConfiguration" : {
            "enabled" : "true",
            "issuer" : "API_PUBLISHER",
            "identityProviderURI" : "https://localhost:9444/oauth2/token",
            "authorizationEndpointURI" : "https://localhost:9444/oauth2/authorize",
            "tokenEndpointURI" : "https://localhost:9444/oauth2/token",
            "userInfoURI" : "https://localhost:9444/oauth2/userinfo",
            "jwksURI" : "https://localhost:9444/oauth2/jwks",
            "logoutEndpointURI" : "https://localhost:9444/oidc/logout",
            "authHttpMethod": "POST",
            "clientConfiguration" : {
              "clientId" : "BB5qBB8mr54JJJJI5T56uH8Gvfkk",
              "clientSecret" : "hiAk_Y_vVbbbrDP_6sJJchJgKlwca",
              "responseType" : "code",
              "authorizationType" : "authorization_code",
              "scope" : "phone email address openid profile",
              "redirectURI" : "https://wso2.am:9443/publisher/jagg/jaggery_oidc_acs.jag",
              "postLogoutRedirectURI" : "https://wso2.am:9443/publisher/"
            }
          },

      Make sure to replace the following placeholders with the actual values.

      • <client-id> and the <client-secret> - Replace these with the credentials that you got when creating the API_PUBLISHER service provider.

      • <IS<IdP-hostname> - Replace this with the hostname of the WSO2 Identity Server.

      • <IdP-port> - Replace this with the WSO2 IS port
      • <APIM-hostname> - Replace this with the hostname of the WSO2 API Manager Server.
      • <APIM-port> - Replace this with the WSO2 APIM port

Step 7 - Import the public certificate of the Identity Provider

...

  1. Navigate to the <IS_HOME>/repository/resources/security directory.

    Code Block
    cd <IS_HOME>/repository/resources/security
  2. Export the public certificate to a .pem file.

    Localtab Group
    Localtab
    activetrue
    idformat
    titleFormat
    Code Block
    keytool -export -alias wso2carbon -keystore wso2carbon.jks -file publickey.pem

    Enter the password as wso2carbon when requested. This is the default password for keystores.

    Localtab
    idexportoutput
    titleOutput
    Code Block
    Certificate stored in file <publickey.pem>
    Warning:
    The JKS keystore uses a proprietary format. It is recommended to migrate to PKCS12 which is an industry standard format using "keytool -importkeystore -srckeystore wso2carbon.jks -destkeystore wso2carbon.jks -deststoretype pkcs12".
  3. Copy the <IS_HOME>/repository/resources/security/publickey.pem file to the  <API-M_HOME>/repository/resources/security directory.
  4. Navigate to the <API-M_HOME>/repository/resources/security directory.

    Code Block
    cd <API-M_HOME>/repository/resources/security
  5. Import the .pem file in to the client trust store (client-truststore.jks).

    Localtab Group
    Localtab
    activetrue
    idimportformat
    titleFormatSample Command
    Code Block
    keytool -import -alias wso2is -file publickey.pem -keystore client-truststore.jks -storepass wso2carbon
    Localtab
    idimportoutput
    titleOutput

    Type yes when the question that you see in the second line is printed.

    Code Block
    Certificate already exists in keystore under alias <wso2carbon>
    Do you still want to add it? [no]:  yes
    Certificate was added to keystore
  6. Check the details of the imported certificate that corresponds to the Identity Provider.

    Code Block
    keytool -list -alias wso2is -keystore client-truststore.jks -v

...

  1. Configure OpenID Connect for SSO.
    For more information, see Configuring SSO with OpenID Connect.

  2. Access the API Publisher.
    https://<APIM-hostname>:<APIM-port>/publisher/
    In this example, access the Publisher as follows:
    https://wso2.am:9443/publisher/

  3. Provide your username and password and click SIGN IN.

    Image Modified

  4. Enter your username as the display name and click SIGN IN.
    Image Modified

  5. Check Select All to select the mandatory user claims related to API_PUBLISHER and also check one of the approve options (Approve Once or Approve Always) based on your preference.
    If you select Approve Once, you will have to approve OpenID user claim related data each time that you sign in to the Publisher.
    Image Modified
  6. Click Continue.
    You are now logged in to the Publisher interface.
  7. Access the Store.
    https://<APIM-hostname>:<APIM-port>/store/
    In this example, access the Store as follows:
    https://wso2.am:9443/store/
  8. Click Sign In.
  9. Check Select All to select the mandatory user claims related to API_STORE and also check one of the approve options (Approve Once or Approve Always) based on your preference.
    If you select Approve Once, you will have to approve OpenID user claim related data each time that you sign in to the Store.
    Image Modified
  10. Click Continue.
    You are directly logged in to the Store without needing to add any user credentials.