Procedure

1. To allow Developer Hub to authenticate with RHBK, complete the steps in RHBK, to create a realm and a user and secure the first application:

   1. Use an existing realm, or create a realm, with a distinctive Name such as <my_realm>. Save the value for the next step:

      • RHBK realm base URL, such as: <your_rhbk_URL>/realms/<your_realm>.

   2. To register your Developer Hub in RHBK, in the created realm, secure the first application, with:

      1. Client ID: A distinctive client ID, such as <RHDH>.
      2. Valid redirect URIs: Set to the OIDC handler URL: https://<my_developer_hub_domain>/api/auth/oidc/handler/frame.
      3. Go to the Credentials tab and copy the Client secret.

      4. Save the values for the next step:

         • Client ID
         • Client Secret
   3. To prepare for the verification steps, in the same realm, get the credential information for an existing user or create a user. Save the user credential information for the verification steps.

2. To add your RHSSO 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 environment variable name.

   KEYCLOAK_CLIENT_ID

   Enter the saved Client ID.

   KEYCLOAK_CLIENT_SECRET

   Enter the saved Client Secret.

   KEYCLOAK_BASE_URL

   Enter the saved RHBK realm base URL.

3. Enable the Keycloak organization plugin (backstage-plugin-catalog-backend-module-keycloak-dynamic) in your dynamic-plugins.yaml file. The plugin is named after RHBK upstream project. This plugin imports RHBK users and groups to the Developer Hub software catalog.

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

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

   catalog:
     providers:
       keycloakOrg:
         default:
           baseUrl: ${KEYCLOAK_BASE_URL}
           clientId: ${KEYCLOAK_CLIENT_ID}
           clientSecret: ${KEYCLOAK_CLIENT_SECRET}
           realm: master
           loginRealm: master

   baseUrl

   Enter your RHBK server URL, defined earlier.

   clientId

   Enter your Developer Hub application client ID in RHBK, defined earlier.

   clientSecret

   Enter your Developer Hub application client secret in RHBK, defined earlier.

   realm

   Enter the realm name to provision users, such as master.

   loginRealm

   Enter the realm name to authenticate users, such as master.

   Optional: Add optional fields. See Configuring Red Hat Developer Hub.

5. To set up the RHBK authentication provider in your Developer Hub custom configuration, edit your custom Developer Hub ConfigMap such as app-config-rhdh, and add the following lines to the app-config.yaml content:

   auth:
     environment: production
     providers:
       oidc:
         production:
           metadataUrl: ${KEYCLOAK_BASE_URL}
           clientId: ${KEYCLOAK_CLIENT_ID}
           clientSecret: ${KEYCLOAK_CLIENT_SECRET}
           prompt: auto
   signInPage: oidc

   environment: production

   Mark the environment as production to hide the Guest login in the Developer Hub home page.

   metadataUrl, clientId, clientSecret

   To configure the OIDC provider with your secrets.

   sigInPage: oidc

   To enable the OIDC provider as default sign-in provider.

   prompt: auto

   To allow the identity provider to automatically determine whether to prompt for credentials or bypass the login redirect if an active RHSSO session exists.

   Note

   If prompt: auto is not set, the identity provider defaults to prompt: none, which assumes that you are already logged in and rejects sign-in requests without an active session.

   Optional: Add optional fields. See Configuring Red Hat Developer Hub.

Verification

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

   Successful synchronization example:

   2025-06-27T16:02:34.647Z catalog info Read 5 Keycloak users and 3 Keycloak groups in 0.4 seconds. Committing... class="KeycloakOrgEntityProvider" taskId="KeycloakOrgEntityProvider:default:refresh" taskInstanceId="db55c34b-46b3-402b-b12f-2fbc48498e82" trace_id="606f80a9ce00d1c86800718c4522f7c6" span_id="7ebc2a254a546e90" trace_flags="01"
   
   2025-06-27T16:02:34.650Z catalog info Committed 5 Keycloak users and 3 Keycloak groups in 0.0 seconds. class="KeycloakOrgEntityProvider" taskId="KeycloakOrgEntityProvider:default:refresh" taskInstanceId="db55c34b-46b3-402b-b12f-2fbc48498e82" trace_id="606f80a9ce00d1c86800718c4522f7c6" span_id="7ebc2a254a546e90" trace_flags="01"

2. To verify RHBK user authentication:

   1. Go to the Developer Hub login page.
   2. Your Developer Hub sign-in page displays Sign in using OIDC and the Guest user sign-in is disabled.
   3. Log in with OIDC by using the saved Username and Password values.

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, use short-lived tokens, scale with the number of installations by avoiding rate limits, and have a more transparent integration by avoiding to request user input.

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

      Authorization callback URL

      Enter your Developer Hub authentication backend URL: https://<my_developer_hub_domain>/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 environment variable name.

   GITHUB_CLIENT_ID

   Enter the saved Client ID.

   GITHUB_CLIENT_SECRET

   Enter the saved Client Secret.

   GITHUB_URL

   Enter the GitHub host domain: github.com.

   GITHUB_ORG

   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 imports 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. Provision GitHub users and groups to the Developer Hub software catalog by adding the catalog.providers.githubOrg section to your custom Developer Hub app-config.yaml configuration file:

   catalog:
     providers:
       githubOrg:
         id: githuborg
         githubUrl: "${GITHUB_URL}"
         orgs: [ "${GITHUB_ORG}" ]
         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 or conflicts.

   githubUrl

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

   orgs

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

   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 your app-config.yaml file:

   auth:
     environment: production
     providers:
       github:
         production:
           clientId: ${GITHUB_CLIENT_ID}
           clientSecret: ${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: ${GITHUB_CLIENT_ID}.

   clientSecret

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

   signInPage

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

   Optional: Consider adding optional fields. See Configuring Red Hat Developer Hub.

Verification

1. Verify user and group provisioning by checking 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 many 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_domain>/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 here and in your 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) in your dynamic-plugins.yaml file. This plugin imports Azure users and groups to the Developer Hub software catalog.

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

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:

   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 optional fields. See Configuring Red Hat Developer Hub.

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

   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: Add optional fields. See Configuring Red Hat Developer Hub.

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.

Procedure

1. Go to Administration at the bottom of the sidebar in the Developer Hub.

   The RBAC tab appears, displaying all the created roles in the Developer Hub.

2. (Optional) Click any role to view the role information on the OVERVIEW page.
3. Click CREATE to create a role.
4. Enter the name and description of the role in the given fields and click NEXT.
5. Add users and groups using the search field, and click NEXT.
6. Select Plugin and Permission from the drop-downs in the Add permission policies section.
7. Select or clear the Policy that you want to set in the Add permission policies section, and click NEXT.
8. Review the added information in the Review and create section.
9. Click CREATE.

Procedure

1. Go to Administration at the bottom of the sidebar in the Developer Hub.

   The RBAC tab appears, displaying all the created roles in the Developer Hub.

2. (Optional) Click any role to view the role information on the OVERVIEW page.
3. Select the edit icon for the role that you want to edit.
4. Edit the details of the role, such as name, description, users and groups, and permission policies, and click NEXT.
5. Review the edited details of the role and click SAVE.

Procedure

1. Go to Administration at the bottom of the sidebar in the Developer Hub.

   The RBAC tab appears, displaying all the created roles in the Developer Hub.

2. (Optional) Click any role to view the role information on the OVERVIEW page.

3. Select the delete icon from the Actions column for the role that you want to delete.

   Delete this role? pop-up appears on the screen.

4. Click DELETE.