Chapter 5. Enabling user authentication with Microsoft Azure, with optional steps

Procedure

1. Register your Developer Hub app in Azure, by using the Azure portal.

   1. Sign in to the Microsoft Entra admin center.
   2. Optional: If you have access to multiple tenants, use the Settings icon in the top menu to switch to the tenant in which you want to register the application from the Directories + subscriptions menu.

   3. Browse to Applications > App registrations, and create a New registration with the configuration:

      Name

      Enter a name to identify your application in Azure, such as <Authenticating with Developer Hub>.

      Supported account types

      Select Accounts in this organizational directory only.

      Redirect URI

      Select a platform

      Select Web.

      URL

      Enter the backend authentication URI set in Developer Hub: https://<my_developer_hub_domain>/api/auth/microsoft/handler/frame

   4. On the Applications > App registrations > <Authenticating with Developer Hub> > Manage > API permissions page, Add a Permission, Microsoft Graph, select the following permissions:

      Application Permissions

      GroupMember.Read.All, User.Read.All

      Enter permissions that enable provisioning user and groups to the Developer Hub software catalog.

      Optional: Grant admin consent for these permissions. Even if your company does not require admin consent, consider doing so as it means users do not need to individually consent the first time they access Developer Hub.

      Delegated Permissions

      User.Read, email, offline_access, openid, profile

      Enter permissions that enable authenticating users.

      Optional: Enter optional custom scopes for the Microsoft Graph API that you define both here and in your app-config.yaml Developer Hub configuration file.

   5. On the Applications > App registrations > <Authenticating with Developer Hub> > Manage > Certificates & secrets page, in the Client secrets tab, create a New client secret.

   6. Save the following values for the next step:

      • Directory (tenant) ID
      • Application (client) ID
      • Application (client) Secret ID

2. Add your Azure credentials to Developer Hub, by adding the following key/value pairs to your Developer Hub secrets:

   MICROSOFT_TENANT_ID

   Enter your saved Directory (tenant) ID.

   MICROSOFT_CLIENT_ID

   Enter your saved Application (client) ID.

   MICROSOFT_CLIENT_SECRET

   Enter your saved Application (client) secret.

3. Enable the Microsoft Graph catalog provider plugin in your dynamic-plugins.yaml file. This plugin imports Azure users and groups to the Developer Hub software catalog.

   plugins:
     - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-msgraph-dynamic'
       disabled: false

4. Enable provisioning Azure users and groups to the Developer Hub software catalog, by adding the Microsoft Graph catalog provider section in your app-config.yaml file:

   catalog:
     providers:
       microsoftGraphOrg:
         providerId:
           target: https://graph.microsoft.com/v1.0
           tenantId: ${MICROSOFT_TENANT_ID}
           clientId: ${MICROSOFT_CLIENT_ID}
           clientSecret: ${MICROSOFT_CLIENT_SECRET}
           schedule:
             frequency:
               hours: 1
             timeout:
               minutes: 50
             initialDelay:
               minutes: 50

   target

   Enter https://graph.microsoft.com/v1.0 to define the MSGraph API endpoint the provider is connecting to. You might change this parameter to use a different version, such as the beta endpoint.

   tenandId

   Enter the configured secret variable name: ${MICROSOFT_TENANT_ID}.

   clientId

   Enter the configured secret variable name: ${MICROSOFT_CLIENT_ID}.

   clientSecret

   Enter the configured secret variable name: ${MICROSOFT_CLIENT_SECRET}.

   schedule

   frequency

   Enter the schedule frequency in the cron, ISO duration, or human duration format. In a large organization, user provisioning might take a long time, therefore avoid using a low value.

   timeout

   Enter the schedule timeout in the ISO duration or human duration format. In a large organization, user provisioning might take a long time, therefore avoid using a low value.

   initialDelay

   Enter the schedule initial delay in the ISO duration or human duration format.

5. Optional: Add optional fields to the Microsoft authentication provider section in your app-config.yaml file:

   catalog:
     providers:
       microsoftGraphOrg:
         providerId:
           authority: https://login.microsoftonline.com/
           queryMode: advanced
           user:
             expand: manager
             filter: accountEnabled eq true and userType eq 'member'
             loadPhotos: true
             select: ['id', 'displayName', 'description']
           userGroupMember:
             filter: "displayName eq 'Backstage Users'"
             search: '"description:One" AND ("displayName:Video" OR "displayName:Drive")'
           group:
             expand: member
             filter: securityEnabled eq false and mailEnabled eq true and groupTypes/any(c:c+eq+'Unified')
             search: '"description:One" AND ("displayName:Video" OR "displayName:Drive")'
             select: ['id', 'displayName', 'description']

   authority

   Enter your Azure authority URL if it is different from the default: https://login.microsoftonline.com.

   queryMode

   Enter advanced when the default basic query mode is insufficient for your queries to the Microsoft Graph API. See Microsoft Azure advanced queries.

   user

   Add this section to configure optional user query parameters.

   expand

   Enter your expansion parameter to include the expanded resource or collection referenced by a single relationship (navigation property) in your results. A single request can expand only one relationship. See Microsoft Graph query expand parameter.

   You can combine this parameter with userGroupMember.filter or user.filter.

   filter

   Enter your user filter. See Microsoft Graph API and Microsoft Graph API query filter parameters syntax.

   This parameter and userGroupMember.filter are mutually exclusive, specify only one.

   loadPhotos

   Developer Hub loads photos by default. Enter false to avoid loading user photos.

   select

   Enter the Microsoft Graph resource type list to retrieve.

   userGroupMember

   Add this section to use group membership to get users.

   filter

   Enter your filter to filter groups and fetch their members.

   This parameter and user.filter are mutually exclusive, specify only one.

   search

   Enter your search query to search for groups and fetch their members.

   This parameter and user.filter are mutually exclusive, specify only one.

   group

   Enter your configuration to get groups.

   expand

   Enter your expansion parameter to include the expanded resource or collection referenced by a single relationship (navigation property) in your results. A single request can expand only one relationship. See Customize Microsoft Graph responses with query parameters.

   You can combine this parameter with user.filter or userGroupMember.filter.

   filter

   Enter your group filter parameter. See Microsoft Graph API query group syntax.

   search

   Enter your group search parameter. See Microsoft Graph API query search parameter.

   select

   Enter the Microsoft Graph resource type list to retrieve.

6. Enable Azure authentication, by adding the Microsoft authentication provider to your app-config.yaml file content:

   auth:
     environment: production
     providers:
       microsoft:
         production:
           clientId: ${MICROSOFT_CLIENT_ID}
           clientSecret: ${MICROSOFT_CLIENT_SECRET}
           tenantId: ${MICROSOFT_TENANT_ID}
   signInPage: microsoft

   environment

   Enter production to disable the Guest login option in the Developer Hub login page.

   clientId

   Enter the configured secret variable name: ${MICROSOFT_CLIENT_ID}.

   clientSecret

   Enter the configured secret variable name: ${MICROSOFT_CLIENT_SECRET}.

   tenantId

   Enter the configured secret variable name: ${MICROSOFT_TENANT_ID}.

   signInPage

   Enter microsoft to set the Azure provider as your Developer Hub sign-in provider.

7. Optional: Add optional fields to the Microsoft authentication provider section in your app-config.yaml file:

   auth:
     environment: production
     providers:
       microsoft:
         production:
           clientId: ${MICROSOFT_CLIENT_ID}
           clientSecret: ${MICROSOFT_CLIENT_SECRET}
           tenantId: ${MICROSOFT_TENANT_ID}
           domainHint: ${MICROSOFT_TENANT_ID}
           additionalScopes:
              - Mail.Send
           sessionDuration:
             hours: 24
           signIn:
             resolvers:
               - resolver: usernameMatchingUserEntityName
                 dangerouslyAllowSignInWithoutUserInCatalog: true
   signInPage: microsoft

   domainHint

   • Leave this parameter empty, or enter the tenant ID when your application registration is single-tenant.
   • Leave this parameter empty when your application registration is multi-tenant.

   • Enter the tenant ID to reduce login friction for users with accounts in multiple tenants, by automatically filtering out accounts from other tenants.

     For more information, see Home Realm Discovery.

   additionalScopes

   Enter the list of additional scopes to add scopes for the application registration. The default and mandatory value lists following scopes:

   • openid
   • offline_access
   • profile
   • email
   • User.Read

   sessionDuration

   Lifespan of the user session. Enter a duration in ms library (such as '24h', '2 days'), ISO duration, or "human duration" format.

   signIn.resolvers

   After successful authentication, Developer Hub resolves the user signing in to an existing user in the Developer Hub catalog. To best match users securely for your use case, consider configuring a specific resolver.

   Enter the resolver list to override the default resolver: userIdMatchingUserEntityAnnotation.

   The authentication provider tries each sign-in resolver in order until it succeeds, and fails if none succeed.

   Warning

   In production mode, configure only one resolver to make sure users are securely matched.

   resolver

   Enter the sign-in resolver name. Available resolvers:

   emailMatchingUserEntityAnnotation

   Use this resolver to look up the user by matching their Microsoft email to the email entity annotation.

   emailLocalPartMatchingUserEntityName

   Use this resolver to look up the user by matching their Microsoft email user name to the user entity name.

   emailMatchingUserEntityProfileEmail

   Use this resolver to look up the user by matching their Microsoft email to the user entity profile email.

   dangerouslyAllowSignInWithoutUserInCatalog

   Enter true to configure the sign-in resolver to bypass the user provisioning requirement in the Developer Hub software catalog.

   Warning

   In production mode, do not enable dangerouslyAllowSignInWithoutUserInCatalog.

Verification

1. To verify user and group provisioning, check the console logs for MicrosoftGraphOrgEntityProvider events.

   Successful synchronization example:

   2025-06-23T13:37:55.804Z catalog info Read 9 msgraph users and 3 msgraph groups in 1.5 seconds. Committing... class="MicrosoftGraphOrgEntityProvider" taskId="MicrosoftGraphOrgEntityProvider:providerId:refresh" taskInstanceId="e104a116-6481-4ceb-9bc4-0f8f9581f959" trace_id="e4c633659cffd6b1529afa55a5bfbad7" span_id="76affd0420e8baa6" trace_flags="01"
   
   2025-06-23T13:37:55.811Z catalog info Committed 9 msgraph users and 3 msgraph groups in 0.0 seconds. class="MicrosoftGraphOrgEntityProvider" taskId="MicrosoftGraphOrgEntityProvider:providerId:refresh" taskInstanceId="e104a116-6481-4ceb-9bc4-0f8f9581f959" trace_id="e4c633659cffd6b1529afa55a5bfbad7" span_id="76affd0420e8baa6" trace_flags="01"

2. To verify Azure user authentication:

   1. Go to the Developer Hub login page.
   2. Your Developer Hub sign-in page displays Sign in using Microsoft and the Guest user sign-in is disabled.
   3. Log in with an Azure account.