Skip to content

Using Entra ID as an External Identity Provider

This section explains the steps required to use Entra ID as an external IDP. It starts by describing the configuration on the Azure Portal, and then describes the configuration settings of the Authorization Service.

Requirements

For this to work you need an Azure subscription that provides you with the Microsoft Entra ID service and an Entry ID tenant. For minimal requirements, the basic account of Entra ID is sufficient. Having a paid subscription can make the role assignments to users easier. You also need permissions on the Azure Portal to register an application, as well as the permission to add an enterprise application.

Preparations in the Azure Portal

Microsoft keeps an own guide (https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal) on how to add applications to Entra ID. If the UI changes, the Microsoft guide is likely more up to date than this documentation. The Microsoft guide also offers more detail than what we can provide.

The steps you need to perform on the Azure Portal provide you with all the configuration settings to connect the Authorization Service to Entra ID. Those settings include:

  • a client ID
  • a client secret
  • the tenant guid that identifies your organization on Entra ID

Create a new Application

  1. Open the Microsoft Entra ID management blade on the Azure Portal
  2. Click on 'App Registrations'.
  3. Add a 'New Registration'.
    • Define a display name
    • Allow accounts in this organization. If you're familiar with Entra ID, you can of course also chose another option
    • Select 'Web' on the 'Redirect URI' part
    • Define a default redirect URI
      The URI points to the Authorization Service so that if you host on https://auth.contoso.com you have to specify https://auth.contoso.com/signin-oidc.
      Use only lower-case characters - redirect URIs are case-sensitive.
  4. You are now redirected to the 'Overview' page of the created application. The applications 'ClientID' is shown under 'Essentials'.
  5. Click the 'Register' at the bottom.
  6. In your newly created application, click on 'Add certificate or secret' to add a client secret that the Authorization Service requires for integrating into Entra ID. You also reach this area by clicking on the 'Certificates & Secrets' area in the 'Manage' group on the left.
  7. Click on 'New Client Secret' - an area opens on the right.
    • Enter a description
    • Select a reasonable expiration date of the client secret. Keep in mind that you need to update the secret configured for the Authorization Service after the secret expired.
  8. Keep a copy of the value of your secret - it cannot be viewed after you leave this page.

After these steps you have 4 important values:

  1. You created an application, and by doing that you obtained a client ID
  2. The application showed you also the tenant guid
  3. You created a client secret that allows the Authorization Service to use the client credentials flow
  4. You defined a correct, case-sensitive redirect URI that points to the authorization service.

Tip Redirect URIs are a common pitfall. The RFC specification defines some basic requirements, but each IDP can have additional constraints. If the redirect URI is an issue, please refer to the Microsoft documentation for redirect URI restrictions and limitations (https://learn.microsoft.com/en-us/entra/identity-platform/reply-url).

If you do not want to define and assign roles to users, you can jump to the configuration of the Authorization Service.

Add Application Permissions for Role and User Discovery

The Authorization Server can actively discover roles and users that are available for signed-in Entra ID users. This search uses Microsoft Graph and requires additional permissions. The permissions are set on the client application.

  1. Navigate to the client application that you just created.
  2. Click on 'API permissions' in the menu on the left.
  3. Click 'Add a permission'. A menu on the right opens.
    1. Click on Microsoft Graph
    2. Click on 'Delegated permissions'
      1. Select the delegated 'User.Read' permission
    3. Click on 'Application permissions'
      1. Select the application 'User.Read.All' permission
    4. Click the button 'Add permissions' at the bottom of this panel.
  4. Some permissions might require Admin Consent. If the consent is missing, you see a yellow warning icon.
    1. Switch over to 'Enterprise applications' - there is a link below the table.
    2. Click the big button 'Grant admin consent for XX' and grant admin consent.

If these permissions are not given, automatic role and user discovery of the Authorization Server does not work. Information-lvl logs are written if Microsoft Graph responds missing permissions or other issues.

Define Roles and Apply them to Users

Application roles can be used to group your users. The roles can then be used by platforms and applications that authenticate users via the Authorization Service to assign permissions in their internal role management. Assigning roles/groups instead of users individually allows you easier configuration than assigning each user individually.

To create application roles in Entra ID, you must first add roles to your application and then assign users to these roles. Here, we explain the steps needed to be done in the Azure portal. However, it is likely possible to use scripts and the Azure command line interface to automate that process. Refer to the Azure documentation on how to do so.

Follow these steps to manually create an application role and assign a user to that role:

  1. Click on 'App Roles' and create a new role. Chose any name, for example 'users' or 'administrators'
    • Repeat this step for all roles that you want to add
  2. Click on 'How do I assign App roles' - a new properties panel opens on the right. Click on the link to 'Enterprise applications' that redirects you to the configuration of your application in Enterprise application management
  3. Click 'Users and Groups' on the 'Management' options group, or click the first button 'Assign users and groups' in the 'Getting Started' section in the Overview
  4. Assign users to roles
    • Click the button 'Add user/group' in the top menu.
    • Select one or more users you want to assign to a role
    • Select the role you want to assign to those users. If you have no roles defined yet, please define a role in your application first
    • Click on 'Assign' at the bottom. You now have assigned one role to the selected users
    • Repeat this step for all other roles that you want to assign to users

Creating roles is done in 'Application Registration', while assigning users is done in 'Enterprise applications'. Navigating normally between both is slow. We recommend using the respective shortcuts: 'How do I assign App roles'->'Enterprise Applications' on your applications 'App Roles' section to switch to the Enterprise application section of your app, and the link to 'application registration' on the 'Users and Groups' configuration area in the Enterprise Application panel of your app.

Configuring the Authorization Service for Entra ID integration

The final configuration is done entirely in the Web UI of the TCG Authorization Server. The data is stored and encrypted at rest in the database. The encryption uses the data protection subsystem of .NET.

  1. Log in as local administrator to the Authorization Server
  2. Click on the "Identity Providers" tab
  3. Click on "Add Entra ID"

  4. Enter your configuration data. In this example, the following data is sufficient:

    {
    "Name": "EntraID",
    "Authority": "https://login.microsoftonline.com/<tenant_guid>/v2.0",
    // MetadataAddress is not required since it uses the default path behind the Authority URL
    // "MetadataAddress": "https://login.microsoftonline.com/<tenant_guid>/v2.0/.well-known/openid-configuration",
    "ClientId": "<registered application (client) id>",
    "ClientSecret": "<registered application secret>",
    "UsernameClaimType": "preferred_username",
    "RoleClaimType": "roles",
    "NameClaimType": "name",
}

  5. Optionally add custom claim mappings

  6. Click "Create" and restart the Authorization Server