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
- You have shared a secret with RHBK.
- You have provisioned users and groups to the software catalog.
Procedure
-
Enable the Keycloak authentication provider plugin in your
dynamic-plugins.yamlfile:plugins: - package: oci://quay.io/rhdh/backstage-community-plugin-auth-backend-module-keycloak-provider:{{inherit}} enabled: true -
The OIDC provider authentication backend plugin requires Developer Hub to support sessions. Enable session support by adding the session secret to your
app-config.yamlfile:auth: session: secret: ${SESSION_SECRET} -
Add a Keycloak provider section to your
app-config.yamlfile: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
productionto hide the Guest login in the Developer Hub home page. baseUrl,realm,clientId,clientSecret- Configure the Keycloak provider with your secrets.
-
prompt -
Enter
autoto 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
keycloakto enable the OIDC provider as default sign-in provider.
-
-
Optional: Add optional fields to the Keycloak authentication provider section in your
app-config.yamlfile: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
subparameter 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
dangerouslyAllowSignInWithoutUserInCatalogoption.
-
-
-
sessionDuration - Lifespan of the user session. Enter a duration in
mslibrary 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.
- 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.
-
- Optional: Enable Monitor system logs and application metrics to ensure platform availability.
-
To disable the guest login option, in the
app-config.yamlfile, set the authentication environment toproduction:auth: environment: production
Results
- Go to the Developer Hub login page.
- Your Developer Hub sign-in page displays Sign in using Keycloak and the Guest user sign-in is disabled.
- Log in with Keycloak by using the saved Username and Password values.