Accessing an OAuth 2.0 secured API in WSO2 API Manager with a SAML 2 Bearer token

One of the key feature provided by the WSO2 API Manager is its ability to secure the exposed API’s using OAuth 2.0 tokens. WSO2 API Manager supports all 4 grant types of OAuth 2.0 specification. OAuth 2.0 is a specification that is widely adapted especially in the mobile application space. However we still find the need for API’s to be accessed by web applications that still use standard username-password based credentials. Many of these web applications use SAML 2 based authentication and would prefer to use the same SAML assertion to access OAuth 2.0 protected API’s. This type of a scenario is supported by WSO2 API Manager which supports a SAML 2 Bearer grant type that can allow an application to exchange the SAML 2 bearer token with an OAuth 2.0 access token. This token exchange is transparent to the end-user hence it will not impact their user experience. This token exchange process can be depicted in the diagram below.diag

Step 1 – Application receives a SAML assertion from the SAML IdP after authenticating the user.

Step 2 – When the Application needs to invoke an API, it sends the SAML assertion to the token endpoint of the API Manager. SAML assertion is Base 64 encoded and sent as a SAML Bearer grant. Application will also need to send the consumer key and consumer secret which has to be obtained when subscribing to this API.

Step 3– API Manager will validate the request and exchange the SAML token with an OAuth 2.0 access token and a refresh token.

Step 4 – Application Access the API with the OAuth 2.0 access token (generated in the above step). This OAuth 2.0 token should be included as the Authorization header when invoking API’s via the API Manager.

The objective of this blog is to introduce the concept of token exchange, you would find detailed instructions on how to set this up in the following API Manager document.

SSL Mutual Authentication with WSO2 ESB

SSL Mutual authentication is a widely used authentication mechanism in B2B communication. This blog looks at the concept of SSL mutual authentication and how WSO2 ESB can support SSL Mutual authentication.

How mutual authentication works can be depicted in the diagram below


1. Client Request a resource from the server

2. Server presents the certificate

3. Client validates the certificate from the trust-store

4. Client present its certificate to the server

5. Server validates the certificate with the trust-store

6. Client access the protected resource

For this example we are using the mutual authentication client developed by Asela, and we will be creating our own KeyStore and a TrustStore (we will be using a single key store as both the KeyStore and the TrustStore) for the client service.

1. Lets start by modify the following {ESB_home}/repository/conf/axis2/axis2.xml file by un-commenting the following line in the ‘PassThroughHttpSSLListener’ transport receiver.

<parameter name="SSLVerifyClient">require</parameter>

2. Lets create the KeyStore for the client. We will be using the Java Keytool library for this. We will be executing the following command to create the keystore.

keytool -genkey -alias Client -keyalg RSA -keystore clientKeyStore.jks -keysize 2048

Keytool will prompt the user to enter a keystore password and other values pertaining to the keystore, enter these values and create the keystore. If you go to the folder from which you executed this command you will see the newly created keystore.

3. Next lets export a public certificate from the client Keystore that we can share with the ESB. To do this lets execute the following command.

keytool -export -keystore clientKeyStore.jks -alias Client -file client.crt

You will be prompted to enter the keystore password, enter the password you entered in the step1 .You will now see the client.crt file been created in the folder

4. We will be using the default WSO2Carbon keystore in the ESB, so lets create a public certificate from the wso2carbon keystore to be shared with the client. To do this execute the command below from the following location {ESB_Home}\repository\resources\security

keytool -export -keystore wso2carbon.jks -alias wso2carbon -file ESB.crt

You will prompted to enter the password of the keystore, enter ‘wso2carbon’ which is the default password.

5. Lets now import the certificates to each other’s trust store. Since we are using the same store as the keystore and the truststore for the client lets import the ESB certificate by executing the below command. (this command assume that both the client keystore and the ESB’s public certificate in the same folder)

keytool -import -keystore clientKeyStore.jks -alias wso2carbon -file ESB.crt

You will need to enter the client keystore password you entered in step1. You will also need to confirm the importing of the certificate to the keystore

6. Lets now import the clients certificate to the ESB. To do this execute the following command.

keytool -import -keystore client-truststore.jks -alias Client -file client.crt

As before you will need to enter the client-truststore password which is ‘wso2carbon’ and you would be prompted to add the certificate to the keystore. Once you approve the addition, the certificate would be added to the keystore.

7. Now lets invoke the MutualSSL client[1], for this client to work as we have configure the keystore name, the keystore password which we have set in step1, and the client keystore location. You will also need to provide the service URL of the secured service in the ESB.  Once this is set build the MutualSSLClient using maven. After the build is complete you will see the relevant jar file in the target folder. You can run this jar file from the WSO2 Application Server by following the information here [2]. You can use the try it client in WSO2 Application Server or a SOAP client to test the MutualSSLAuthentication client.

You would see the response from the service in the client



Restricting grant types for an application in WSO2 API Manager

WSO2 API Manager has the capability of restricting which grant types are enabled to a given application. This functionality is provided via the management console of the API Manager. Given below are the steps required

1. App developers should have the required permission in order to restrict the grant types available for an application. Permission given below should be set to a user role associate to the App developer.

2. Once this is done please log out and log into the API Manager’s admin console

3. Now you would see the OAuth URL available in the left navigation, click on this.

4. Here you would see all the applications that are created by the App developer, from this menu select the relevant application to which the grant types should be restricted.

5. Once you are inside the selected application you can define which grant types should be allowed to a given application. By default all grant types are ‘un-checked’ and all grant types are allowed. If you want to override this default configuration select on the required grant types that should be allowed to a given application.

6. Once you are done click on the update button and the configuration would be updated.

Secure, Expose and Manage a SOAP Service using WSO2 API Manager and WSO2 ESB.

WSO2 API Manager provides support for both REST and SOAP based web services. However the API Manager doesn’t support WS Standards. The API Manager and the WSO2 ESB can be used in conjunction to support WS Standards to API’s exposed via the API Manager. In this blog we look at how WSO2 API Manager can be used with the WSO2 ESB to secure and expose a SOAP based API.

Given below is a diagram depicting the message flow on how WS-Security is implemented using WSO2 API manager and WSO2 ESB.


The message from the client would be encrypted using the public key of the ESB. The encrypted message would be sent along with the acquired OAuth token to the API Manager. The API Manager would validate the OAuth token and enforce throttling on the message. The API Manager would send the encrypted message to the ESB. The ESB would decrypt the content of the message using its own private key and send the request to the backend service.

Once the response is received from the backend service, the ESB would encrypt the message using client’s public key and send it to the API Manager. The API Manager would pass-through the message back to the client. The client would decrypt the message using its own private key.

This type of a scenario is useful in a case where

1.WS-Security needs to be enforced but cannot be enforced directly at the backend service (hence needs be enforced in an intermediary stage in the message flow).

  1. Client should be provided with a portal to explore and subscribe to API’s.
  2. API Publisher wants to manage life-cycle and manage API versioning of the exposed API’s.
  3. Throttling and other security mechanisms has to be enforced on-top of WS-Security.
  4. Statistics on API invocations needs to be gathered.