Configuring Auth0 with WSO2 API Manager for SSO

8 min readFeb 8, 2022

This article will guide you to configure SSO for WSO2 API Manager portal applications with Auth0 as a federated identity server step by step.

Prerequisites

Create an account in https://auth0.com/
Download API Manager version 4.0.0 distribution from https://wso2.com/api-management/

Configuring users, application and rules in Auth0

There are several configurations that has to be done in Auth0 in order to use such as adding user roles, creating application and enabling SAML, create rules to get user roles in the SAML response. So lets start one by one.

Configuring Users

In the User management section, we need to add the relevant roles that we need to assign the users in the Auth0. Usually we have 3 roles in the API Manager which are to access admin, publisher and dev portal functionalities. So in order to map the three roles in the API Manager we need to add three roles in Auth0 side as well.

Note 1: Also, if needed you can just add only one role in the Auth0 side and map to a single role in WSO2 API Manager

After adding all the roles, select the use and assign the required roles. Since the user I have selected need to access all the portal functionalities, I have assigned all the roles to the user.

After you enable the SAML add-on, in the usage page you will get the Auth0 public certificate as well as the IDP metadata file which will be needed when configuring the Auth0 in the WSO2 API Manager side.

Creating application

Now we need to create application in Auth0 side. For that, we select “Regular Web Applications” in the application creation process.

Then we need to enable SAML add-on for the created application which generates access tokens for the web applications

In the usage section you will be able to download the public certificate and the metadata of the application which will be needed when configuring the Auth0 in API Manager side. Download both files and save it.

And also when you goto the settings section, you will be able to debug and see how the SAML response will be like. In order to check, click on “settings” section and add “https://localhost:9443/commonauth” as Application callback URL and click on “debug”.

Note: You may can keep the JSON settings as default (all commented out) as well. The json keys are the where we get the SAML attributes values in the Auth0 and the json values will get mapped to the SAML response’s attribute names.

When you click on the “debug” you will be able to see encoded and decoded SAML Response with the following user roles as well. Make sure those roles are available in the response or else the login process will break.

Note: If you dont get the “http://schemas.auth0.com/roles” in the SAML response, you need to follow the below steps. and try the “debug” again.
Goto “Auth Pipeline” and “Rules” and create a new rule

From the next page that opens, select the “Set Roles to a User” template from the “Access Control” section

And replace the script using the following code segment and save it

Now we have configured all the configurations thats needed to be done in the Auth0 side. Lets move on to WSO2 APIM.

Configuring Auth0, Service Providers in WSO2 API Manager

Changes in deployment.toml

Open the deployment.toml file located in <API-M_HOME>/repository/conf/ directory. Add the following configuration

[tenant_mgt] 
enable_email_domain= true[apim.throttling]
username = "$ref{super_admin.username}@carbon.super"

[apim.throttling.jms]
username="admin!wso2.com!carbon.super"
password = "$ref{super_admin.password}"

And then change the super admin username to “admin@wso2.com”. Or else you wont be able to login to the admin portal (we are not going to configure admin portalto use the federated IDP)

[super_admin] 
username = "admin@wso2.com" 
password = "admin

Add Auth0 as an external IDP

As shown in the below figure, click on “Add” in the left toolbar and enter the necessary information. Now you could give the downloaded certificate to the selected upload holder as well.

As we scroll further, you could see several sections. Then expand the “Federated Authentication” and “SAML2 Web SSO Configuration” within the section and add and tick the information as below. Upload the metadata file downloaded when configuring the Auth0 in the “Metadata file configuration” section so that you wont need to configure most of the the information manually. And after all the information is added click on “Register”.

One the IDP is saved successfully, click on “edit” and fill up the following information.

First we need to configure claim mappings. In the SAML response the subject value received the user id in the Auth0 which is something similar to “google-oauth2|103811304865022908679” and the format gives an error in the WSO2 side when provisioning the user.

So as a unique name get the email address claim “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress” from the SAML response and map it to WSO2 local claim “http://wso2.org/claims/emailaddress”

Then we need the roles to be mapped. To do that, get role claim “http://schemas.auth0.com/roles” from the SAML response and map it to WSO2 local claim “http://wso2.org/claims/role”

After that select the “User ID Claim URI” and “Role Claim URI” from the dropdown as shown in the following figure.

Then we need to map the local roles that we have in the WSO2 with the roles that we got from the SAML response.

Note 2: I have added three new roles auth0_publisher, auth0_subscriber, auth0_creator in the WSO2 and gace the the respective permissions which were already given in internal/publisher, internal/subscriber and internal/creator
Note 3: If needed you can use the same internal/publisher, internal/subscriber and internal/creator as the local roles and skip “Configuring scope mapping” section
Note 4: If you create only 1 role in Auth0 side, you will have to create a new role (eg: auth0role) and add all the permissions given in internal/publisher, internal/subscriber and internal/creator roles. And in “Configuring scope mapping” section, all the scope that are mapped in the three roles should be added to the auth0role as well

As the final step in configuring the Auth0, configure “Just in time provisioning” as shown below. This will create a user in the primary userstore so that theres no need to go to Auth0 when a user is already authenticated and when a user accesses the portal applications multiple times.

Configuring publisher, dev and admin portal application’s service provider configurations

Here we need to change the Authentication Type to “Federated Authentication” and select the IDP we configured in the above steps.

And also, the if we do not select the “Subject Claim URI”, the subject from the SAML response goes to the portal apps as well. So here also we need to select the “emailaddress” claim.

After adding the two configurations, save the service provider. This has to be done for all the portal apps thats needed Auth0 SSO.

Configuring scope mapping

Since we add new roles in the API Manager, we need to map the roles with the scopes that has the permissions to execute portal functionalities. Inorder to configure those, login to the admin portal with “https://localhost:9443/admin” with with changed username and the password for the super admin in “Changes in deployment.toml” section

Navigate to “Scope assgnments” section in the left toolbar and click on “Add scope mappings”

Add the role name as per the role added on the management console and click on enter.

There are two options where you can map the scopes to a role

Map from an existing role
Select custom scopes

Map from an existing role: since we are also adding scopes to a publisher =, we can use the same internal/publisher scopes by selecting “intenal/publisher” from the drop down.

Select custom scopes: you can select a number of custom scopes which you need to give it to the role.

Note: But since we have 3 separate roles for the 3 portals, we can just assign the scopes using existing roles. But if you only configured one role and then the role mapping should be done accordingly in the WSO2 management console and use custom scope mapping to select all the scopes that requires to do the admin, publisher and devportal functionalities.