Chapter 4. Authentication with Microsoft Azure

Prerequisites

1. You have the permission to register an application in Microsoft Azure.

   • You added a custom Developer Hub application configuration, and have sufficient permissions to modify it.

Procedure

1. To allow Developer Hub to authenticate with Microsoft Azure, create an OAuth application in Microsoft Azure.

   1. In the Azure portal go to App registrations, create a New registration with the configuration:

      Name

      The application name in Azure, such as <My Developer Hub>.

   2. On the Home > App registrations > <My Developer Hub> > Manage > Authentication page, Add a platform, with the following configuration:

      Redirect URI

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

      Front-channel logout URL

      Leave blank.

      Implicit grant and hybrid flows

      Leave all checkboxes cleared.

   3. On the Home > App registrations > <My Developer Hub> > Manage > API permissions page, Add a Permission, then add the following Delegated permission for the Microsoft Graph API:

      • email
      • offline_access
      • openid
      • profile
      • User.Read.All
      • GroupMember.Read.All
      • Optional custom scopes for the Microsoft Graph API that you define both in this section and in the app-config.yaml Developer Hub configuration file.

1. On the Home > App registrations > <My Developer Hub> > Manage > Certificates & Secrets page, in the Client secrets tab, create a New client secret.

2. Save for the next step:

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

   • Application (client) secret

     1. To add your Microsoft Azure credentials to Developer Hub, add the following key/value pairs to your Developer Hub secrets:

        AUTH_AZURE_TENANT_ID

        Enter your saved Directory (tenant) ID.

        AUTH_AZURE_CLIENT_ID

        Enter your saved Application (client) ID.

        AUTH_AZURE_CLIENT_SECRET

        Enter your saved Application (client) secret.

     2. Set up the Microsoft Azure authentication provider in your app-config.yaml file:

        app-config.yaml file fragment

        auth:
          environment: production 

        1

        
          providers:
            microsoft:
              production:
                clientId: ${AUTH_AZURE_CLIENT_ID} 

        2

        
                clientSecret: ${AUTH_AZURE_CLIENT_SECRET}
                tenantId: ${AUTH_AZURE_TENANT_ID}
        signInPage: microsoft 

        3

        Copy to Clipboard Toggle word wrap

        1

        Mark the environment as production and disable the Guest login option in the Developer Hub login page.

        2

        Apply the Microsoft Azure credentials configured in your Developer Hub secrets.

        3

        Set the Microsoft Azure provider as your Developer Hub sign-in provider.

3. Optional: Consider adding following optional fields:

   domainHint

   Optional for single-tenant applications. You can reduce login friction for users with accounts in multiple tenants by automatically filtering out accounts from other tenants. If you want to use this parameter for a single-tenant application, uncomment and enter the tenant ID. If your application registration is multi-tenant, leave this parameter blank. For more information, see Home Realm Discovery.

   app-config.yaml file fragment with optional domainHint field

   auth:
     environment: production
     providers:
       microsoft:
         production:
           domainHint: ${AUTH_AZURE_TENANT_ID}

   Copy to Clipboard Toggle word wrap

   additionalScopes

   Optional for additional scopes. To add scopes for the application registration, uncomment and enter the list of scopes that you want to add. The default and mandatory value lists: 'openid', 'offline_access', 'profile', 'email', 'User.Read'.

   app-config.yaml file fragment with optional additionalScopes field

   auth:
     environment: production
     providers:
       microsoft:
         production:
           additionalScopes:
              - Mail.Send

   Copy to Clipboard Toggle word wrap

   sessionDuration

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

   app-config-rhdh.yaml fragment with optional sessionDuration field

   auth:
     providers:
       microsoft:
         production:
           sessionDuration: { hours: 24 }

   Copy to Clipboard Toggle word wrap

   signIn

   resolvers

   After successful authentication, the user signing in must be resolved 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: emailLocalPartMatchingUserEntityName.

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

   Warning

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

   resolver

   Enter the sign-in resolver name. Available resolvers:

   • userIdMatchingUserEntityAnnotation
   • emailLocalPartMatchingUserEntityName
   • emailMatchingUserEntityProfileEmail

   dangerouslyAllowSignInWithoutUserInCatalog: true

   Configure the sign-in resolver to bypass the user provisioning requirement in the Developer Hub software catalog.

   Warning

   Use dangerouslyAllowSignInWithoutUserInCatalog to explore Developer Hub features, but do not use it in production.

   app-config-rhdh.yaml fragment with optional field to allow signing in users absent from the software catalog

   auth:
     environment: production
     providers:
       microsoft:
         production:
           clientId: ${AUTH_AZURE_CLIENT_ID}
           clientSecret: ${AUTH_AZURE_CLIENT_SECRET}
           tenantId: ${AUTH_AZURE_TENANT_ID}
           signIn:
             resolvers:
               - resolver: usernameMatchingUserEntityName
                 dangerouslyAllowSignInWithoutUserInCatalog: true
   signInPage: microsoft

   Copy to Clipboard Toggle word wrap

Procedure

1. Enable the backstage-plugin-catalog-backend-module-msgraph-dynamic plugin.

   dynamic-plugins.yaml file fragment

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

   Copy to Clipboard Toggle word wrap

2. To enable Microsoft Azure member discovery, edit app-config.yaml, your custom Developer Hub configuration file::

   app-config.yaml fragment with mandatory microsoftGraphOrg fields

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

   Copy to Clipboard Toggle word wrap

   target: https://graph.microsoft.com/v1.0

   Defines 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, clientId and clientSecret

   Use the Developer Hub application information you created in Microsoft Azure and configured in OpenShift as secrets.

   schedule

   frequency

   Enter the schedule frequency as cron, ISO duration, or human duration as used in code.

   timeout

   Enter the schedule timeout as ISO duration or human duration as used in code.

   initialDelay

   Enter the schedule initial delay as ISO duration or human duration as used in code.

   Tip

   In a large organization, this plugin can take a long time. Therefore, avoid setting a low frequency or timeout when importing a large number of users and groups for the first time.

Verification

1. Check the console logs to verify that the synchronization is completed.

   Successful synchronization example:

   backend:start: {"class":"MicrosoftGraphOrgEntityProvider$1","level":"info","message":"Read 1 msgraph users and 1 msgraph groups in 2.2 seconds. Committing...","plugin":"catalog","service":"backstage","taskId":"MicrosoftGraphOrgEntityProvider:default:refresh","taskInstanceId":"88a67ce1-c466-41a4-9760-825e16b946be","timestamp":"2024-06-26 12:23:42"}
   backend:start: {"class":"MicrosoftGraphOrgEntityProvider$1","level":"info","message":"Committed 1 msgraph users and 1 msgraph groups in 0.0 seconds.","plugin":"catalog","service":"backstage","taskId":"MicrosoftGraphOrgEntityProvider:default:refresh","taskInstanceId":"88a67ce1-c466-41a4-9760-825e16b946be","timestamp":"2024-06-26 12:23:42"}

   Copy to Clipboard Toggle word wrap

2. Log in with a Microsoft Azure account.