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

All docs This doc
Expand all   Collapse all
||
Skip to end of metadata
Go to start of metadata

OAuth provides a method for clients to access server resources on behalf of a resource owner (such as a different client or an end-user). It also provides a process for end-users to authorize third-party access to their server resources without sharing their credentials (typically, a username and password pair), using user-agent redirections.

OpenID Connect (OIDC) is a simple identity layer on top of the OAuth 2.0 (OAuth2) protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.

OpenID Connect allows clients of all types, including Web-based, mobile, and JavaScript clients, to request and receive information about authenticated sessions and end-users. The specification suite is extensible, allowing participants to use optional features such as encryption of identity data, discovery of OpenID Providers, and session management, when it makes sense for them.

Configuring SSO with OpenID Connect

Follow the instructions below to configure Single Sign-on (SSO) using OpenID Connect in WSO2 API Manager (WSO2 API-M) using WSO2 Identity Server (WSO2 IS):

Step 1 - Download WSO2 IS

Download WSO2 Identity Server 5.7.0.

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

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.

 Click 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:

    <HostName>wso2.am</HostName>
<MgtHostName>wso2.am</MgtHostName>

  3. Open the /etc/hosts file.

    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.

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

    Error rendering macro 'code': Invalid value specified for parameter 'com.atlassian.confluence.ext.code.render.InvalidValueException'
    mysql -u<username> -p
    Error rendering macro 'code': Invalid value specified for parameter 'com.atlassian.confluence.ext.code.render.InvalidValueException'
    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.

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

Step 4 - Configure the user stores

Follow the instructions below to share the user stores between WSO2 API-M and WSO2 IS. 

  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. 

    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.

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

    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.

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

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

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

      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 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.7.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 as the local claim and make it a mandatory claim.
      You can either use a local claim or a custom claim.
      Your configurations should look similar to the following after creating the service provider.

  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.
      You can either use a local claim or a custom claim.
      Your configurations should look similar to the following after creating the service provider.

Step 6 - Configure WSO2 API-M 

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.

      "oidcConfiguration" : {
    "enabled" : "true",
    "issuer" : "API_STORE",
    "identityProviderURI" : "https://<IdP-hostname>:<IdP-port>/oauth2/token",
    "authorizationEndpointURI" : "https://<IdP-hostname>:<IdP-port>/oauth2/authorize",
    "tokenEndpointURI" : "https://<IdP-hostname>:<IdP-port>/oauth2/token",
    "userInfoURI" : "https://<IS-hostname>:<IdP-port>/oauth2/userinfo",
    "jwksURI" : "https://<IdP-hostname>:<IdP-port>/oauth2/jwks",
    "logoutEndpointURI" : "https://<IdP-hostname>:<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"
    }
  },

      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

      In this example WSO2 IS is port offset by 1.

      "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 API_STORE service provider.

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

      "oidcConfiguration" : {
      "enabled" : "true",
      "issuer" : "API_PUBLISHER",
      "identityProviderURI" : "https://<IdP-hostname>:<IdP-port>/oauth2/token",
      "authorizationEndpointURI" : "https://<IdP-hostname>:<IdP-port>/oauth2/authorize",
      "tokenEndpointURI" : "https://<IdP-hostname>:<IdP-port>/oauth2/token",
      "userInfoURI" : "https://<IdP-hostname>:<IdP-port>/oauth2/userinfo",
      "jwksURI" : "https://<IdP-hostname>:<IdP-port>/oauth2/jwks",
      "logoutEndpointURI" : "https://<IdP-hostname>:<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>/publisher/jagg/jaggery_oidc_acs.jag",
        "postLogoutRedirectURI" : "https://<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

      In this example WSO2 IS is port offset by 1.

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

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

  3. Optionally, map the username claim with a claim of your choice.

    In order to use this feature, apply the WUM update for WSO2 API-M 2.6.0 released on 15-11-2018 (15th Nov 2018).

    If you want to deploy a WUM update in to production, you need to have a paid subscription. If you do not have a paid subscription, you can use this feature with the next version of WSO2 API Manager when it is released. For more information on updating WSO2 API Manager using WUM, see Getting Started with WUM in the WSO2 Updates Guide.

    By default, in WSO2 API-M the username is mapped to the preferred_username claim. However, if you need WSO2 API-M to map the username to a different claim, follow the instructions below.

    1. Open the <API-M_HOME>/repository/deployment/server/jaggeryapps/store/site/conf/site.json file and the <API-M_HOME>/repository/deployment/server/jaggeryapps/publisher/site/conf/site.json files.

    2. Add the usernameClaim property under the oidcconfiguration configurations sections in both the files and specify the OIDC claim to which you want to map the username claim.

      "oidcConfiguration" : {
 ...
 "usernameClaim":"<oidc_claim_name>",
}

      For example, if you want to use the user's email address as their username, then you would configure the site.json as follows:

      "oidcConfiguration" : {
 ...
 "usernameClaim":"email",
 ...
}

Step 7 - Import the public certificate of the Identity Provider

Import the public certificate of the Identity Provider (IdP), which corresponds to the WSO2 Identity Server, into the client-trustore.jks of WSO2 API-M.

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

    cd <IS_HOME>/repository/resources/security

  2. Export the public certificate to a .pem file.

    keytool -export -alias wso2carbon -keystore wso2carbon.jks -file publickey.pem

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

    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.

    cd <API-M_HOME>/repository/resources/security

  5. Import the .pem file in to the client trust store (client-truststore.jks).

    keytool -import -alias wso2is -file publickey.pem -keystore client-truststore.jks -storepass wso2carbon

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

    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.

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

Step 8 - Start WSO2 API Manager

Start WSO2 API-M based on your OS.

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

  • On Linux/Mac OS: sh <API-M_HOME>/bin/wso2server.sh

Using SSO in API Manager with OpenID Connect

Follow the instructions below to use OpenID Connect based SSO with the API Store and the API Publisher.
Let's consider a scenario where you first log in to the Publisher and then log in to the Store.

  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.

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

  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.
  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.
  10. Click Continue.
    You are directly logged in to the Store without needing to add any user credentials.
  • No labels
||