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://<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. 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 respective environment variable name.

   AUTHENTICATION_OIDC_CLIENT_ID

   Enter the saved Client ID.

   AUTHENTICATION_OIDC_CLIENT_SECRET

   Enter the saved Client Secret.

   AUTHENTICATION_OIDC_METADATA_URL

   Enter the saved RHBK realm base URL.

3. Enable the Keycloak organization plugin (backstage-plugin-catalog-backend-module-keycloak-dynamic). The plugin is named after RHBK upstream project. This plugin ingests RHBK users and groups to the Developer Hub software catalog.

   dynamic-plugins.yaml file fragment

   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:

   app-config.yaml fragment with mandatory keycloakOrg fields

   catalog:
     providers:
       keycloakOrg:
         default:
           baseUrl: ${AUTHENTICATION_OIDC_METADATA_URL}
           clientId: ${AUTHENTICATION_OIDC_CLIENT_ID}
           clientSecret: ${AUTHENTICATION_OIDC_CLIENT_SECRET}

   baseUrl

   Your RHBK server URL, defined when enabling authentication with RHBK.

   clientId

   Your Developer Hub application client ID in RHBK, defined when enabling authentication with RHBK.

   clientSecret

   Your Developer Hub application client secret in RHBK, defined when enabling authentication with RHBK.

   Optional: Consider adding the following optional fields:

   realm

   Realm to synchronize. Default value: master.

   app-config.yaml fragment with optional realm field

   catalog:
     providers:
       keycloakOrg:
         default:
           realm: master

   loginRealm

   Realm used to authenticate. Default value: master.

   app-config.yaml fragment with optional loginRealm field

   catalog:
     providers:
       keycloakOrg:
         default:
           loginRealm: master

   userQuerySize

   User number to query simultaneously. Default value: 100.

   app-config.yaml fragment with optional userQuerySize field

   catalog:
     providers:
       keycloakOrg:
         default:
           userQuerySize: 100

   groupQuerySize

   Group number to query simultaneously. Default value: 100.

   app-config.yaml fragment with optional groupQuerySize field

   catalog:
     providers:
       keycloakOrg:
         default:
           groupQuerySize: 100

   schedule.frequency

   To specify custom schedule frequency. Supports cron, ISO duration, and "human duration" as used in code.

   app-config.yaml fragment with optional schedule.frequency field

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

   schedule.timeout

   To specify custom timeout. Supports ISO duration and "human duration" as used in code.

   app-config.yaml fragment with optional schedule.timeout field

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

   schedule.initialDelay

   To specify custom initial delay. Supports ISO duration and "human duration" as used in code.

   app-config.yaml fragment with optional schedule.initialDelay field

   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:

   1. Configure mandatory fields:

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

      auth:
        environment: production
        providers:
          oidc:
            production:
              metadataUrl: ${AUTHENTICATION_OIDC_METADATA_URL}
              clientId: ${AUTHENTICATION_OIDC_CLIENT_ID}
              clientSecret: ${AUTHENTICATION_OIDC_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.

Verification

1. To verify user and group provisioning, check the console logs.

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

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

   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

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

Prerequisites

1. You have the permission to register an application in Microsoft Azure.

   • You added a custom Developer Hub application configuration, and have sufficient permissions to modify it.

Procedure

1. To allow Developer Hub to authenticate with Microsoft Azure, create an OAuth application in Microsoft Azure.

   1. In the Azure portal go to App registrations, create a New registration with the configuration:

      Name

      The application name in Azure, such as <My Developer Hub>.

   2. On the Home > App registrations > <My Developer Hub> > Manage > Authentication page, Add a platform, with the following configuration:

      Redirect URI

      Enter the backend authentication URI set in Developer Hub: https://<my_developer_hub_url>/api/auth/microsoft/handler/frame

      Front-channel logout URL

      Leave blank.

      Implicit grant and hybrid flows

      Leave all checkboxes cleared.

   3. On the Home > App registrations > <My Developer Hub> > Manage > API permissions page, Add a Permission, then add the following Delegated permission for the Microsoft Graph API:

      • email
      • offline_access
      • openid
      • profile
      • User.Read.All
      • GroupMember.Read.All
      • Optional custom scopes for the Microsoft Graph API that you define both in this section and in the app-config.yaml Developer Hub configuration file.

1. On the Home > App registrations > <My Developer Hub> > Manage > Certificates & Secrets page, in the Client secrets tab, create a New client secret.

2. Save for the next step:

   • Directory (tenant) ID
   • Application (client) ID

   • Application (client) secret

     1. To add your Microsoft Azure credentials to Developer Hub, add the following key/value pairs to your Developer Hub secrets:

        AUTH_AZURE_TENANT_ID

        Enter your saved Directory (tenant) ID.

        AUTH_AZURE_CLIENT_ID

        Enter your saved Application (client) ID.

        AUTH_AZURE_CLIENT_SECRET

        Enter your saved Application (client) secret.

     2. Set up the Microsoft Azure authentication provider in your app-config.yaml file:

        app-config.yaml file fragment

        auth:
          environment: production 1
          providers:
            microsoft:
              production:
                clientId: ${AUTH_AZURE_CLIENT_ID} 2
                clientSecret: ${AUTH_AZURE_CLIENT_SECRET}
                tenantId: ${AUTH_AZURE_TENANT_ID}
        signInPage: microsoft 3

        1

        Mark the environment as production and disable the Guest login option in the Developer Hub login page.

        2

        Apply the Microsoft Azure credentials configured in your Developer Hub secrets.

        3

        Set the Microsoft Azure provider as your Developer Hub sign-in provider.

3. Optional: Consider adding following optional fields:

   domainHint

   Optional for single-tenant applications. You can reduce login friction for users with accounts in multiple tenants by automatically filtering out accounts from other tenants. If you want to use this parameter for a single-tenant application, uncomment and enter the tenant ID. If your application registration is multi-tenant, leave this parameter blank. For more information, see Home Realm Discovery.

   app-config.yaml file fragment with optional domainHint field

   auth:
     environment: production
     providers:
       microsoft:
         production:
           domainHint: ${AUTH_AZURE_TENANT_ID}

   additionalScopes

   Optional for additional scopes. To add scopes for the application registration, uncomment and enter the list of scopes that you want to add. The default and mandatory value lists: 'openid', 'offline_access', 'profile', 'email', 'User.Read'.

   app-config.yaml file fragment with optional additionalScopes field

   auth:
     environment: production
     providers:
       microsoft:
         production:
           additionalScopes:
              - Mail.Send

   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.

   app-config-rhdh.yaml fragment with optional sessionDuration field

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

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

   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.

   resolver

   Enter the sign-in resolver name. Available resolvers:

   • userIdMatchingUserEntityAnnotation
   • emailLocalPartMatchingUserEntityName
   • emailMatchingUserEntityProfileEmail

   dangerouslyAllowSignInWithoutUserInCatalog: true

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

   Warning

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

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

   auth:
     environment: production
     providers:
       microsoft:
         production:
           clientId: ${AUTH_AZURE_CLIENT_ID}
           clientSecret: ${AUTH_AZURE_CLIENT_SECRET}
           tenantId: ${AUTH_AZURE_TENANT_ID}
           signIn:
             resolvers:
               - resolver: usernameMatchingUserEntityName
                 dangerouslyAllowSignInWithoutUserInCatalog: true
   signInPage: microsoft

Procedure

1. Enable the backstage-plugin-catalog-backend-module-msgraph-dynamic plugin.

   dynamic-plugins.yaml file fragment

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

2. To enable Microsoft Azure member discovery, edit app-config.yaml, your custom Developer Hub configuration file::

   app-config.yaml fragment with mandatory microsoftGraphOrg fields

   catalog:
     providers:
       microsoftGraphOrg:
         providerId:
           target: https://graph.microsoft.com/v1.0
           tenantId: ${AUTH_AZURE_TENANT_ID}
           clientId: ${AUTH_AZURE_CLIENT_ID}
           clientSecret: ${AUTH_AZURE_CLIENT_SECRET}
           schedule:
             frequency: { hours: 1 }
             timeout: { minutes: 50 }
             initialDelay: { minutes: 50 }

   target: https://graph.microsoft.com/v1.0

   Defines 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, clientId and clientSecret

   Use the Developer Hub application information you created in Microsoft Azure and configured in OpenShift as secrets.

   schedule

   frequency

   Enter the schedule frequency as cron, ISO duration, or human duration as used in code.

   timeout

   Enter the schedule timeout as ISO duration or human duration as used in code.

   initialDelay

   Enter the schedule initial delay as ISO duration or human duration as used in code.

   Tip

   In a large organization, this plugin can take a long time. Therefore, avoid setting a low frequency or timeout when importing a large number of users and groups for the first time.

Verification

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

   Successful synchronization example:

   backend:start: {"class":"MicrosoftGraphOrgEntityProvider$1","level":"info","message":"Read 1 msgraph users and 1 msgraph groups in 2.2 seconds. Committing...","plugin":"catalog","service":"backstage","taskId":"MicrosoftGraphOrgEntityProvider:default:refresh","taskInstanceId":"88a67ce1-c466-41a4-9760-825e16b946be","timestamp":"2024-06-26 12:23:42"}
   backend:start: {"class":"MicrosoftGraphOrgEntityProvider$1","level":"info","message":"Committed 1 msgraph users and 1 msgraph groups in 0.0 seconds.","plugin":"catalog","service":"backstage","taskId":"MicrosoftGraphOrgEntityProvider:default:refresh","taskInstanceId":"88a67ce1-c466-41a4-9760-825e16b946be","timestamp":"2024-06-26 12:23:42"}

2. Log in with a Microsoft Azure account.