Using SSO with Microsoft Azure Active Directory/Entra ID

book reader icon
14 Minutes
facebook logo gray
linkedin logo gray
mail logo gray
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.

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).

What is SSO?

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.

How the Integration with Active Directory/Entra ID works

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.

Simplified SSO Integration overview with Active Directory/Entra ID
Simplified SSO Integration overview with Active Directory/Entra ID

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.

How To Connect to our QR Code Platform with SSO using Microsoft Azure Active Directory/Entra ID

1. Set up Active Directory/Entra ID for SSO

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.

Create 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".

Open the Microsoft Entra ID service
Open the Microsoft Entra ID service

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

Go to Enterprise applications
Go to Enterprise applications

To create a new Enterprise Application click on New application.

click on New application
click on New application

Click on Create your own application.

Click on Create your own 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.

Enter a name for the application and choose option 3 (Non-gallery)
Enter a name for the application and choose option 3 (Non-gallery)

Configure Single-Sign on

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.

click on the Single sign-on menu in the Manage section on the left
click on the Single sign-on menu in the Manage section on the left

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

Under Select a single sign-on-method click on SAML
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.

Copy the App Federation Metadata Url
Copy the App Federation Metadata Url

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

2. First configuration of White Label Platform

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.

Login

Login
Login Form

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
SSO Types: 1 to 1 versus 1 to many
SSO Types: 1 to 1 versus 1 to many

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.

Create User (1:1)

1 IDP User is assigned to 1 White Label User
1 IDP User is assigned to 1 White Label User

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.

Create Subaccount (1:n)

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.
1 IDP User is assigned to 1 or more White Label Users
1 IDP User is assigned to 1 or more White Label Users

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:

Click Users on the left side and then Create User
Click Users on the left side and then Create User

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.

Enter the App Federation Metadata Url you saved before
Enter the App Federation Metadata Url you saved before

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.

Click on Connect
Click on Connect

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.

Copy SSO Service Provider Descriptor URL
Copy SSO Service Provider Descriptor URL

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

3. Finish configuration of Active Directory/Entra ID

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.

Click on Upload metadata file
Click on Upload metadata file

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

Click on Save
Click on Save

Configure Attributes and Claims

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 Edit
Click on Edit

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

Click on a Claim (eg email)
Click on a Claim (eg email)

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>.

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

Now you can see the Attribute name
Now you can see the Attribute name

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

Click on the Add new claim button
Click on the Add new claim button

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

Enter Role into Name field and user.assignedroles into Source attribute field
Enter Role into Name field and user.assignedroles into Source attribute field

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

Your screen should look something like this
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.

4. Enter Attributes in White Label Platform

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.

Enter the Attribute names into the fields
Enter the Attribute names into the fields

5. Optional: Create App Roles

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.

Click on App registrations > All applications > the Enterprise App you created before
Click on App registrations > All applications > the Enterprise App you created before

Subaccount (1:n)

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.

1 IDP User is assigned to 1 or more White Label Users
1 IDP User is assigned to 1 or more White Label Users

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.

Click on Create app role
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.

Enter the Display name, Value and Description
Enter the Display name, Value and Description

Special Case: Login of Admin/Manager via SSO

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.

Example of Admin John and Manager Monica
Example of Admin John and Manager Monica

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.

Click on Create app role
Click on Create app role

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

Enter the Display name, Value and Description
Enter the Display name, Value and Description

6. Add Users to the Enterprise App

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.

Click on Users and Groups menu (on the left) and then on the button Add user/group
Click on 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.

7. First Login of a SSO User

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.

SSO Type User (1:1)

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.

One IDP User maps to a White Label user
One IDP User maps to a White Label user

SSO Type Subaccount (1:n)

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.

Subaccount for IDP User
Subaccount for IDP User

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

SSO Debugging

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.

Browser Plugin SAML-tracer
Browser Plugin SAML-tracer

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.
Last update 4 months ago