Federating Entra External ID with Entra Workforce ID

Posted on by cljung

With Azure AD B2C, it was quite common to configure federation with your company’s Entra tenant so that admin resources could login to your app with their workforce account. When Entra External ID was introduces, this capability was initially missing. Now it’s available (see docs). Here’s a practical example of how you do it.

Step 1 – Entra Workforce ID configuration

The first step is to do an App registration in the workforce tenant that can be used for authentication.

  1. Entra portal > App registrations > +New registration
  2. Name: CIAM Federation AppReg (or whatever you prefer. It’s only visible as the name of the app registration)
  3. Supported account types: Single tenant only
  4. Redirect URI:
    1. Platform: Web
    2. https://<tenant-subdomain>.ciamlogin.com/<tenant-ID>/federation/oauth2
  5. Click Register button
  6. Authentication > Redirect URI > Edit
    1. add https://<tenant-subdomain>.ciamlogin.com/<tenant-subdomain>.onmicrosoft.com/federation/oauth2
  7. Token configuration > +Add optional claim
    1. Token type: ID
    2. Select email, family_name and given_name
    3. Add
  8. API Permission > +Add a permission
    1. Microsoft APIs > Microsoft Graph > Delegated permissions
    2. Select email, openid and profile
    3. Add permissions
  9. Certificates / secrets > Client secrets > +New client secret
    1. Select you name and expiry time
    2. Add
    3. Copy secret to Notepad
  10. Overview
    1. Copy Application (client) ID to Notepad
    2. Copy Directory (tenant) ID to Notepad
  11. Owners > +Add owners
    1. Not really needed but its a good practice

This should leave you with a configuration like the screenshots below:

API permissions

Token configuration

Authentication (Redirect URIs)

Step 2 – Entra External ID configuration

The second step is to add your Entra Workforce tenant as an Identity Provider in your Entra External ID tenant. For this, make sure you have all your details copied to Notepad and that you have switched tenant to your Entra External ID tenant.

  1. Entra portal > External Identities > Add identity providers > Custom +Add new > OpenID Connect
  2. Display name: Your-Workforce-Name
    This is important!! The name you select is what the users will see as an option in the sign-in form. Select something easily understandable and not too technical
  3. Well-known endpoint
    1. Contrary to the Microsoft documentation, add the link to your own tenant and not to “/organizations”
      Example:
      login.microsoftonline.com/fawltytowers2.com/v2.0/.well-known/openid-configuration
    2. Open this link in a browser and copy the value for “issuer”
      Example:
      https://login.microsoftonline.com/9885457a-2026-4e2c-a47e-32ff52ea0b8d/v2.0
    3. Client ID: the AppID you have in Notepad
    4. Client authentication: client_secret
    5. Client secret: the secret you have in Notepad
    6. Scope: openid profile email
    7. Response type: code
    8. Click Review + create

Step 3 – Update your User flow

You need to add the newly configured identity provider as an option to your existing User flow. Do the following

  1. Entra portal > External Identities > User flows > Select your user flow > Identity providers
  2. Select the checkbox next to your newly created identity provider.
    It will say “Open ID Connect IdP” but your display name will be visible to the right.

Step 4 – Test run the user flow with a workforce account

To check that you can do self-service sign-up and sign-in using your workforce account, the easiest way is to test run the user flow. This requires that you already have a working user flow where you can login with local accounts.

  1. Click “Run user flow” at the top menu for the User flow
  2. The sign-in form should have your new option

Clicking this option will redirect the authentication flow to your workforce tenant. Authentication will happen according to the rules configured in the workforce tenant, meaning Conditional Access policies are applied, as authentication is happening in the Entra workforce tenant. The last step the workforce tenant does in the authentication flow is to ask the workforce user to consent to the permissions the consumer app asks for, like viewing the basic profile.

The first time a workforce user sign-ins to the consumer application (Northwind Airlines in the above example), the data capture forms may appear based on what user attributes you have configured to capture during sign-up. If your workforce app provides these claims, these values will be prefilled, like below.