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. 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. Add your RHSSO 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.

   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 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-plugin-catalog-backend-module-keycloak-dynamic'
       disabled: false

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

5. Optional: Add optional fields to the keycloackOrg catalog provider section in your app-config.yaml file:

   catalog:
     providers:
       keycloakOrg:
         default:
           baseUrl: ${KEYCLOAK_BASE_URL}
           clientId: ${KEYCLOAK_CLIENT_ID}
           clientSecret: ${KEYCLOAK_CLIENT_SECRET}
           realm: master
           loginRealm: master
           userQuerySize: 100
           groupQuerySize: 100
           schedule:
             frequency: { hours: 1 }
             timeout: { minutes: 50 }
             initialDelay: { seconds: 15}

   userQuerySize

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

   groupQuerySize

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

   schedule

   frequency

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

   timeout

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

   initialDelay

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

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

   To 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 RHSSO session exists.

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

   signInPage

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

7. Optional: Add optional fields to the OIDC authentication provider section in your app-config.yaml file:

   auth:
     providers:
       oidc:
         production:
           metadataUrl: ${KEYCLOAK_BASE_URL}
           clientId: ${KEYCLOAK_CLIENT_ID}
           clientSecret: ${KEYCLOAK_CLIENT_SECRET}
           callbackUrl: ${KEYCLOAK_CALLBACK_URL}
           tokenEndpointAuthMethod: ${KEYCLOAK_TOKEN_ENDPOINT_METHOD}
           tokenSignedResponseAlg: ${KEYCLOAK_SIGNED_RESPONSE_ALG}
           additionalScopes: ${KEYCLOAK_SCOPE}
           signIn:
             resolvers:
               - resolver: oidcSubClaimMatchingKeycloakUserId
               - resolver: preferredUsernameMatchingUserEntityName
               - resolver: emailMatchingUserEntityProfileEmail
               - resolver: emailLocalPartMatchingUserEntityName
                 dangerouslyAllowSignInWithoutUserInCatalog: true
           sessionDuration: { hours: 24 }
     backstageTokenExpiration: { minutes: _<user_defined_value>_ }
   signInPage: oidc

   callbackUrl

   RHBK callback URL.

   tokenEndpointAuthMethod

   Enter your token endpoint authentication method.

   tokenSignedResponseAlg

   Token signed response algorithm.

   additionalScopes

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

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

   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.

   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.

   backstageTokenExpiration

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

   Warning

   If multiple valid refresh tokens are issued due to frequent refresh token requests, older tokens will remain valid until they expire. Enhance security and prevent potential misuse of older tokens by enabling 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. Allow Developer Hub to authenticate with GitHub, by creating a GitHub App.

   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", 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 catalog provider plugin in your dynamic-plugins.yaml file. This plugin imports GitHub users and groups to the Developer Hub software catalog.

   plugins:
     - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org'
       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.

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

   Warning

   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.