See https://docs.google.com/document/d/1hzho44sCs1Y-m4UTy2kDuZg_0jm8LNJXruJDusAQ4aI/edit#heading=h.ck38crd9vlm

Chapter 4 - Authenticating with Microsoft Azure

S4.1 - Enabling authentication with Microsoft Azure

• DONE AI: [SME]: Where goes the “dangerouslyAllowSignInWithoutUserInCatalog” option go? See above
• AI: [Docs] Consistency: use RHDH_URL, note for environment: production, add prerequisites and verification

• Unchanged https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.2/html/authentication/proc-adding-azure-as-an-authentication-provider_title-authentication 

Red Hat Developer Hub includes a Microsoft Azure authentication provider that can authenticate users by using OAuth.

Prerequisites

• You added a custom RHDH application configuration. See https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.2/html/administration_guide_for_red_hat_developer_hub/assembly-add-custom-app-file-openshift_admin-rhdh.

Procedure

1. To allow Developer Hub to authenticate with Microsoft Azure, create an OAuth Application in Microsoft Azure.
2. Go to[ Azure Portal > App registrations|https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade], and create an App Registration for Developer Hub.
3. On your App registration overview page, add a new Web platform configuration, with the configuration:

• Redirect URI: Enter the backend authentication URI set in Developer Hub: https://<RHDH_URL>/api/auth/microsoft/handler/frame
• Front-channel logout URL: Leave blank.
• Implicit grant and hybrid flows: Leave all checkboxes cleared.

1. On the API permissions tab, click Add Permission, then add the following Delegated permission for the Microsoft Graph API:

• email
• offline_access
• openid
• profile
• User.Read
• Optional custom scopes of the Microsoft Graph API that you define both here and in the Developer Hub configuration (app-config-rhdh.yaml).
  NOTE: Your company might require you to grant admin consent for these permissions. Even if your company does not require admin consent, you might do so as it means users do not need to individually consent the first time they access backstage. To grant admin consent, a directory admin must go to the admin consent page and click Grant admin consent for COMPANY NAME.

1. Go to the Certificates & Secrets page, then the Client secrets tab, and create a new client secret. Save the Client secret for the next step.

1.  Add your Microsoft Azure credentials in your Developer Hub secrets.
2. Edit your Developer Hub secrets, such as secrets-rhdh.
3. Add the following key/value pairs:

• AUTH_AZURE_CLIENT_ID: Enter the Application ID that you generated on Microsoft Azure.
• AUTH_AZURE_CLIENT_SECRET: Enter the Client secret that you generated on Microsoft Azure.
• AUTH_AZURE_TENANT_ID: Enter your Tenant ID on Microsoft Azure.

1. Set up the Microsoft Azure authentication provider in your Developer Hub custom configuration.
   Edit your custom Developer Hub config map, such as app-config-rhdh.
   In the app-config-rhdh.yaml content, add the microsoft provider configuration under the root auth configuration, and enable the microsoft provider for sign-in:
   app-config-rhdh.yaml fragment
   auth:
     environment: production <1>
     providers:
       microsoft:
         production:
           clientId: ${AUTH_AZURE_CLIENT_ID}
           clientSecret: ${AUTH_AZURE_CLIENT_SECRET}
           tenantId: ${AUTH_AZURE_TENANT_ID}
           # domainHint: ${AUTH_AZURE_TENANT_ID} <2>
           # additionalScopes: <3>
             # - Mail.Send
   signInPage: microsoft <4>
   dangerouslyAllowSignInWithoutUserInCatalog: true <5>
2. <1> Marking the environment as production hides the Guest login in the RHDH home page.
3. <2> 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|https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/home-realm-discovery-policy].
4. <3> 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 is ['user.read'].
5. <4> To enable the Microsoft Azure provider as default sign-in provider.
   <5> To enable authentication without requiring to provision the software catalog.

Note: Optional for environments with restrictions on outgoing access, such as firewall rules. If your environment has outgoing access restrictions make sure your Backstage backend has access to the following hosts:

• login.microsoftonline.com: To get and exchange authorization codes and access tokens.
• graph.microsoft.com: To fetch user profile information (as seen in this source code). If this host is unreachable, users might see an Authentication failed, failed to fetch user profile error when they attempt to log in.

Verification

• Go to the RHDH login page. Log in with the Guest user account is disabled. Log in with Azure.

S4.2 - Provisioning users from Microsoft Azure

• AI: [SME+Docs] new content TBD msgraph README plugin: https://github.com/backstage/backstage/tree/master/plugins/catalog-backend-module-msgraph don't seem to see any product docs for this at the moment