Using SSO with Microsoft Azure Active Directory/Entra ID

This article will guide you to how to connect your users on Microsoft Azure Entra ID (formerly known as Active Directory) via SSO to our platform. This feature is only available for enterprise customers.

This article is covering the SSO integration with our platform based on an example with Microsoft Azure Entra ID/Active Directory.

• If you are using Keycloak read our SSO post for Keycloak.
• If you are using Okta read our SSO post for Okta

This post contains technical details for IAM Admins or your IT department managing Microsoft Azure Entra ID (Active Directory). Please get in touch with an IT expert on your end to help you in setting up the SSO connection. Please make sure that the person who is doing the configuration on Microsoft Azure has the necessary Administrator permissions (especially Attribute Definition Administrator, Attribute Assignment Administrator).

SSO stands for Single Sign-On. It's an authentication process that allows a user to access multiple services, such as our QR Code platform, with only one set of login credentials (such as username and password). With SSO, users don't need to remember different passwords for each application they use, streamlining the login process and enhancing security by reducing the need for multiple credentials. Once authenticated, the user can navigate between various applications or services without needing to log in again.

To integrate your Microsoft Azure Active Directory/Entra ID with our White Label Platform we use SAML 2.0 (Security Assertion Markup Language) to exchange information between your system and our system.

Your company acts as a Identity Provider (IDP) that provides user data to us. Our White Label Platform acts as a Service Provider (SP) receiving user data and giving users access to our system.

Basic information about your IDP and our SP are going to be exchanged via so-called Descriptor URLs - in Entra ID/Active Directory they are called App Federation Metadata Url.

Behind these URLs are files that describe the IDP (Entra ID/Active Directory) or SP with details for the other side to process automatically and help with the configuration.

The user information is going to be sent via a SAML 2.0 message. In this message the data is encoded in Attributes. When sending out the information from your Active Directory/Entra ID an Outbound Mapper is mapping your internal IDP fields, like first name, last name, email, etc. to SAML 2.0 Attributes.

When we receive your SAML 2.0 message our Inbound Mapper transforms the SAML 2.0 Attribute back to our internal format and we will sign in the user into our platform.

In order to set up your Active Directory/Entra ID you need to do 2 sub steps. First, create an Enterprise Application and second configure the Single Sign-On of that Enterprise Application.

To connect our White Label Platform to your Active Directory/Entra ID you need to create a so-called Enterprise Application. This Enterprise Application is a representation of our White Label Platform in your Microsoft Azure Account.

First, make sure that you are logged into your Microsoft Azure Account. You can reach the Microsoft Azure Portal via portal.azure.com .

Next, open the Entra ID Service. You can find the Service with a search in the search bar by typing "Microsoft Entra ID".

In the Microsoft Entra ID service click on the menu Enterprise Applications in the section Manage (on the left side).

To create a new Enterprise Application click on New application.

Click on Create your own application.

Enter a name (we will use QR Code Platform in our example) for the application and choose option 3 (Non-gallery). Then click on Create.

Now its time to configure the Single Sign-on functionality of the just created Enterprise Application.

In order to do this click on the Single sign-on menu in the Manage section on the left.

Under Select a single sign-on-method click on SAML.

Now copy the App Federation Metadata Url and paste it in a Notepad (Windows) or TextEdit (Mac) - we will need it later for our Service Provider.

The App Federation Metadata Url is the Descriptor URL of your Microsoft Active Directory/Entra ID Identity Provider.

Now its time to set up our Service Provider configuration in the White Label Portal.

Head to our website and login to your white label account. Once logged in go to your Account settings and choose the SSO tab.

When you sign in with a user from your company on our platform you can choose how this user can access the platform. There are 2 different scenarios possible:

• User logs in as white label user 1:1
• User can login under different white label users 1:n

To continue with the setup of the SSO connection you must choose a SSO Type first.

For you to understand the concepts as quickly as possible we use an example during this article. Let‘s make the following assumptions:

• The users Adam, Eve and Steve work in your company and need to get access to the White Label Platform.
• You are using Microsoft Azure Active Directory/Entra ID as the Identity Provider (IDP) in your company. If you don't have Active Directory/Entra ID but a different IDP you do not need to worry. You can check out our general SSO post.
  

Attention: In the case of 1:1 a monthly fee for every user occurs.

Select User if you want that a user in your Identity Provider (="IDP User") will be assigned to exactly one (1:1) individual white label user.

When an IDP User signs in for the first time, the corresponding White Label User will be created. In the example above the IDP User Adam will be created as White Label User Adam when he is logging in for the first time.

In this scenario, let's assume as an example that the White Label platform has one user for the Marketing department and one user for the CustomerService department.

Select Subaccount if you want that a user in your Identity Provider (="IDP User") is mapped to one or more (1:n) white label users.

In the example above the IDP users Adam and Eve can use the White Label Users Marketing and CustomerService. The IDP User Steve can only use the White Label User CustomerService.

Before they can be used via SSO make sure that these two users are created in the White Label Platform by creating them via the menu Users on the left side and then Create User.

After creation the User list should look like this:

Inspiration: The White Label Users do not need to be based on a department like Marketing or CustomerService. We just use this here as an example. It is also quite common that there is a separate White Label User for every

• Country (Austria, Spain, Italy, Brazil, etc.) and/or
• Brand (BrandA, BrandB, BrandC, etc.) and/or
• Product Line (Shoes, Shirts, Jacktes, etc.)

The use case can be different for every company. So, just think about how it would make the most sense for your company.

• An IDP User will then act like a teamleader and he can choose under which white label user he wants to sign in. Hence Adam and Eve can choose if they want to sign in as White Label User Marketing or CustomerService
  

After you have chosen the SSO Type you need to enter the SSO IDP Descriptor URL of your Active Directory/Entra ID Identity Provider. This is needed for us to get basic information about how to connect and authenticate your users with SAML 2.0.

In order for you to do that you just need to copy the App Federation Metadata Url you have saved before into the field.

Once you have entered the SSO IDP Descriptor URL the service URLs are extracted from the Descriptor URL and the fields for the SSO Signon Service URL and the SSO Logout Service URL are pre-populated.

If there are no URLs shown, please enter them manually. The SSO Logout Service URL is optional. If the URL is set, the user will be redirected to this URL when he signs out from the QR Code platform. He can then optionally also log out from his IDP.

Click on the Connect button at the bottom to initialize the connection to your Active Directory/Entra ID.

You then get presented the Service Provider Descriptor URL. Copy this URL and paste it into the browser. Download the configuration to file. Remeber where you store the file - we will need it in a second for your Active Directory/Entra ID to upload it there.

Alternatively you can also use the button Download Descriptor XML to download the configuration content.

Now switch back to the Enterprise Application that you just created (QR Code Plaform) and into the Single sign-on section where you copied the App Federation Metadata Url before.

In the top of the page you find a button Upload metadata file. Click on it and choose the file you just downloaded.

Now you see the extracted data on the screen. Click on Save.

As already discussed the user information is going to be sent via a SAML 2.0 message from your Active Directory/Entra ID (IDP) to our White Label Platform (SP). In this message the data is encoded in Attributes. When sending out the information from your Active Directory/Entra ID an Outbound Mapper is mapping your internal IDP fields, like first name, last name, email, etc. to SAML 2.0 Attributes.

When we receive your SAML 2.0 message our Inbound Mapper transforms the SAML 2.0 Attribute back to our internal format and we will sign in the user into our platform.

We will now take a look at the Outbound Mapper. Click on the Edit button next to 2 Attributes & Claims.

Click on a claim (attribute) to see the name under which it is transferred.

On the detail screen you can see the attribute name under which the email address will be transmitted in the SAML 2.0 message.

We need this information later to finalize the configuration in our Inbound Mapper on our White Label Platform Service Provider.

The Attribute name is a combination of the Namespace and the Name in the format <Namespace>/<Name>.

So for the email address it is http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Write the Attribute names down for the fields first name, last name, email address, etc.

Next we will add a mapping for Roles. Click on the Add new claim button.

Give the claim (attribute) a name Role and choose the source attribute user.assignedroles. Click on Save.

Now we have everything we need Attribute/Claim-wise. Your screen should look something like this.

Before you continue with the next step make sure you noted down all the Attribute names - we will need them now for configuring the Inbound Mapper.

Its time to finalize the configuration of the White Label Platform (Service Provider). Switch back to the Account > SSO settings.

Then enter the Attribute names you noted down before for first name, last name, email address, etc. Click on the Connect button to save the changes.

Your screen should look something like this.

If you want to use the Subaccount (1:n) approach with creating users on the White Label Platform (discussed before) or you want to use SSO for Administrators and Managers you need to configure App roles for that.

In your Microsoft Entra ID service main screen click on App registrations, choose the tab All applications and click on the previously created Enterprise app (QR Code Platform) in the list.

If you have selected the SSO type Subaccount (1:n) you need to provide the information which IDP User should have access to which White Label User.

In order to do this we need to create an additional Role for every White Label User in Active Directory/Entra ID. The name of the role must be identical to the White Label user name.

On the App roles screen click on Create app role.

Next, enter the Display name, Value and Description. Make sure that the values match the Whitel Label Username.

In our example we need to create Marketing and CustomerService.

Your admin user can log into our whitelabel platform directly via username and password by default. However, it is also possible to use SSO to log in as an admin or manager.

For that case there are 2 special Roles available: whitelabel_admin and whitelabel_manager.

In our example we have 2 users in the organization that are a admin/manager. User John should be an Admin in the Whitelabel Portal, hence needs the Role whitelabel_admin, user Monica should be a Manager, hence needs the Role whitelabel_manager.

In order to do this we need to create two additional Roles named whitelabel_admin and whitelabel_manager in Active Directory/Entra ID. The names of the roles must be exactly that.

Next, enter the Display name, Value and Description. Make sure that the values match exactly whitelabel_admin and whitelabel_manager.

After we configured everything its time to actually add users to the Enterprise App in Active Directory/Entra ID, so that they can access the White Label Platform. 

There are different ways to do this:

• 1) if you have chosen SSO-Type "1:1":

• 1a) add specific users and just assign the Role User
• 1b) add groups of users and just assign the Role User
• 1c) add specific users or groups and assign an admin role (whitelabel_admin, whitelabel_manager) - if you want to let Admins log in via SSO
• 2) if you have chosen SSO-Type "1:n":

• 2a) add specific users and assign to them specific App roles like Marketing or CustomerService
• 2b) add groups of users and assign role to each group and assign to them specific App roles like Marketing or CustomerService
• 2c) add specific users or groups and assign an admin role (whitelabel_admin, whitelabel_manager) - if you want to let Admins log in via SSO

Lets take a look how to assign users and groups to roles. Before we continue make sure that you have created the necessary App roles (see previous chapter).

In the Enterprise Application (QR Code Platform) click on the Users and Groups menu (on the left) and then on the button Add user/group.

You then get greeted by the Add Assignment screen. Dependend on the scenario you want to pursue do one of the following options:

1a) add specific users and just assign the Role User.

e.g. User Adam should access the White Label Platform with his individual user

1b) add groups of users and just assign the Role User

e.g. all employees from the the Marketing and Sales Department should access the White Label Platform with their individual user.

1c) add specific users or groups and assign an admin role (whitelabel_admin, whitelabel_manager)

e.g. User John is a White Label Admin.

e.g. User Monica is a White Label Manager.

2a) add specific users and assign to them specific App roles like Marketing or CustomerService

e.g. User Adam should be able to access the White Label User Marketing

2b) add groups of users and assign role to each group and assign to them specific App roles like Marketing or CustomerService

e.g. all employees from the the Marketing Department should access the White Label Platform with the White Label User Marketing.

2c) add specific users or groups and assign an admin role (whitelabel_admin, whitelabel_manager)

e.g. User John is a White Label Admin.

In this section you will see how the white label account looks like after the first login of the users for the 2 different SSO types.

When an IDP user logs in for the first time via SSO, a White Label user with the same name is created. In the example below you see the 3 IDP users Adam, Eve and Steve created as White Label users in the User section.

If an IDP user logs into our platform for the first time, a subaccount with the role SSO is created and the matching White Label users are assigned to that subaccount. You can see the Subaccounts in the Account section under the Subaccounts tab.

The following screenshot shows the IDP user Adam assigned to the White Label users Marketing and CustomerService.

To debug the SAML 2.0 communication between your Identity Provider (IDP) and our Service Provider (SP) you can install the browser plugin SAML-tracer.

• Firefox
• Chrome
  

After you open the SAML-tracer popup...

1. start with a SSO login process
2. You will see the list at the top of the popup fill with HTTP requests.
3. Click on the request that is marked as a SAML request in orange color.
4. Choose the tab Summary (or SAML for all the details in XML format). You can check, if the data (eg. Role) is transferred correctly. In this case the role whitelabel_admin has been transferred. This is exactly what we need for this user to log in as a whitelabel portal admin.