Configuring Azure Active Directory as a federated IdP in WSO2 Identity Server using SAML

WSO2 Identity Server allows you to integrate Azure Active Directory as a federated identity provider out of the box using the OIDC protocol. However, there may be times you may want to integrate Azure Active Directory with WSO2 Identity Server using the SAML protocol. This blog provides you a step-by-step guide on how to accomplish this.  

For ease of understanding, I have split the guide into three sections, namely:  

1. Configuring an application in Azure Active Directory

1. Creating an identity provider in WSO2 Identity Server

1. Configuring a service provider to use the configured identity provider as an authenticator

I will be using WSO2 Identity Server 5.11.0 to demonstrate this integration. If you have not downloaded 5.11.0 yet, you can download it from our product page. As the client application, I will be using the pickup and dispatch sample application. You can get hold of it from our GitHub release page.  

1. Configuring an application in Azure Active Directory

First, needless to say, log into your Azure portal using your credentials. Then, click on the hamburger menu button and select “Azure Active Directory”.  

In the Active Directory section, select “Enterprise applications”. We will be creating an enterprise application and configuring it to use SAML.   

Once you click on Enterprise applications, you will be taken to the enterprise application page. Here, click on “New application” on the top bar to create a new enterprise application.  

After you click on the “New application” button, you will be taken to the “Browse Azure AD Gallery” page. On this page, you can select applications that are preconfigured to work with Azure Active Directory. However, we will have to create a custom application to integrate with WSO2 Identity Server.  

So, click on the “Create your own application” button to create our custom application.    

You should see a side panel pop up. In the side panel, give a name for your application and select “Integrate any other application you don’t find in the gallery (Non-gallery)” under “What are you looking to do with your application?”. I am going to name my application “WSO2 IdP”. Click on “Create” once you are good to proceed.  

Once the application is created, we will be taken to the “Overview” page of the application. On the “Overview” page, select the “Set up single sign on” option under “Getting Started” to configure SAML.  

On the “Single sign-on” page, select SAML.    

Once you select SAML, you will be directed to the SAML configuration page. Here, we will be making the necessary configurations and downloading a metadata file containing all the data necessary to configure an identity provider in WSO2 Identity Server.  

SAML Configurations

First, we need to configure an entity ID and a reply URL. An entity ID uniquely identifies our application. The reply URL is the URL to which Active Directory sends the SAML response. In order to configure these two, select the “Edit” button of the “Basic SAML Configuration” step. You should see a side panel slide in.  

I am going to select the default entity ID of http://adapplicationregistry.onmicrosoft.com/customappsso/primary as the entity ID. Set the “Reply URL” to https://localhost:9443/commonauth. Once done, click on “Save”. Make note of the entity ID as we will be needing it when configuring an identity provider in WSO2 Identity Server.   

Now, we need to download the metadata file. To that end, click on “Download” against “Federation Metadata XML” on the third step named “SAML Signing Certificate”. Save this file in a location you can remember.    

There is one more thing to do. We need to assign users to this application to allow those users to sign into this application. So, click on “Users and groups” and click on “Add user/group”.   

Then, under “Users”, select “None Selected”.   

Select the users you want to assign to this application from the side panel and click on “Select”. Finally, click on “Assign” to assign these users to the application.  

This concludes our tryst with Azure Active Directory. Almost half the battle is won. Now, let’s head over to WSO2 Identity Server to configure an Identity Provider.  

2. Creating an identity provider in WSO2 Identity Server

Now, let’s create an identity provider in WSO2 Identity Server. So, let us log into the Carbon console (https://localhost:9443/carbon) using our admin credentials.  

Then, select “Add” under “Identity Providers” to create an identity provider.     

First, give a name for your identity provider using the “Identity Provider Name” textbox. I am going to name the identity provider “Azure AD SAML”.   

Then, expand “Federated Authenticators” and then, expand “SAML2 Web SSO Configuration”. Here is where we will be configuring SAML.   

First, check “Enable SAML2 Web SSO”. Now, remember the entity ID I asked you to make note of when configuring the enterprise application in Azure Active Directory? Paste that entity ID into the textbox labeled “Service Provider Entity ID”. I chose http://adapplicationregistry.onmicrosoft.com/customappsso/primary as the entity ID so I will be pasting that here.  

Now, we need to upload the metadata file we downloaded from Azure Active Directory. To do so, check the radio button that says “Metadata File Configuration” against “Select Mode”. You will see the settings below this disappear and get replaced with an option to upload the metadata file.   

Then, click on “Choose file” and upload the metadata file we downloaded. Once done, click on “Register”.  

After clicking on “Register”, you will be taken to the IdP list page. Select the IdP you created and once again go to the SAML settings.  

Additional Configurations

As you might be able to notice, WSO2 Identity Server will have configured SAML using the metadata file we provided. However, we have to tweak a few settings to get SAML working perfectly.  

The first setting is the “Enable Authentication Request Signing” setting. Check the checkbox to enable this. Then, we need to configure the algorithm Azure Active Directory uses for signing and hashing. From Azure Active Directory’s documentation, we can learn that Azure Active Directory uses SHA-256 as the default algorithm for signing.   

Therefore, against “Signature Algorithm” select “RSA with SHA256” as the signature algorithm. Choose “SHA1” as the digest algorithm.    

Next, select “Password” as the “Authentication Context Class”.  

That is it. We are done! Click on “Update”.   

3. Configuring a service provider to use the configured identity provider as an authenticator

Now, I am going to add the created IdP as an authenticator to a service provider. Since creating a service provider is beyond the scope of this article, I will skip that part and fast forward straight to the adding-the-IdP-as-an-authenticator part.  

I am going to add “Azure AD SAML” as a federated authenticator in addition to a basic authenticator to the first step and click on “Update”. Let’s test it

Now, the last hurdle! I am going to spin up the pickup and dispatch application that has already been configured to work with my service provider. On the login page, click on “login” to initiate the login flow.    

You should now be able to see a “Sign In With Azure AD SAML” button. Let me click on this to sign into the pickup and dispatch application using my Azure Active Directory credentials.    

We are done! We have successfully configured Azure Active Directory as a federated Identity Provider in WSO2 Identity Server using SAML.