proc-enabling-user-authentication-with-rhbk.adoc

Enabling user authentication with {rhbk-brand-name} ({rhbk})

To authenticate users with {rhbk-brand-name} ({rhbk}), enable and configure the OpenID Connect (OIDC) authentication provider in {product} and provision the users and groups from {rhbk} to the {product-short} software catalog.

Prerequisites

• You added a custom {product-short} application configuration, and have sufficient permissions to modify it.

• You have sufficient permissions in {rhsso} to create and manage a realm. Alternatively, you can ask your {rhbk} administrator to prepare the required {rhbk} App.

Procedure

1. To allow {product-short} 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 {product-short} in {rhbk}, in the created realm, secure the first application, with:

      1. Client ID: A distinctive client ID, such as <{product-very-short}>.

      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 {product-short}, add the following key/value pairs to your {product-short} secrets. You can use these secrets in the {product-short} configuration files by using their respective environment variable name.

   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. 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 {product-short} 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 {product-short} software catalog, add the catalog.providers.keycloakOrg section to your custom {product-short} {my-app-config-file} configuration file:

   {my-app-config-file} fragment with mandatory keycloakOrg fields

   catalog:
     providers:
       keycloakOrg:
         default:
           baseUrl: ${AUTH_OIDC_METADATA_URL}
           clientId: ${AUTH_OIDC_CLIENT_ID}
           clientSecret: ${AUTH_OIDC_CLIENT_SECRET}

   baseUrl

   Your {rhbk} server URL, defined when enabling authentication with {rhbk}.

   clientId

   Your {product-short} application client ID in {rhbk}, defined when enabling authentication with {rhbk}.

   clientSecret

   Your {product-short} 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.

   {my-app-config-file} fragment with optional realm field

   catalog:
     providers:
       keycloakOrg:
         default:
           realm: master

   loginRealm

   Realm used to authenticate. Default value: master.

   {my-app-config-file} fragment with optional loginRealm field

   catalog:
     providers:
       keycloakOrg:
         default:
           loginRealm: master

   userQuerySize

   User number to query simultaneously. Default value: 100.

   {my-app-config-file} fragment with optional userQuerySize field

   catalog:
     providers:
       keycloakOrg:
         default:
           userQuerySize: 100

   groupQuerySize

   Group number to query simultaneously. Default value: 100.

   {my-app-config-file} 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.

   {my-app-config-file} 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.

   {my-app-config-file} 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.

   {my-app-config-file} fragment with optional schedule.initialDelay field

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

5. To set up the {rhbk} authentication provider in your {product-short} custom configuration, edit your custom {product-short} ConfigMap such as app-config-rhdh, and add the following lines to the {my-app-config-file} content:

   1. Configure mandatory fields:

      {my-app-config-file} 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}
              prompt: auto
      signInPage: oidc

      environment: production

      Mark the environment as production to hide the Guest login in the {product-short} 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.

callbackUrl

{rhbk} callback URL.

{my-app-config-file} fragment with optional callbackURL field

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

tokenEndpointAuthMethod

Token endpoint authentication method.

{my-app-config-file} fragment with optional tokenEndpointAuthMethod field

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

tokenSignedResponseAlg

Token signed response algorithm.

{my-app-config-file} fragment with optional tokenSignedResponseAlg field

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

scope

{rhbk} scope.

{my-app-config-file} fragment with optional scope field

auth:
  providers:
    oidc:
      production:
        scope: ${AUTH_OIDC_SCOPE}

signIn

resolvers

After successful authentication, the user signing in must be resolved to an existing user in the {product-short} 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.

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

{my-app-config-file} fragment with optional resolvers list

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 {product-short} software catalog.

Warning

Use this option to explore {product-short} 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:
    oidc:
      production:
        metadataUrl: ${AUTH_OIDC_METADATA_URL}
        clientId: ${AUTH_OIDC_CLIENT_ID}
        clientSecret: ${AUTH_OIDC_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.

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

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

auth

backstageTokenExpiration

To modify the {product-short} 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.

{my-app-config-file} fragment with optional auth.backstageTokenExpiration field

auth:
  backstageTokenExpiration: { minutes: <user_defined_value> }

Warning

Security consideration 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. From the Configure section of the navigation menu, click Realm Settings. From the Realm Settings page, click the Tokens tab. 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:

   {"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 {product-short} login page.

   2. Your {product-short} 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.