How to Integrate Azure AD for API Authentication in WSO2 APIM

Here I'm covering how to configure WSO2 API Manager 4.1.0 federated authentication with Azure Active Directory step by step(OpenID connect SSO flow)

1. Azure configuration.

1.1 Azure App Registration.

First login to your Azure portal with your credentials. If you don't have an account you can create a free trial account to check this scenario.

Once you successfully logged-in you can see as below.

Click on the Azure Active Directory and select which AD you want to use. If you don't have created AD then you can create a new one for this by clicking on the Create Directory icon. Enter the required details and create new one. It will take few minuted to create an AD for you.

Once all done with new creation select the Azure AD and select App registration on the left navigation panel to register an Open ID client.

Click on the New registration and enter the following details:

• Name: wso2-apim (any desired name as you want)
• Supported Account Types: Accounts in this organizational directory only
• Redirect URI: Web , https://<hostname>:9443/commonauth (change the hostname according to your environment)

And click on Register.

After successful creation you will be redirected to a general info page of the registered application. On this page copy and save the Application (client) ID as it will need for API Manager configurations.

Then click on the Certificates & secrets section in the left side panel and select the New client secret to generate a secret for our newly created wso2-apim application. 

Enter the following details and click Add. 

• Description: WSO2APIMDEV OIDC Secret (You can change this as per your choice)
• Expires: Select your desired time period

Then click on Add.

Copy and save the generated client secret value.

After that click on the API permissions in the left navigation panel to configure the OpenID and Profile scope permissions to your application.

Click on the Add a permission button to add new permissions. Once you click, you will see a side window popped up with the following options.

Choose the Microsoft Graph option and select Delegated permissions on the following screen. Then select the following permissions. 

• email 
• openid 
• Profile 

Click on Add permissions. Leave the existing permissions as it is. Then you can see the all configured API permissions as below.

1.2 Group Registration.

Since we are configuring the SSO flow with Azure AD, we will be creating a security group called Subscriber to represent the subscriber role in the Azure service. For Publisher and Creator roles you need to create separate groups respectively. 

Note: You can create Roles in the azure service and assign them to Users. In addition, you can also create Groups in Azure AD and assign it to your Users. 

Click on the Groups on your AD and there click on New group button. Then you will see it as below. Fill the followings in there. 

• Group type: Security 
• Group name: Subscriber 
• Group description: Group for subscriber

Click on the No owners selected. On the prompted side window, select on owner's Azure accounts you need to add. 

Then click on the No members selected. As above step selects desired members you want to add. 

And finally click on Create. You can see the newly created group as below.

Take a note of the Object id value. 

Note: This is to map the Groups with the API Manager’s internal roles. We will be using the Object IDs of the groups to map the roles in the API Manager. 

Create Another Groups for Publisher and Creator as well. 

1.2.1 Add Groups claim.

Now we have to configure our Azure application to populate the Groups claim in the ID token. Go to the Azure application (wso2-apim) and click on Token configurations.

Click on the Add group claim and tick the security groups. Then expand the ID and choose the Group ID and enable Emit groups as role claims and click on Add.

Now all the set with the Azure configurations. But before moving forward, we will make a note on the Authorization and Token endpoints of our Azure application. We will need these endpoints when configuring an Identity provider in the API Manager.

Go to the Overview page of the Azure application and click on the Endpoints button as above. This will pop a side-window with all the necessary endpoints of our application. Make a note on the Authorization v2 and Token v2 endpoints. In addition to the above-set, also make a note on the OpenID Connect metadata document endpoint.

If you go to the endpoint URL mentioned in the OpenID Connect metadata document, you will find a set of metadata to configure an Identity Provider in the API Manager.

2. WSO2 API Manager configuration.

First of all you need to enable "enable_email_domain" property in the API Manager. Reason behind it "preferred_username" claim in Azure ID token represented with email username. So we will be enabling email username in our API Manager server to provision and log-in to the Store nodes.

Go to <apim-home>/repository/conf and open deployment.toml file and add the following entry.

[tenant_mgt] enable_email_domain= true

Add the following entry for the email regex validation since the default validation only checks the 30 characters. [user_store] username_java_regex = '^[a-zA-Z0-9.-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,4}'

2.1 Identity Provider Creation.

Go to the Carbon Management console, and log-in with the admin credentials.

Select the Add under the Identity Providers and input the followings: 

• Identity Provide Name: AzureADIDP 
• Display Name: Azure AD IDP 
• Choose IDP Certificate Type: Use IDP JWKS Endpoint 
• Identity Provider’s JWKS Endpoint: the JWKS URI found in the OpenID Connect metadata document 

Next, expand the Claim Configurations > Basic Claim configuration > Define Custom Claim Dialect > Add Claim Mapping and add the following mappings 

• preferred_username : http://wso2.org/claims/displayName 
• roles : http://wso2.org/claims/role 

and 

• User ID Claim URI: preferred_username 
• Role Claim URI: roles 

Expand the Role configurations and click on the Add Role Mapping. Paste the Object ID acquired from the Subscriber group in the Azure service and map it with our internal subscriber role

• The Object ID of Subscriber Group : Internal/subscriber

Given below is a sample Role mapping configuration.

Update these for all other groups as well like below.

Then, expand the Federated Authenticators > OAuth2/OpenID Connect Configurations and perform the following

• Enable OAuth2 / OpenID Connect: true
• Default: true
• Client ID: the Client ID of our WSO2APIM Azure app
• Client Secret: the generated secret of our WSO2APIM Azure app
• Authorization Endpoint URL: the authorization_endpoint in the OpenID Connect metadata document
• Token Endpoint URL: the token_endpoint in the OpenID Connect metadata document
• Userinfo Endpoint URL: the userinfo_endpoint in the OpenID Connect metadata document
• Additional Query Parameters: scope=openid profile email

And finally, expand the Just-In-Time Provisioning accordion and configure as follows.

And finally click on Register.

2.2 Service Provider Creation.

From API Manager 4.x onwards, both Publisher and Devportal nodes are configured with OIDC SSO flows as default. 

Hence, go to both Publisher and Devportal nodes and click on the Sign-in button to automatically create and register a Service Provider for the OIDC SSO flow. You don't have to log-in to the portals, the above-mentioned process is to create the respective Service Providers in the API Manager. 

Navigate to the Carbon Management console and sign-in with the Admin credentials. 

Click on List under Service Providers section to list the automatically created Service Providers respective to Publisher: apim_publisher and Devportal: apim_devportal.

Click the Edit of the apim_devportal and expand the Claim Configurations. Select "Define Custom Claim Dialect" and make the following changes 

• preferred_username : http://wso2.org/claims/displayName : Requested 

Next, expand the Local & Outbound Authentication Configuration and select the AzureADIDP as the Federated Authentication and make the following changes

Do the same configurations for apim_publisher. 

Now we are done with all configs. We have now successfully configured OpenID Connect Federated Authentication between Azure AD and Single Sign-On with OpenID Connect with APIM Devportal and Publisher. 

Go to the Publisher or devporal and click on Sign-In. You will be redirected to the Microsoft’s login page to enter the credentials. Enter the credentials of our Microsoft User and then allow the attributes on the consent screen to continue with the federation and provision of the users to the WSO2