Configure Single Sign-On with Entra ID (Azure AD) manually

This guide details the steps required to configure SSO with Entra ID / Azure AD manually. An alternative to using the method using the Azure AD Galley app described in this guide.

Step 1 - Create a new Azure AD Application

For this step you need access to your company’s Azure Active Directory in the Azure portal, if you are not an IT administrator for your company you would typically need help from one in order to complete this step.
See What is application management? - Microsoft Entra ID for more details on managing Azure AD apps.

 

On the left side menu:

i. Navigate to “App Registration”

ii. Choose “New application”

 

 

iii. Enter a name for the application

iv. Under “Supported account types”, select “Accounts in this organisational directory only (Single tenant)”

v. Leave the Redirect URI part empty for now, we will add that in the step below.

vi. Click “Register”

Step 2 - Find and add redirect URLs for your SSO configuration

 

i. From the Organisation Settings home page, click on the “Single Sign-On” icon as shown below:

 

ii. Depending on whether you have added SSO configurations previously or not you should either see a list of current configurations, or just an empty list. Either way, you should also have the “Add” button displayed on the top right.

iii. Click on the “Add” button and choose “OIDC” as illustrated below:

 

iv. On the next screen you will be presented with two fields which you need to add to your Azure AD application configuration, “Redirect URI” and “Front-channel logout URL”. See screenshot below:

 

v. Copy the value of “Redirect URI” and navigate back to the Azure AD application page.

vi. From the overview page, choose “Add a Redirect URI” as shown below:

 

 

vii. On the next screen click “Add a platform” and then choose “Web” from the right-side popup screen.

 

viii. Paste the content you copied from “Redirect URI” previously into the “Redirect URIs” field.

ix. Go back to the Organisation Settings portal and copy the content of the “Front-channel logout URL”

x. Then paste it into the corresponding field in the Azure AD application page as shown below. Make sure “ID tokens” is checked then click “Configure” button.

Step 3 - Add necessary information to SSO External Identity Provider configuration

 

Next we need to add a client secret to the Azure AD application.

i. To do this, go to the left-side menu option “Certificates & secrets”.

ii. Next click “New client secret”

iii. Fill in a description and choose an expiry date for the secret (note that you can also enter a custom date here).

iv. Click the “Add” button to generate the client secret. These steps are shown below:

When the secret has been generated, it will only be visible once, so at this step it is very important to copy its value to the clipboard. If you miss this you will need to generate another secret.

v. Next, switch back to the organisation settings portal

 

vi. Paste the value of the secret into the field “Client Secret”.

 

 

vii. In the Azure AD application page, go back to “Overview” and copy value of the “Application (client) ID” as shown below:

 

viii. Switch to the organisation settings page and paste the value of the “Application (client) ID” into the field “Client id”.

ix. Go back to the Azure AD application page and copy the value of “Directory (tenant) ID”:

 

x. Back in the organisation settings page, paste the “Directory (tenant) ID” into the field “Authority”, then move the cursor to the start of the input field and paste “https://login.microsoftonline.com/” in front of it. This should now make out a URL in the following format (using the example directory ID shown above): https://login.microsoftonline.com/9b681d80-0d21-463d-b0e8-5f9e0ccc46db

 

Staying in the organisation settings page now add the following information :

• Display name (enter a descriptive name for your configuration)

• If your organisation have more than one tenant add your domain name in the field “Tenant”, this could be e.g. “puzzel.com” or “mycompany.biz” - this is to be able automatically route users to the correct SSO configuration based on their email address domain if you have more than one SSO configuration active.

 

 

Step 4 - External id claim

Continuing in same form as in the previous step, the field “External id claim” requires special attention. Here you need to provide a valid Azure AD claim that will be used to map the user to Puzzel ID.

It is highly recommended to not use claims like email, preferred_username or unique_name as external id claim. These claims are not unique, as they can be controllable by tenant administrators or sometimes users, which makes them unsuitable for authorisation decisions. They are only usable for display purposes.

The claims sub or oid are some of the suggested claims, below you can find a chapter of using oid as external id. upn is also a commonly used claim, but it should be noted that the upn value is also possible to change (e.g. by tenant admins) and hence it is not determined a fully safe identifier.

Enter your chosen claim into the “External id claim” field, the rest of the fields can be left as is. Your view should now look something similar to this:

See the following section of this article from Microsoft: Secure applications and APIs by validating claims - Microsoft identity platform

Note that the field “external id” needs to be filled out for each user that is to use SSO according to the chose claim. See the section Validate users using external id for more information.

Step 5 - Save and enable the configuration

Still in the same form as in the previous step, make sure to toggle the configuration to “Enabled” if you wish to start using the configuration right away.

Click “Save” to store your configuration. If you chose to enable the configuration, and you have completed the steps to link the users using external id, you should now be able to login using SSO with Azure AD.