Open in app

Sign in

Write

Sign in

Configure Azure AD as a SAML Federated Identity Provider in WSO2 API Manager

Lakmini Wathsala
13 min readSep 14, 2021

Hello everyone! In this medium, I will be guiding on integrating Azure Active Directory with WSO2 API Manager v4.0.0 as a SAML federated identity provider. With this integration WSO2 APIM will have the SAML SSO(Single Sign-On) capabilities via Azure Active Directory.

The steps are provided for configuring the API Manager Developer Portal using the SAML2 protocol. The same steps can be followed to configure the Publisher and Admin portals as well for the SAML federation.

✅ Setting Up Azure AD

🔷 1.Configuring the Office 365 App 🔷

First of all, let’s create an Office 365 account to make the process easier. For that click here, and select the account type. You can create a trial account which is valid for 30 days. I have selected the ‘Office 365 Business Premium’ type. Then sign up to get an account.

https://www.microsoft.com/en-us/microsoft-365/business/compare-all-microsoft-365-business-products — To create the Office 365 account

🔷 2.Associate a Microsoft Azure AD subscription with the Office 365 account that you created.🔷

Log in to the Microsoft Azure management portal with your existing Office 365 credentials to see the Microsoft Azure Dashboard.

https://portal.azure.com/#home — Azure dashbord

🔷 3. Add new users 🔷

You can add users to your organization from both Office 365 (https://portal.office.com/adminportal/#/users) and Azure AD (https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview)

When creating the users, you should use the same domain which you registered your account.
Ex: My account domain is lakminiw123.onmicrosoft.com
So in my case, when creating users they need to have a format such as user@lakminiw123.onmicrosoft.com.

Make sure you copy down the default password which has been set for each user. At the initial login, the users will be asked to reset their password therefore having this value is important.

https://portal.office.com/adminportal/#/users — Add new user with Office 365
https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview — To create users with Azure AD — I
https://portal.azure.com/#blade/Microsoft_AAD_IAM/UsersManagementMenuBlade/MsGraphUsers — To create users with Azure AD — II

🔷 4. App Registration 🔷

✋ i. Add application

In the Overview section of your Organization(https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview), click ‘Add’ → ‘Enterprise Applications’.

https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview — To add Enterprise application — I

You will be redirected to the ‘Browse Azure AD Gallery’ page.

To add Enterprise application — II

Click the above-pointed banner to navigate to the legacy app gallery and then select ‘Non-gallery application’.

To add Enterprise application — III

Thereafter you can create an application after adding an application name and click on ‘Add’.

To add Enterprise application — IV

✋ ii. Configure the App with APIM server

Then you will be redirected to the Overview page of your newly created Application. Click ‘Single sign-on’ to configure the SAML IDP configurations.

Enterprise application Overview to Single sign-on — I

Select ‘SAML’ as the Single sign-on method.

Enterprise application Overview to Single sign-on — II

Then you will be redirected to ‘SAML-based Sign-on’ page.

SAML-based Sign-on configuration -I
SAML-based Sign-on configuration -II

Ok, let’s configure the application to communicate with the APIM server during the SAML-based federation. Add the following values under the ‘Basic SAML Configuration’ section, Save and exit.

Your configuration for this application should look like the one below(You may need to refresh the page to view the new configurations).

Basic SAML configuration view after editing

✋ ii. Configure Claims

Then let’s configure the claims which will be passed in the SAML response to APIM Server during the federation. The default claims are as follows.

Configuring user attributes and claims

If there is any requirement to capture the AD user’s assigned role you need to add the attribute ‘memberOf’. This will be used to carry out the role mappings when configuring the IDP at the APIM end.

Name: memberOf
Namespace: http://schemas.xmlsoap.org/ws/2005/05/identity/claims
Value: user.assignedroles

Adding memberOf attribute in the purpose of adding roles from AD

After you have completed this, save your changes.

✋ iii. Adding custom roles

Next, we are going to add custom roles. This step is needed only if there is a requirement to pass the roles from Azure AD to APIM, given that this should be followed after adding the ‘memberOf’ attribute in the previous step ‘ii. Configure Claims’.

Select your newly created app from the ‘All applications’ list after navigating to https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade. Then select ‘App roles’ → ‘Create app role’ and add the relevant details and Save.

Adding app roles

Now we can proceed to the next step to assign these roles for the users in AD.

✋ iv. Adding Users to your gallery application

In this step, we are going to assign users from our active directory into our Azure application. Unless we have users authorized to this application they would not be able to perform the login using federation.

From ‘All applications’ of ‘Enterprise applications’ select your application(https://portal.azure.com/#blade/Microsoft_AAD_IAM/StartboardApplicationsMenuBlade/AllApps). Then select the ‘Users and groups’ section of your application.

Adding users to the app — I

Then click ‘Add user/group’ and assign users and roles(if applicable) for the application.

Adding users to the app — II
Adding users to the app — III

Now we have completed the configurations needed for the federation on the Microsoft Azure end.

✋ v. Summary of all needed configurations from the Azure side

Please refer to the ‘SAML-based Sign-on configuration -II’ image and click on the ‘View step-by-step instructions’ of the 4th section of SAML-based Sign-on’ page. There you will be able to figure out the following pieces of information.

Extarct from the step-by-step instructions

🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩

Please refer to the following information of my sample application relevant to Section 1, 2, 3, and 4 of ‘SAML-based Sign-on’ page.

  • Roles:
    📍 Option 1:
    No roles on the Azure AD side so you may need to define the roles within the WSO2 side.
    📍 Option 2:
    Roles and relevant claims are available in the Azure AD(need to follow ‘ii. Configure Claims’ with ‘memeberOf’ attributes and ‘iii. Adding custom roles’ of ‘4. App Registration’)

🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩 🛩

✅ Setting Up API Manager v4.0.0

🔶 1. Enable email as username 🔶

Add the following configuration in deployment.toml file located in <APIm-HOME>/repository/conf/ directory.

[tenant_mgt]
enable_email_domain= true[user_store]
type = “database_unique_id”
username_java_regex = ‘^[\S]{3,100}$’
username_java_script_regex = ‘^[\S]{3,100}$’

In the very first start-up of the WSO2 APIM server (when you have plugged an empty database and run the APIM for the first time), the server will read the super_admin username and password from the deployment.toml file and save it in the DB. Configuring the email address as the username in an already running APIM server is not the production recommended way. Therefore, make sure to configure it before you begin working with WSO2 APIM.

Please refer to WSO2 official documentation for more details on maintaining logins and passwords of WSO2:
https://apim.docs.wso2.com/en/latest/install-and-setup/setup/security/logins-and-passwords/maintaining-logins-and-passwords/

The aforementioned configurations are needed since Azure AD is using the email as the username by default. To use the email as the username in WSO2 API Manager we need to enable it as it is not enabled by default. Additionally, since Azure AD username has more than 30 characters and it is not valid with the default WSO2 regex of “^[\S]{3,30}$”, we need to update the user store regex configurations as well. Otherwise, we will end up with errors while provisioning the Azure AD user to the Primary user store.

Another configuration need to be added in the deployment.toml file if you are going with Option 2. It will be under ‘iv. Expand the “Local & Outbound Authentication Configuration” section, follow one of the below options and login to devportal’.

🔶 2. Register and configure an Identity Provider in the API Manager server to communicate with Azure AD and to perform Federated authentication. 🔶

✋ i. Login to the Carbon Management Console https://localhost:9443/carbon of the APIM server using the admin credentials.

✋ ii. Navigate to the “Identity Providers” section from the left side pane under the Main menu, click on “Add”.

✋ iii. Under “Basic information” provide the below details.

  • Identity Provider Name: Azure_SAML_IDP
  • Display Name: Azure SAML IDP
  • Description: IDP for Azure SAML Federation
  • Alias: https://localhost:9443/oauth2/token
  • In “Choose IDP certificate type:” select “Upload IDP certificate” and upload the APIM4SAML.pem(in .pem format).

📓 Note: If your certificate is exported with Base64 encoding, then rename the extension .cer to .pem. The file is already in .pem format.

APIM — IDP configurations

✋ iv. Expand the “Claim Configuration” accordion to map and configure the Azure AD claims with API Manager.

Click on “Define Custom Claim Dialect” and then “Add Claim Mapping” to add custom mappings. Input the following mappings following one of the below options relates the previously mentioned options of role configurations in ‘. Overlook of all needed configurations from the Azure side’ of ‘4. App Registration’.

📍Option 1:

Set ‘http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name’ as the User ID Claim URI.

APIM — Claim mappings for Option 1

📍Option 2:

In addition to the configurations in Option 1, add another claim mapping for roles. All the needed claim mappings for the Option 2 is as below.

Set ‘http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name’ as the User ID Claim URI and ‘http://schemas.xmlsoap.org/ws/2005/05/identity/claims/memberOf’ as the Role Claim URI.

APIM claim mappings for Option 2

Further, you need to add role mappings as well to map the IDP roles with local roles.

Role mappings for Option 2

✋ v. Expand the “Federated Authenticators” section and then expand the “SAML2 Web SSO Configuration” to configure the Federated SAML2 Authenticator. Input the following in the respective fields.

Keep the other existing configurations as it is.

APIM — SAML configurations — I
APIM — SAML configurations — II
APIM — SAML configurations — III

✋ vi. Expand the “Just-In-Time Provisioning” accordion and tick the “Always Provision to User Store Domain” with “PRIMARY” and enable “Provision silently” to provision the Azure AD users to the API Manager while logging into the portals.

APIM — Just in Time provisioning

✋ vii. Click “Register” to register the IDP.

🔶 3. Configure Service Provider(These steps are applied for the Publisher and Admin portal as well) 🔶

✋ i. Start the API Manager server and navigate to the Devportal for the very first time, https://localhost:9443/devportal/. This will automatically generate and configure a Service Provider related to the Devportal and can be viewed from the Carbon Management Console.

✋ ii. Login to the Carbon Management Console with admin credentials and navigate to the “Service Providers” section from the left side pane under the Main menu and click on “List”.

✋ iii. Edit the auto-generated Service Provider related to the devportal, “apim_devportal”.

APIM — service providers

✋ iv. Expand the “Local & Outbound Authentication Configuration” section, follow one of the below options and login to devportal.

☂️ Option A (To use only federated authentication):

Select ‘Federated Authentication’ and select the relevant IDP from the drop-down Ex: ‘Azure_SAML_IDP’. Additionally enable the “Assert Identity using mapped local subject identifier” and “Use user store domain in roles” and Update the Service Provider configurations.

APIM — Service Providers configuration for Option A

Go to the Devportal https://localhost:9443/devportal/ and click ‘SIGN-IN’. You will be redirected to the Sign In page of the Azure AD. Then enter your credentials to log in.

IDP Sign In

After entering the auto-generated password, you will be asked to update the password.

IDP update password for initial login

☂️ Option B (To use both basic authentication and federated authentication):

Tick the “Advanced Configuration”. Then in “Advanced Authentication Configuration for apim_devportal” section tick “Use subject identifier from this step” and “Use attributes from this step”.
In that step select “basic” from the drop-down menu of “Local Authenticators” and click “Add Authenticator”.
In the same step select “Azure_SAML_IDP” from the drop-down menu of “Federated Authenticators” and click “Add Authenticator”.
Click “Update” in the “Advanced Authentication Configuration for apim_devportal” window.

APIM — Service Providers configuration I for Option B

Then, enable the “Assert Identity using mapped local subject identifier” and “Use user store domain in roles” and Update the Service Provider configurations.

APIM — Service Providers configuration II for Option B
/authenticationendpoint/login page

Go to the Devportal https://localhost:9443/devportal/ click ‘SIGN-IN’.
If the above configurations are successfully performed, you will be redirected to the “/authenticationendpoint/login.do” page where you can select two different sign-in options, i.e. from the basic authentication and IDP authentication.

And If you select IDP authentication by clicking “Sign In With AZURE_SAML_IDP” you will be redirected to Azure AD’s login page. Then enter the credentials of the Azure AD user and continue same as Option 1.
With that, the identity federation and provision of the Azure AD users to the WSO2 API Manager will be performed.

📓 Note: At the initial login flow of a user of Azure AD in both the above approaches, can be ended up with successful or unsuccessful login depending on the selected Option 1 or Option 2.

There will be no issues with Option 1 and will be able to successfully log in even at the very first login.
👉 However, with Option 2 at the very first login of a user, that flow will end up with a ‘403’ error page since the user is not having the relevant roles/permission to log in to WSO2 portals. To overcome this, please follow the below steps.

⭐️ Login to the Carbon Management console of WSO2 API Manager using admin credentials and list the Users (Main → “Users and Roles” → List → “Users”). If the federated SAML flow is successful and JIT Provisioning performed without any errors, you will be able to see your Azure AD User in the prompted list.

⭐️ Since there are no Roles from the Azure AD side and the requirement is to configure it from the WSO2 side, only the “Internal/everyone” role will be assigned for the provisioned user by default. So the other required roles can be assigned after clicking “Assign Roles” of the provisioned user. After APIM 4.0.0.27 update level, these manually adding roles will persist even after re-login of the provisioned user.

⭐️ In order to affect this change you need to apply the below configurations in the deployment.toml file.

[idp_role_management]
return_only_mapped_local_roles = true
return_manually_added_local_roles = true

👉 In order to successfully login into the Devportal, there is another workaround that may not feasible for all the use-cases. It is, “Login” and “Subscribe” permissions can be added to the “Internal/everyone” role then add a role mapping via the /admin portal https://localhost:9443/admin/. (ex: add mapping to “Internal/everyone” with “Internal/subscriber” or else add the relevant scopes.)

Login permission
Subscribe permission
APIM scope assignment via /admin portal

Please refer to the WSO2 official documentation for more details on this:
https://apim.docs.wso2.com/en/latest/administer/managing-users-and-roles/managing-user-roles/#adding-role-mappings

Please refer to the WSO2 official documentation for general information on configuring WSO2 IS as Federated IDP with SAML:
https://apim.docs.wso2.com/en/latest/install-and-setup/setup/sso/configuring-identity-server-as-external-idp-using-saml/

Please refer to the WSO2 official documentation for general information on configuring OKTA as Federated IDP with SAML:
https://apim.docs.wso2.com/en/latest/install-and-setup/setup/sso/okta-as-an-external-idp-using-saml/

Please refer to the WSO2 official documentation for more details on managing Service Providers and Identity Providers via the WSO2 admin services:
https://apim.docs.wso2.com/en/latest/reference/wso2-admin-services/

Respective Admin services that you will have to use are,
Manage Service Providers : IdentityApplicationManagementService
Manage Identity providers : IdentityProviderMgtService

Voila 🎊 🎊 we have successfully integrated Azure AD as a SAML-based federated IDP with WSO2 APIM.

Hope you find the blog post useful!! 😃 🤗 🌸 🌸 Happy Learning!! 🌸 🌸

Wso2 Api Manager
400
Azure Ad
Saml

--

--

Lakmini Wathsala

Written by Lakmini Wathsala

25 Followers

Associate Technical Lead @WSO2

Help

Status

About

Careers

Blog

Privacy

Terms

Text to speech

Teams