Chapter 4. Authentication with Microsoft Azure To authenticate users with Microsoft Azure: Enable authentication with Microsoft Azure . Provision users from Microsoft Azure to the software catalog . 4.1. Enabling authentication with Microsoft Azure Red Hat Developer Hub includes a Microsoft Azure authentication provider that can authenticate users by using OAuth. Prerequisites 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 To allow Developer Hub to authenticate with Microsoft Azure, create an OAuth application in Microsoft Azure . 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> . 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. 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 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 administrator consent, a directory administrator must go to the admin consent page and click Grant admin consent for COMPANY NAME . On the Home > App registrations > <My Developer Hub> > Manage > Certificates & Secrets page, in the Client secrets tab, create a New client secret . Save for the step: Directory (tenant) ID Application (client) ID Application (client) secret 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 . Set up the Microsoft Azure authentication provider in your Developer Hub custom configuration, such as app-config-rhdh : app-config-rhdh.yaml fragment auth: environment: production providers: microsoft: production: clientId: USD{AUTH_AZURE_CLIENT_ID} clientSecret: USD{AUTH_AZURE_CLIENT_SECRET} tenantId: USD{AUTH_AZURE_TENANT_ID} signInPage: microsoft environment: production Mark the environment as production to hide the Guest login in the Developer Hub home page. clientId , clientSecret and tenantId Use the Developer Hub application information that you have created in Microsoft Azure and configured in OpenShift as secrets. signInPage: microsoft Enable the Microsoft Azure provider as default sign-in provider. Optional: Consider adding following optional fields: dangerouslyAllowSignInWithoutUserInCatalog: true To enable authentication without requiring to provision users 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 authenticating users absent from the software catalog auth: environment: production providers: microsoft: production: clientId: USD{AUTH_AZURE_CLIENT_ID} clientSecret: USD{AUTH_AZURE_CLIENT_SECRET} tenantId: USD{AUTH_AZURE_TENANT_ID} signInPage: microsoft dangerouslyAllowSignInWithoutUserInCatalog: true 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-rhdh.yaml fragment with optional domainHint field auth: environment: production providers: microsoft: production: domainHint: USD{AUTH_AZURE_TENANT_ID} 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-rhdh.yaml fragment with optional additionalScopes field auth: environment: production providers: microsoft: production: additionalScopes: - Mail.Send 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. 4.2. 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: app-config.yaml fragment with mandatory microsoftGraphOrg fields dangerouslyAllowSignInWithoutUserInCatalog: false catalog: providers: microsoftGraphOrg: providerId: target: https://graph.microsoft.com/v1.0 tenantId: USD{AUTH_AZURE_TENANT_ID} clientId: USD{AUTH_AZURE_CLIENT_ID} clientSecret: USD{AUTH_AZURE_CLIENT_SECRET} dangerouslyAllowSignInWithoutUserInCatalog: false Allow authentication only for users in the Developer Hub software catalog. 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. Optional: Consider adding the following optional microsoftGraphOrg.providerId fields: authority: https://login.microsoftonline.com Defines the authority used. Change the value to use a different authority , such as Azure US government. Default value: https://login.microsoftonline.com . app-config.yaml fragment with optional queryMode field catalog: providers: microsoftGraphOrg: providerId: authority: https://login.microsoftonline.com/ queryMode: basic | advanced By default, the Microsoft Graph API only provides the basic feature set for querying. Certain features require advanced querying capabilities. See Microsoft Azure Advanced queries . app-config.yaml fragment with optional queryMode field catalog: providers: microsoftGraphOrg: providerId: queryMode: advanced user.expand To include the expanded resource or collection referenced by a single relationship (navigation property) in your results. Only one relationship can be expanded in a single request. See Microsoft Graph query expand parameter . This parameter can be combined with ] or xref:userFilter[ . app-config.yaml fragment with optional user.expand field catalog: providers: microsoftGraphOrg: providerId: user: expand: manager user.filter To filter users. See Microsoft Graph API and Microsoft Graph API query filter parameters syntax . This parameter and ???TITLE??? are mutually exclusive, only one can be specified. app-config.yaml fragment with optional user.filter field catalog: providers: microsoftGraphOrg: providerId: user: filter: accountEnabled eq true and userType eq 'member' user.loadPhotos: true | false Load photos by default. Set to false to not load user photos. app-config.yaml fragment with optional user.loadPhotos field catalog: providers: microsoftGraphOrg: providerId: user: loadPhotos: true user.select Define the Microsoft Graph resource types to retrieve. app-config.yaml fragment with optional user.select field catalog: providers: microsoftGraphOrg: providerId: user: select: ['id', 'displayName', 'description'] userGroupMember.filter To use group membership to get users. To filter groups and fetch their members. This parameter and ???TITLE??? are mutually exclusive, only one can be specified. app-config.yaml fragment with optional userGroupMember.filter field catalog: providers: microsoftGraphOrg: providerId: userGroupMember: filter: "displayName eq 'Backstage Users'" userGroupMember.search To use group membership to get users. To search for groups and fetch their members. This parameter and ???TITLE??? are mutually exclusive, only one can be specified. app-config.yaml fragment with optional userGroupMember.search field catalog: providers: microsoftGraphOrg: providerId: userGroupMember: search: '"description:One" AND ("displayName:Video" OR "displayName:Drive")' group.expand Optional parameter to include the expanded resource or collection referenced by a single relationship (navigation property) in your results. Only one relationship can be expanded in a single request. See https://docs.microsoft.com/en-us/graph/query-parameters#expand-parameter This parameter can be combined with ] instead of xref:userFilter[ . app-config.yaml fragment with optional group.expand field catalog: providers: microsoftGraphOrg: providerId: group: expand: member group.filter To filter groups. See Microsoft Graph API query group syntax . app-config.yaml fragment with optional group.filter field catalog: providers: microsoftGraphOrg: providerId: group: filter: securityEnabled eq false and mailEnabled eq true and groupTypes/any(c:c+eq+'Unified') group.search To search for groups. See Microsoft Graph API query search parameter . app-config.yaml fragment with optional group.search field catalog: providers: microsoftGraphOrg: providerId: group: search: '"description:One" AND ("displayName:Video" OR "displayName:Drive")' group.select To define the Microsoft Graph resource types to retrieve. app-config.yaml fragment with optional group.select field catalog: providers: microsoftGraphOrg: providerId: group: select: ['id', 'displayName', 'description'] schedule.frequency To specify custom schedule frequency. Supports cron, ISO duration, and "human duration" as used in code. app-config.yaml fragment with optional schedule.frequency field catalog: providers: microsoftGraphOrg: providerId: schedule: frequency: { hours: 1 } schedule.timeout To specify custom timeout. Supports ISO duration and "human duration" as used in code. app-config.yaml fragment with optional schedule.timeout field catalog: providers: microsoftGraphOrg: providerId: schedule: timeout: { minutes: 50 } schedule.initialDelay To specify custom initial delay. Supports ISO duration and "human duration" as used in code. app-config.yaml fragment with optional schedule.initialDelay field catalog: providers: microsoftGraphOrg: providerId: schedule: initialDelay: { seconds: 15} Verification Check the console logs to verify that the synchronization is completed. Successful synchronization example: backend:start: {"class":"MicrosoftGraphOrgEntityProviderUSD1","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":"MicrosoftGraphOrgEntityProviderUSD1","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"} Log in with a Microsoft Azure account.

Commands:
auth: environment: production providers: microsoft: production: clientId: USD{AUTH_AZURE_CLIENT_ID} clientSecret: USD{AUTH_AZURE_CLIENT_SECRET} tenantId: USD{AUTH_AZURE_TENANT_ID} signInPage: microsoft
auth: environment: production providers: microsoft: production: clientId: USD{AUTH_AZURE_CLIENT_ID} clientSecret: USD{AUTH_AZURE_CLIENT_SECRET} tenantId: USD{AUTH_AZURE_TENANT_ID} signInPage: microsoft dangerouslyAllowSignInWithoutUserInCatalog: true
auth: environment: production providers: microsoft: production: domainHint: USD{AUTH_AZURE_TENANT_ID}
auth: environment: production providers: microsoft: production: additionalScopes: - Mail.Send
dangerouslyAllowSignInWithoutUserInCatalog: false catalog: providers: microsoftGraphOrg: providerId: target: https://graph.microsoft.com/v1.0 tenantId: USD{AUTH_AZURE_TENANT_ID} clientId: USD{AUTH_AZURE_CLIENT_ID} clientSecret: USD{AUTH_AZURE_CLIENT_SECRET}
catalog: providers: microsoftGraphOrg: providerId: authority: https://login.microsoftonline.com/
catalog: providers: microsoftGraphOrg: providerId: queryMode: advanced
catalog: providers: microsoftGraphOrg: providerId: user: expand: manager
catalog: providers: microsoftGraphOrg: providerId: user: filter: accountEnabled eq true and userType eq 'member'
catalog: providers: microsoftGraphOrg: providerId: user: loadPhotos: true
catalog: providers: microsoftGraphOrg: providerId: user: select: ['id', 'displayName', 'description']
catalog: providers: microsoftGraphOrg: providerId: userGroupMember: filter: "displayName eq 'Backstage Users'"
catalog: providers: microsoftGraphOrg: providerId: userGroupMember: search: '"description:One" AND ("displayName:Video" OR "displayName:Drive")'
catalog: providers: microsoftGraphOrg: providerId: group: expand: member
catalog: providers: microsoftGraphOrg: providerId: group: filter: securityEnabled eq false and mailEnabled eq true and groupTypes/any(c:c+eq+'Unified')
catalog: providers: microsoftGraphOrg: providerId: group: search: '"description:One" AND ("displayName:Video" OR "displayName:Drive")'
catalog: providers: microsoftGraphOrg: providerId: group: select: ['id', 'displayName', 'description']
catalog: providers: microsoftGraphOrg: providerId: schedule: frequency: { hours: 1 }
catalog: providers: microsoftGraphOrg: providerId: schedule: timeout: { minutes: 50 }
catalog: providers: microsoftGraphOrg: providerId: schedule: initialDelay: { seconds: 15}
backend:start: {"class":"MicrosoftGraphOrgEntityProviderUSD1","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":"MicrosoftGraphOrgEntityProviderUSD1","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"}