Enable authentication with RHBK

Configure Red Hat Build of Keycloak (RHBK) as your Red Hat Developer Hub sign-in provider by enabling the corresponding authentication provider.

Before you begin

Procedure

  1. Enable the Keycloak authentication provider plugin in your dynamic-plugins.yaml file:
    plugins:
      - package: oci://quay.io/rhdh/backstage-community-plugin-auth-backend-module-keycloak-provider:{{inherit}}
        enabled: true
  2. The OIDC provider authentication backend plugin requires Developer Hub to support sessions. Enable session support by adding the session secret to your app-config.yaml file:
    auth:
      session:
        secret: ${SESSION_SECRET}
  3. Add a Keycloak provider section to your app-config.yaml file:
    auth:
      environment: production
      providers:
        keycloak:
          production:
            baseUrl: ${KEYCLOAK_BASE_URL}
            realm: ${KEYCLOAK_REALM}
            clientId: ${KEYCLOAK_CLIENT_ID}
            clientSecret: ${KEYCLOAK_CLIENT_SECRET}
            prompt: auto
    signInPage: keycloak
    environment: production
    Mark the environment as production to hide the Guest login in the Developer Hub home page.
    baseUrl, realm, clientId, clientSecret
    Configure the Keycloak 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 RHBK session exists.

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

    signInPage
    Enter keycloak to enable the OIDC provider as default sign-in provider.
  4. Optional: Add optional fields to the Keycloak authentication provider section in your app-config.yaml file:
    auth:
      providers:
        keycloak:
          production:
            baseUrl: ${KEYCLOAK_BASE_URL}
            realm: ${KEYCLOAK_REALM}
            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: ldapUuidMatchingAnnotation
            sessionDuration: { hours: 24 }
      backstageTokenExpiration: { minutes: _<user_defined_value>_ }
    signInPage: keycloak
    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:

    ldapUuidMatchingAnnotation
    Matches the user with the immutable sub parameter from OIDC to the RHBK user ID. Consider using this resolver for enhanced security.
    oidcLdapUuidMatchingAnnotation

    Matches the user by their immutable LDAP UUID. Requires a custom client scope in Red Hat Build of Keycloak.

    For setup instructions, see Match users by LDAP UUID with Red Hat Build of Keycloak.

    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

    In production mode, do not enable the dangerouslyAllowSignInWithoutUserInCatalog option.

    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.
  5. Optional: Enable Monitor system logs and application metrics to ensure platform availability.
  6. To disable the guest login option, in the app-config.yaml file, set the authentication environment to production:
    auth:
      environment: production

Results

  1. Go to the Developer Hub login page.
  2. Your Developer Hub sign-in page displays Sign in using Keycloak and the Guest user sign-in is disabled.
  3. Log in with Keycloak by using the saved Username and Password values.