Chapter 5. 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
      • 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.

        1. 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

        Note

        This step is optional for environments with outgoing access restrictions, such as firewall rules. If your environment has such restrictions, ensure that your RHDH backend can access the following hosts:

        • login.microsoftonline.com: For obtaining and exchanging authorization codes and access tokens.
        • graph.microsoft.com: For retrieving user profile information (as referenced in the source code). If this host is unreachable, you might see an Authentication failed, failed to fetch user profile error when attempting to log in.

        = Provisioning users from Microsoft Azure to the software catalog

        To authenticate users with Microsoft Azure, after Enabling authentication with Microsoft Azure, provision users from Microsoft Azure to the Developer Hub software catalog.

        Prerequisites

        • You have enabled authentication with Microsoft Azure.

        Procedure

        • To enable Microsoft Azure member discovery, edit your custom Developer Hub ConfigMap, such as app-config-rhdh, and add following lines to the app-config.yaml content:

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.