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.
Step 3 - Configure the user database
Configure a database of your choice with SSL support. This example uses a MySQL database.
Step 4 - Configure the user stores
Follow the instructions below to share the user stores between WSO2 API-M and WSO2 IS.
- 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
- WSO2 IS -
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&useSSL=false</url>
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>
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:Comment out the default LDAP user store details, which are defined in the
<UserStoreManager class="org.wso2.carbon.user.core.ldap.ReadWriteLDAPUserStoreManager">
section.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:
Start WSO2 Identity Server.
On Windows:
<IS_HOME>/bin/wso2server.bat --run
On Linux/Mac OS:
sh <IS_HOME>/bin/wso2server.sh
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.
Create a service provider (SP) as
API_STORE
with a inbound OAuth/oidc callback URL ashttps://<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.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.
Create a service provider for the Publisher.
Create a service provider as
API_PUBLISHER
with a inbound OAuth/oidc callback URL ashttps://<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.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.
- Configure the API Store. For more detailed information, see Adding and Configuring a Service Provider in the WSO2 Identity Server 5.7.0 documentation.
- Navigate to the
<API-M_HOME>/repository/deployment/server/jaggeryapps/store/site/conf/site.json
file. 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 theAPI_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
- Navigate to the
- Configure the API Publisher.
- Navigate to the
<API-M_HOME>/repository/deployment/server/jaggeryapps/publisher/site/conf/site.json
file. 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 theAPI_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 theAPI_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
- Navigate to the
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.- 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. Add the
usernameClaim
property under theoidcconfiguration
configurations sections in both the files and specify the OIDC claim to which you want to map theusername
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", ... }
- Open the
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.
Navigate to the
<IS_HOME>/repository/resources/security
directory.cd <IS_HOME>/repository/resources/security
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".
- Copy the
<IS_HOME>/repository/resources/security/publickey.pem
file to the<API-M_HOME>/repository/resources/security
directory. Navigate to the
<API-M_HOME>/repository/resources/security
directory.cd <API-M_HOME>/repository/resources/security
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
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.
Configure OpenID Connect for SSO.
For more information, see Configuring SSO with OpenID Connect.Access the API Publisher.
https://<APIM-hostname>:<APIM-port>/publisher/
In this example, access the Publisher as follows:
https://wso2.am:9443/publisher/
Provide your username and password and click SIGN IN.
Enter your username as the display name and click SIGN IN.
- 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.
- Click Continue.
You are now logged in to the Publisher interface.
- Access the Store.
https://<APIM-hostname>:<APIM-port>/store/
In this example, access the Store as follows:
https://wso2.am:9443/store/
- Click Sign In.
- 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.
- Click Continue.
You are directly logged in to the Store without needing to add any user credentials.