1. Enable the OpenID Connect (OIDC) authentication provider in RHDH.
2. Provision users from Red Hat Build of Keycloak (RHBK) to the software catalog.

Procedure

1. To allow Developer Hub to authenticate with GitHub, create a GitHub App. Opt for a GitHub App instead of an OAuth app to use fine-grained permissions and use short-lived tokens.

   1. Register a GitHub App with the following configuration:

      GitHub App name

      Enter a unique name identifying your GitHub App, such as authenticating-with-rhdh-<GUID>.

      Homepage URL

      Enter your Developer Hub URL: https://<my_developer_hub_url>.

      Authorization callback URL

      Enter your Developer Hub authentication backend URL: https://<my_developer_hub_url>/api/auth/github/handler/frame.

      Webhook

      Clear "Active", as this is not needed for authentication and catalog providers.

      Organization permissions

      Enable Read-only access to Members.

      Where can this GitHub App be installed?

      Select Only on this account.

   2. In the General → Clients secrets section, click Generate a new client secret.
   3. In the Install App tab, choose an account to install your GitHub App on.

   4. Save the following values for the next step:

      • Client ID
      • Client secret

2. To add your GitHub credentials to Developer Hub, add the following key/value pairs to your Developer Hub secrets. You can use these secrets in the Developer Hub configuration files by using their respective environment variable name.

   AUTHENTICATION_GITHUB_CLIENT_ID

   Enter the saved Client ID.

   AUTHENTICATION_GITHUB_CLIENT_SECRET

   Enter the saved Client Secret.

   AUTHENTICATION_GITHUB_HOST_DOMAIN

   Enter the GitHub host domain: github.com.

   AUTHENTICATION_GITHUB_ORGANIZATION

   Enter your GitHub organization name, such as <your_github_organization_name>.

3. Enable the GitHub organization provisioning plugin (backstage-plugin-catalog-backend-module-github-org). This plugin ingests GitHub users and groups to the Developer Hub software catalog.

   dynamic-plugins.yaml file fragment

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

4. To provision GitHub users and groups to the Developer Hub software catalog, add the catalog.providers.githubOrg section to your custom Developer Hub app-config.yaml configuration file:

   app-config.yaml fragment with mandatory catalog.providers.githubOrg fields

   catalog:
     providers:
       githubOrg:
         id: githuborg
         githubUrl: "${AUTHENTICATION_GITHUB_HOST_DOMAIN}"
         orgs: [ "${AUTHENTICATION_GITHUB_ORGANIZATION}" ]
         schedule:
           frequency:
             minutes: 30
           initialDelay:
             seconds: 15
           timeout:
             minutes: 15

   id

   Enter a stable identifier for this provider, such as githuborg. Entities from this provider are associated with this identifier, therefore you must take care not to change it over time since that might lead to orphaned entities and/or conflicts.

   githubUrl

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

   orgs

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

   schedule.frequency

   Enter your schedule frequency, in the cron, ISO duration, or "human duration" format.

   schedule.timeout

   Enter your schedule timeout, in the ISO duration or "human duration" format.

   schedule.initialDelay

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

5. To set up the GitHub authentication provider, add the auth.providers.github section to the app-config.yaml file content:

   app-config.yaml file fragment with mandatory fields to enable authentication with GitHub

   auth:
     environment: production
     providers:
       github:
         production:
           clientId: ${AUTHENTICATION_GITHUB_CLIENT_ID}
           clientSecret: ${AUTHENTICATION_GITHUB_CLIENT_SECRET}
   signInPage: github

   environment

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

   clientId

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

   clientSecret

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

   signInPage

   Enter github to enable the GitHub provider as your Developer Hub sign-in provider.

   Optional: Consider adding the following optional fields:

   app-config.yaml file fragment including optional fields to enable authentication with GitHub

   auth:
     environment: production
     providers:
       github:
         production:
           clientId: ${AUTHENTICATION_GITHUB_CLIENT_ID}
           clientSecret: ${AUTHENTICATION_GITHUB_CLIENT_SECRET}
           callbackUrl: <your_intermediate_service_url/handler>
           sessionDuration: { hours: 24 }
           signIn:
             resolvers:
               - resolver: usernameMatchingUserEntityName
                 dangerouslyAllowSignInWithoutUserInCatalog: true
   signInPage: github

   callbackUrl

   Enter the callback URL that GitHub uses when initiating an OAuth flow, such as: <your_intermediate_service_url/handler>. Define it when Developer Hub is not the immediate receiver, such as in cases when you use one OAuth app for many Developer Hub instances.

   sessionDuration

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

   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: usernameMatchingUserEntityName.

   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:

   • usernameMatchingUserEntityName
   • preferredUsernameMatchingUserEntityName
   • 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.

Verification

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

   Successful synchronization example:

   {"class":"GithubMultiOrgEntityProvider","level":"info","message":"Reading GitHub users and teams for org: rhdh-dast","plugin":"catalog","service":"backstage","target":"https://github.com","taskId":"GithubMultiOrgEntityProvider:githuborg:refresh","taskInstanceId":"801b3c6c-167f-473b-b43e-e0b4b780c384","timestamp":"2024-09-09 23:55:58"}
   {"class":"GithubMultiOrgEntityProvider","level":"info","message":"Read 7 GitHub users and 2 GitHub groups in 0.4 seconds. Committing...","plugin":"catalog","service":"backstage","target":"https://github.com","taskId":"GithubMultiOrgEntityProvider:githuborg:refresh","taskInstanceId":"801b3c6c-167f-473b-b43e-e0b4b780c384","timestamp":"2024-09-09 23:55:59"}

2. To verify GitHub authentication:

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

Procedure

1. To allow Developer Hub to authenticate with Azure, Register an app 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_url>/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 in this section and in the 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. To add your Azure credentials to Developer Hub, add the following key/value pairs to your Developer Hub secrets:

   AUTHENTICATION_AZURE_TENANT_ID

   Enter your saved Directory (tenant) ID.

   AUTHENTICATION_AZURE_CLIENT_ID

   Enter your saved Application (client) ID.

   AUTHENTICATION_AZURE_CLIENT_SECRET

   Enter your saved Application (client) secret.

3. Enable the Microsoft Graph organization provisioning plugin (backstage-plugin-catalog-backend-module-msgraph-dynamic). This plugin ingests Azure users and groups to the Developer Hub software catalog.

   dynamic-plugins.yaml file fragment

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

   Important

   These features are for Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend using them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

   For more information on Red Hat Technology Preview features, see Technology Preview Features Scope.

4. To provision Azure users and groups to the Developer Hub software catalog, add the catalog.providers.microsoftGraphOrg section to your custom Developer Hub app-config.yaml configuration file:

   app-config.yaml fragment with mandatory microsoftGraphOrg fields

   catalog:
     providers:
       microsoftGraphOrg:
         providerId:
           target: https://graph.microsoft.com/v1.0
           tenantId: ${AUTHENTICATION_AZURE_TENANT_ID}
           clientId: ${AUTHENTICATION_AZURE_CLIENT_ID}
           clientSecret: ${AUTHENTICATION_AZURE_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: ${AUTHENTICATION_AZURE_TENANT_ID}.

   clientId

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

   clientSecret

   Enter the configured secret variable name: ${AUTHENTICATION_AZURE_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.

   Optional: Consider adding the following optional microsoftGraphOrg.providerId fields:

   authority

   Enter your Azure authority URL, when different from the default: https://login.microsoftonline.com.

   app-config.yaml fragment with optional queryMode field

   catalog:
     providers:
       microsoftGraphOrg:
         providerId:
           authority: https://login.microsoftonline.com/

   queryMode: basic | advanced

   Enter advanced when the default basic query mode is not sufficient for your queries to the Microsoft Graph API. 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 userGroupMember.filter or user.filter.

   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 userGroupMember.filter 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

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

   app-config.yaml fragment with optional user.loadPhotos field

   catalog:
     providers:
       microsoftGraphOrg:
         providerId:
           user:
             loadPhotos: true

   user.select

   Enter the Microsoft Graph resource type list 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 user.filter 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 user.filter 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 userGroupMember.filter instead of user.filter.

   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

   Enter the Microsoft Graph resource type list to retrieve.

   app-config.yaml fragment with optional group.select field

   catalog:
     providers:
       microsoftGraphOrg:
         providerId:
           group:
             select: ['id', 'displayName', 'description']

5. To set up the Azure authentication provider, add the auth.providers.microsoft section to your app-config.yaml file content:

   app-config.yaml file fragment with mandatory fields to enable authentication with Azure

   auth:
     environment: production
     providers:
       microsoft:
         production:
           clientId: ${AUTHENTICATION_AZURE_CLIENT_ID}
           clientSecret: ${AUTHENTICATION_AZURE_CLIENT_SECRET}
           tenantId: ${AUTHENTICATION_AZURE_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: ${AUTHENTICATION_AZURE_CLIENT_ID}.

   clientSecret

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

   tenantId

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

   signInPage

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

   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: ${AUTHENTICATION_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.yaml file fragment with optional additionalScopes field

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

   sessionDuration

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

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

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

   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, only configure one resolver to ensure users are securely matched.

   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: ${AUTHENTICATION_AZURE_CLIENT_ID}
           clientSecret: ${AUTHENTICATION_AZURE_CLIENT_SECRET}
           tenantId: ${AUTHENTICATION_AZURE_TENANT_ID}
           signIn:
             resolvers:
               - resolver: usernameMatchingUserEntityName
                 dangerouslyAllowSignInWithoutUserInCatalog: true
   signInPage: microsoft

   resolver

   Enter the sign-in resolver name. Available resolvers:

   emailMatchingUserEntityAnnotation:

   This resolver looks up the user by matching their Microsoft email to the email entity annotation.

   emailLocalPartMatchingUserEntityName:

   This resolver looks up the user by matching their Microsoft email user name to the user entity name.

   emailMatchingUserEntityProfileEmail:

   This resolver looks up the user by matching their Microsoft email to the user entity profile email.

   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.

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.