Procedure

1. Register your Developer Hub app in RHBK:

   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. Create a long, complex, and unique string to use as the Developer Hub session secret key.

3. Add your RHBK credentials and the session secret key to Developer Hub, by adding 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.

   KEYCLOAK_REALM

   Enter the realm name to provision users.

   KEYCLOAK_LOGIN_REALM

   Enter the realm name to authenticate users.

   SESSION_SECRET

   Enter the created session secret key.

4. Enable the Keycloak catalog provider plugin 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-community-plugin-catalog-backend-module-keycloak-dynamic'
       disabled: false

5. The OIDC provider authentication backend plugin requires Developer Hub to support sessions. Enable session support by adding the session secret to your app-config.yaml file:

   auth:
     session:
       secret: ${SESSION_SECRET}

6. Enable provisioning RHBK users and groups to the Developer Hub software catalog, by adding the catalog.providers.keycloakOrg section to your app-config.yaml file:

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

   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.

   loginRealm

   Enter the realm name to authenticate users.

   Optional: To configure optional fields, see Configuring Red Hat Developer Hub. :_mod-docs-content-type: SNIPPET

7. Enable the RHBK authentication provider, by adding the OIDC provider section in your app-config.yaml file:

   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

   Configure the OIDC provider with your secrets.

   prompt

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

   The identity provider defaults to none, which assumes that you are already logged in. Sign-in requests without an active session are rejected.

   signInPage

   Enter oidc to enable the OIDC provider as default sign-in provider.

   Optional: To configure optional fields, see Configuring Red Hat Developer Hub. :_mod-docs-content-type: SNIPPET

8. To disable the guest login option, in the app-config.yaml file, set the authentication environment to production:

   auth:
     environment: production

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. Allow Developer Hub to authenticate with GitHub, by creating a GitHub App.

   Note

   Use 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".

      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. Add your GitHub credentials to Developer Hub by adding 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: https://github.com.

   GITHUB_ORG

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

3. Enable the GitHub catalog provider plugin in your dynamic-plugins.yaml file to import GitHub users and groups to the Developer Hub software catalog.

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

4. Enable provisioning GitHub users and groups to the Developer Hub software catalog by adding the GitHub catalog provider section to your app-config.yaml 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.

   Warning

   Entities from this provider are associated with this identifier. Therefore, do not to change the identifier 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. Enable the GitHub authentication provider, by adding the GitHub authentication provider 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: To configure optional fields, see Configuring Red Hat Developer Hub. :_mod-docs-content-type: SNIPPET

6. To disable the guest login option, in the app-config.yaml file, set the authentication environment to production:

   auth:
     environment: production

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. Register your Developer Hub app in Azure, 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_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. Add your Azure credentials to Developer Hub, by adding the following key/value pairs to your Developer Hub secrets:

   MICROSOFT_TENANT_ID

   Enter your saved Directory (tenant) ID.

   MICROSOFT_CLIENT_ID

   Enter your saved Application (client) ID.

   MICROSOFT_CLIENT_SECRET

   Enter your saved Application (client) secret.

3. Enable the Microsoft Graph catalog provider plugin 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. Enable provisioning Azure users and groups to the Developer Hub software catalog, by adding the Microsoft Graph catalog provider section in your app-config.yaml file:

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

   clientId

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

   clientSecret

   Enter the configured secret variable name: ${MICROSOFT_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: To configure optional fields, see Configuring Red Hat Developer Hub. :_mod-docs-content-type: SNIPPET

5. Enable Azure authentication, by adding the Microsoft authentication provider to your app-config.yaml file content:

   auth:
     environment: production
     providers:
       microsoft:
         production:
           clientId: ${MICROSOFT_CLIENT_ID}
           clientSecret: ${MICROSOFT_CLIENT_SECRET}
           tenantId: ${MICROSOFT_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: ${MICROSOFT_CLIENT_ID}.

   clientSecret

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

   tenantId

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

   signInPage

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

   Optional: To configure optional fields, see Configuring Red Hat Developer Hub. :_mod-docs-content-type: SNIPPET

6. To disable the guest login option, in the app-config.yaml file, set the authentication environment to production:

   auth:
     environment: 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.

Procedure

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

   The RBAC tab is displayed, showing 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 is displayed, showing 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.

Verification

1. After saving the changes, you can view the edited details of the role on the OVERVIEW page of the role.
2. You can also edit a role’s users and groups or permissions by using the edit icon on the Users and Groups or Permissions cards on the OVERVIEW page.

Procedure

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

   The RBAC tab is displayed, showing 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.

   The Delete this role? pop-up is displayed on the screen.

4. Click DELETE.