Configure Auth0 as external OAuth provider for WSO2 APIM 3.1.0

WSO2 API Manager is the unarguably the leader of the open source API Management solutions. The most recent Forrester report crowned the WSO2APIM as the leader of Management solutions for Q3 2020. There could be multiple reasons behind the success story of this. But one of the main reasons behind this success is the extensibility of the product to cater many of the custom use cases.

In this blog, I’m going to address how we could configure Auth0 as the external Oauth provider for securing the API’s hosted using the WSO2 APIM. Even in the previous versions of the WSO2 API manager we had the capability of customizing the Auth Handler to cater this requirement, From the 3.1.0 version onward the proceed made much more simpler and with few configuration changes this can be configured. For this, It is mandatory to use the JWT token provided by the external oauth providers.

Throughout this blog following topics will be explained.

• Creating application and generating access token from the Auth0.
• Configure APIM to identify the token received from the external OAuth providers.
• Validate subscriptions via the out of the box KM against the external token.
• Transform the external JWT tokens for advance use cases.

Creating application and generating access token from the Auth0

Auth0 is an identity provider which ensure authentication and authorization functionality. This is a cloud based solution, Any one can create a free account and it dose offer fair amount of features to play with. If we log into the Auth0 website the necessary information is provided to create an account.

Once creating an account, We can login to the account and it will take to the dashboard upon a successful login.

Create an application (Official Auth0 Documentation)

• In the menu there is a link call Applications, Click on that to go to the Applications page.
• There you will see a button to crate a new application.

• Once you have successfully crate an application, It will list as following and it dose show the setting, Metadata related to application.

• Then with the credentials generated, We can use those credentials to get a access token.
• The URL’s related to the OAuth standers could be listed if click on the Advanced Settings in the application.

• The calling those endpoints could obtain an access token.

• If decoded the JWT, It would be look like the following.

Configure APIM to identify the token received from the external OAuth providers.

The initial part of setting up the Auth0 is done, Now it’s time to make necessary changes to APIM side.

Before configuring, There are several key factors needed to be keep in mind. From the JWT used as the Bearer token some of the key metadata is extracted as follows.

• azp claim (Authorized party — the party to which the ID Token was issued) : This is consider as the claim passing the client ID. If the JWT contains the claim call consumerKey it will get the priority and will consider as the client ID.
• sub claim (subject of the JWT) : This will eventually considered as the party which invoke (User) of the API.
• iss claim (issuer claim identifies the principal that issued the JWT.) : All the mapping is made in the APIM side based on the issuer.

Configure deployement.toml file

• In order to WSO2 API Manager to identify the issue and if the issuer match then the JWKS endpoint to validate the JWT need to add the following config.

You can obtain the JWKS endpoint of the Auth0 app from the advance settings section of the application.

Once you make this change and restart the WSO2 server, You will be able invoke the API with the JWT obtain from the Auth0.

Please note that, By default if you use the 3rd party identity provider’s JWT tokens to invoke API’s It will not validate the subscriptions.

Validate subscriptions via the out of the box KM against the external token.

If the subscription validation is needed, then there are 2 main changes to be made.

1. Change deployement.toml and inform APIM that it need’s to do the key validation from KM component.
2. Map the excising credentials received via the JWT to the locally created application.

To achieve both of these parts, there are 2 configs to be added to the deployement.toml. those are subscription_validation_via_km and enable_key_provisioning for more information regarding the key provisioning, please refer to the official WSO2 documentation which is having a detailed description on that.

Once made these changes and restart the server, We can log into the APIM Dev portal and create an application. The navigate to the production or sandbox key section. Now there will be an option to manually provide the Consumer key and the secret.

And also if needed to do any claim mapping, It could also specify according to the above sample.

As mentioned earlier, For the consumer key will be consumerKey or the azp claim received via the JWT. In the above JWT it will be the azp claim.

After provide those information and upon a successful subscription, It’ll allow to invoke the API without any problem.

Transform the external JWT tokens for advance use cases.

If your JWT is sending the the key metadata such as iss or the azp with some other claim, then it could be mapped to those claim internally as previously mentioned. But if it required to do some extra care during the JWT transformation you can write a custom JWT Transformer to achieve those requirement. Please refer to the following scenario which requires to have a custom JWT transformer.

The JWT send the value related to consumer key with the claim aud, with a claim mapping aud is mapped to the consumerKey claim locally with the intention of use it as the Client ID of the application on key validation. But during the key validation it is getting failed with an internal server error. In the wso2carbon.log following printed.

What has append in this case is that, according to the JWT specification, aud is a multi-valued attribute. So when it mapped to the consumerKey locally it still consider it as a string array. So when it’s trying to read those values from the JWT it fails and will throw the error.

To address the situations like above we have to create a custom JWT Transformer to read and transform the JWT according to our requirement. The following sample provides with a demo addressing the above concerns. Once you build this and added to the <AM_HOME>/repository/components/dropins folder. This will use as the JWTTransformer for this particular issuer and use it when transforming the claims.

Please refefer to the https://github.com/shagihan/extended-jwt-transformer repo to get the full sample.

Hope this will answer the procedure for integrating WSO2 APIM with the Auth0. Even for the other external Oauth providers methodology would be same.

#! /bin/bash
echo 'Good Luck, Happy Coding'