Verification

1. Go to the Developer Hub login page.
2. To log in with the Guest user account, click Enter in the Guest tile.
3. In the Developer Hub Settings page, your profile name is Guest.
4. You can use Developer Hub features.

Verification

1. Go to the Developer Hub login page.
2. To log in with the Guest user account, click Enter in the Guest tile.
3. In the Developer Hub Settings page, your profile name is Guest.
4. You can use Developer Hub features.

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.

   userQuerySize

   Enter the user count to query simultaneously. Default value: 100.

   catalog:
     providers:
       keycloakOrg:
         default:
           userQuerySize: 100

   groupQuerySize

   Enter the group count to query simultaneously. Default value: 100.

   catalog:
     providers:
       keycloakOrg:
         default:
           groupQuerySize: 100

   schedule.frequency

   Enter the schedule frequency. Supports cron, ISO duration, and "human duration" as used in code.

   catalog:
     providers:
       keycloakOrg:
         default:
           schedule:
             frequency: { hours: 1 }

   schedule.timeout

   Enter the timeout for the user provisioning job. Supports ISO duration and "human duration" as used in code.

   catalog:
     providers:
       keycloakOrg:
         default:
           schedule:
             timeout: { minutes: 50 }

   schedule.initialDelay

   Enter the initial delay to wait for before starting the user provisioning job. Supports ISO duration and "human duration" as used in code.

   catalog:
     providers:
       keycloakOrg:
         default:
           schedule:
             initialDelay: { seconds: 15}

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.

   callbackUrl

   RHBK callback URL.

   auth:
     providers:
       oidc:
         production:
           callbackUrl: ${KEYCLOAK_CALLBACK_URL}

   tokenEndpointAuthMethod

   Token endpoint authentication method.

   auth:
     providers:
       oidc:
         production:
           tokenEndpointAuthMethod: ${KEYCLOAK_TOKEN_ENDPOINT_METHOD}

   tokenSignedResponseAlg

   Token signed response algorithm.

   auth:
     providers:
       oidc:
         production:
           tokenSignedResponseAlg: ${KEYCLOAK_SIGNED_RESPONSE_ALG}

   additionalScopes

   Enter additional RHBK scopes to request for during the authentication flow.

   auth:
     providers:
       oidc:
         production:
           additionalScopes: ${KEYCLOAK_SCOPE}

   signIn

   resolvers

   After successful authentication, the user signing in must be resolved 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: oidcSubClaimMatchingKeycloakUserId.

   Available values:

   oidcSubClaimMatchingKeycloakUserId

   Matches the user with the immutable sub parameter from OIDC to the RHBK user ID. Consider using this resolver for enhanced security.

   emailLocalPartMatchingUserEntityName

   Matches the email local part with the user entity name.

   emailMatchingUserEntityProfileEmail

   Matches the email with the user entity profile email.

   preferredUsernameMatchingUserEntityName

   Matches the preferred username with the user entity name.

   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.

   auth:
     providers:
       oidc:
         production:
           signIn:
             resolvers:
               - resolver: oidcSubClaimMatchingKeycloakUserId
               - resolver: preferredUsernameMatchingUserEntityName
               - resolver: emailMatchingUserEntityProfileEmail
               - resolver: emailLocalPartMatchingUserEntityName

   dangerouslyAllowSignInWithoutUserInCatalog: true

   Configure the sign-in resolver to bypass the user provisioning requirement in the Developer Hub software catalog.

   Warning

   Use this option to explore Developer Hub features, but do not use it in production.

   auth:
     environment: production
     providers:
       oidc:
         production:
           metadataUrl: ${KEYCLOAK_BASE_URL}
           clientId: ${KEYCLOAK_CLIENT_ID}
           clientSecret: ${KEYCLOAK_CLIENT_SECRET}
           signIn:
             resolvers:
               - resolver: oidcSubClaimMatchingKeycloakUserID
                 dangerouslyAllowSignInWithoutUserInCatalog: true
   signInPage: oidc

   sessionDuration

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

   auth:
     providers:
       github:
         production:
           sessionDuration: { hours: 24 }

   auth

   backstageTokenExpiration

   To modify the Developer Hub token expiration from its default value of one hour, note that this refers to the validity of short-term cryptographic tokens, not the session duration. The expiration value must be set between 10 minutes and 24 hours.

   auth:
     backstageTokenExpiration: { minutes: <user_defined_value> }

   Warning

   For security, consider that if multiple valid refresh tokens are issued due to frequent refresh token requests, older tokens will remain valid until they expire. To enhance security and prevent potential misuse of older tokens, enable a refresh token rotation strategy in your RHBK realm.

   1. From the Configure section of the navigation menu, click Realm Settings.
   2. From the Realm Settings page, click the Tokens tab.
   3. From the Refresh tokens section of the Tokens tab, toggle the Revoke Refresh Token to the Enabled position.

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. Create a new backend module with the yarn new command.

2. Add your custom user and group transformers to the keycloakTransformerExtensionPoint.

   The following is an example plugins/<module_name>/src/module.ts file defining the backend module:

   import {
     GroupTransformer,
     keycloakTransformerExtensionPoint,
     UserTransformer,
   } from '@backstage-community/plugin-catalog-backend-module-keycloak';
   
   const customGroupTransformer: GroupTransformer = async (
     entity, // entity output from default parser
     realm, // Keycloak realm name
     groups, // Keycloak group representation
   ) => {
     /* apply transformations */
     return entity;
   };
   const customUserTransformer: UserTransformer = async (
     entity, // entity output from default parser
     user, // Keycloak user representation
     realm, // Keycloak realm name
     groups, // Keycloak group representation
   ) => {
     /* apply transformations */
     return entity;
   };
   
   export const keycloakBackendModuleTransformer = createBackendModule({
     pluginId: 'catalog',
     moduleId: 'keycloak-transformer',
     register(reg) {
       reg.registerInit({
         deps: {
           keycloak: keycloakTransformerExtensionPoint,
         },
         async init({ keycloak }) {
           keycloak.setUserTransformer(customUserTransformer);
           keycloak.setGroupTransformer(customGroupTransformer);
           /* highlight-add-end */
         },
       });
     },
   });

   Important

   Set the module’s pluginId to catalog to match the pluginId of the keycloak-backend; otherwise, the module fails to initialize.

3. Install this new backend module into your Developer Hub backend.

   backend.add(import(backstage-plugin-catalog-backend-module-keycloak-transformer))

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.

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 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. To set up the GitHub authentication provider as an auxiliary authentication provider, add the auth.providers.github section to your app-config.yaml file:

   auth:
     providers:
       github:
         production:
           clientId: ${GITHUB_CLIENT_ID}
           clientSecret: ${GITHUB_CLIENT_SECRET}
           disableIdentityResolution: true

   where: clientId:: Enter the configured secret variable name: ${GITHUB_CLIENT_ID}.

   clientSecret

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

   disableIdentityResolution

   Enter `true`to skip user identity resolution for this provider to enable sign-in from an auxiliary authentication provider. Do not enable this setting on the primary authentication provider you plan on using for sign-in and identity management.

Verification

1. Go to the Developer Hub login page.
2. Log in with your primary authentication provider account.
3. In the top user menu, go to Settings > Authentication Providers.
4. In the GitHub line, click the Sign in button and log in.
5. In the GitHub line, the button displays Sign out.