Chapter 2. Authenticating with Red Hat Build of Keycloak (RHBK)

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://<RHDH_URL>/api/auth/oidc/handler/frame.
      3. Navigate to the Credentials tab and copy the Client secret.

      4. Save the values for the next step:

         • Client ID
         • Client Secret

   3. Configure your RHBK realm for performance and security:

      1. Navigate to the Configure > Realm Settings.
      2. Set the Access Token Lifespan to a value greater than five minutes (preferably 10 or 15 minutes) to prevent performance issues from frequent refresh token requests for every API call.
      3. Enable the Revoke Refresh Token option to improve security by enabling the refresh token rotation strategy.
   4. 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 your Developer Hub, add the following key/value pairs to your Developer Hub secrets:

   AUTH_OIDC_CLIENT_ID

   Enter the saved Client ID.

   AUTH_OIDC_CLIENT_SECRET

   Enter the saved Client Secret.

   AUTH_OIDC_METADATA_URL

   Enter the saved RHBK realm base URL.

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

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

   auth:
     environment: production
     providers:
       oidc:
         production:
           metadataUrl: ${AUTH_OIDC_METADATA_URL}
           clientId: ${AUTH_OIDC_CLIENT_ID}
           clientSecret: ${AUTH_OIDC_CLIENT_SECRET}
   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.

   Optional: Consider adding the following optional fields:

   dangerouslyAllowSignInWithoutUserInCatalog: true

   To enable authentication without requiring to provision users in the Developer Hub software catalog.

   Warning

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

   app-config.yaml fragment with optional field to allow authenticating users absent from the software catalog

   auth:
     environment: production
     providers:
       oidc:
         production:
           metadataUrl: ${AUTH_OIDC_METADATA_URL}
           clientId: ${AUTH_OIDC_CLIENT_ID}
           clientSecret: ${AUTH_OIDC_CLIENT_SECRET}
   signInPage: oidc
   dangerouslyAllowSignInWithoutUserInCatalog: true

Verification

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.

Verification

1. Check the console logs to verify that the synchronization is completed.

   Successful synchronization example:

   {"class":"KeycloakOrgEntityProvider","level":"info","message":"Read 3 Keycloak users and 2 Keycloak groups in 1.5 seconds. Committing...","plugin":"catalog","service":"backstage","taskId":"KeycloakOrgEntityProvider:default:refresh","taskInstanceId":"bf0467ff-8ac4-4702-911c-380270e44dea","timestamp":"2024-09-25 13:58:04"}
   {"class":"KeycloakOrgEntityProvider","level":"info","message":"Committed 3 Keycloak users and 2 Keycloak groups in 0.0 seconds.","plugin":"catalog","service":"backstage","taskId":"KeycloakOrgEntityProvider:default:refresh","taskInstanceId":"bf0467ff-8ac4-4702-911c-380270e44dea","timestamp":"2024-09-25 13:58:04"}

2. Log in with an RHBK account.

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 of how the backend module can be defined:

   plugins/<module-name>/src/module.ts

   import {
     GroupTransformer,
     keycloakTransformerExtensionPoint,
     UserTransformer,
   } from '@janus-idp/backstage-plugin-keycloak-backend';
   
   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

   The module’s pluginId must be set 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))