Chapter 2. Authenticating with Red Hat Single Sign-On (RHSSO)

Procedure

1. To allow Developer Hub to authenticate with RHSSO, complete the steps in RHSSO, to create a realm and a user and register the Developer Hub 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:

      • RHSSO realm base URL, such as: <your_rhsso_URL>/auth/realms/<your_realm>.

   2. To register your Developer Hub in RHSSO, in the created realm, create a Client ID, 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 RHSSO 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 secrets, edit your Developer Hub secrets, such as secrets-rhdh, and add the following key/value pairs:

   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 RHSSO realm base URL.

3. To set up the RHSSO 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-rhdh.yaml content:

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

   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-rhdh.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 RHSSO 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))