Chapter 3. Enabling the OpenID Connect authentication provider Red Hat Developer Hub uses the OpenID Connect (OIDC) authentication provider to authenticate with third-party services that support the OIDC protocol. 3.1. Overview of using the OIDC authentication provider in Developer Hub You can configure the OIDC authentication provider in Developer Hub by updating your app-config.yaml file under the root auth configuration. For example: auth: environment: production # Providing an auth.session.secret will enable session support in the auth-backend session: secret: USD{SESSION_SECRET} providers: oidc: production: metadataUrl: USD{AUTH_OIDC_METADATA_URL} clientId: USD{AUTH_OIDC_CLIENT_ID} clientSecret: USD{AUTH_OIDC_CLIENT_SECRET} prompt: USD{AUTH_OIDC_PROMPT} # Recommended to use auto ## Uncomment for additional configuration options # callbackUrl: USD{AUTH_OIDC_CALLBACK_URL} # tokenEndpointAuthMethod: USD{AUTH_OIDC_TOKEN_ENDPOINT_METHOD} # tokenSignedResponseAlg: USD{AUTH_OIDC_SIGNED_RESPONSE_ALG} # scope: USD{AUTH_OIDC_SCOPE} ## Declarative resolvers to override the default resolver: `emailLocalPartMatchingUserEntityName` ## The authentication provider tries each sign-in resolver until it succeeds, and fails if none succeed. Uncomment the resolvers that you want to use. # signIn: # resolvers: # - resolver: preferredUsernameMatchingUserEntityName # - resolver: emailMatchingUserEntityProfileEmail # - resolver: emailLocalPartMatchingUserEntityName signInPage: oidc 3.2. Configuring Keycloak with the OIDC authentication provider Red Hat Developer Hub includes an OIDC authentication provider that can authenticate users by using Keycloak. Important The user that you create in Keycloak must also be available in the Developer Hub catalog. Procedure In Keycloak, create a new realm, for example RHDH . Add a new user. Username Username for the user, for example: rhdhuser Email Email address of the user. First name First name of the user. Last name Last name of the user. Email verified Toggle to On . Click Create . Navigate to the Credentials tab. Click Set password . Enter the Password for the user account and toggle Temporary to Off . Create a new Client ID, for example, RHDH . Client authentication Toggle to On . Valid redirect URIs Set to the OIDC handler URL, for example, https://<RHDH_URL>/api/auth/oidc/handler/frame . Navigate to the Credentials tab and copy the Client secret . Save the Client ID and the Client Secret for the step. In Developer Hub, add your Keycloak credentials in your Developer Hub secrets. Edit your Developer Hub secrets, such as secrets-rhdh. Add the following key/value pairs: AUTH_KEYCLOAK_CLIENT_ID Enter the Client ID that you generated in Keycloak, such as RHDH . AUTH_KEYCLOAK_CLIENT_SECRET Enter the Client Secret that you generated in Keycloak. Set up the OIDC authentication provider in your Developer Hub custom configuration. Edit your custom Developer Hub ConfigMap, such as app-config-rhdh . In the app-config-rhdh.yaml content, add the oidc provider configuration under the root auth configuration, and enable the oidc provider for sign-in: app-config-rhdh.yaml fragment auth: environment: production providers: oidc: production: clientId: USD{AUTH_KEYCLOAK_CLIENT_ID} clientSecret: USD{AUTH_KEYCLOAK_CLIENT_SECRET} metadataUrl: USD{KEYCLOAK_BASE_URL}/auth/realms/USD{KEYCLOAK_REALM} prompt: USD{KEYCLOAK_PROMPT} # recommended to use auto Uncomment for additional configuration options #callbackUrl: USD{KEYCLOAK_CALLBACK_URL} #tokenEndpointAuthMethod: USD{KEYCLOAK_TOKEN_ENDPOINT_METHOD} #tokenSignedResponseAlg: USD{KEYCLOAK_SIGNED_RESPONSE_ALG} #scope: USD{KEYCLOAK_SCOPE} If you are using the keycloak-backend plugin, use the preferredUsernameMatchingUserEntityName resolver to avoid a login error. signIn: resolvers: - resolver: preferredUsernameMatchingUserEntityName signInPage: oidc Verification Restart your backstage-developer-hub application to apply the changes. Your Developer Hub sign-in page displays Sign in using OIDC . 3.3. Migrating from OAuth2 Proxy with Keycloak to OIDC in Developer Hub If you are using OAuth2 Proxy as an authentication provider with Keycloak, and you want to migrate to OIDC, you can update your authentication provider configuration to use OIDC. Procedure In Keycloak, update the valid redirect URI to https://<rhdh_url>/api/auth/oidc/handler/frame . Make sure to replace <rhdh_url> with your Developer Hub application URL, such as, my.rhdh.example.com . Replace the oauth2Proxy configuration values in the auth section of your app-config.yaml file with the oidc configuration values. Update the signInPage configuration value from oauth2Proxy to oidc . The following example shows the auth.providers and signInPage configuration for oauth2Proxy prior to migrating the authentication provider to oidc : auth: environment: production session: secret: USD{SESSION_SECRET} providers: oauth2Proxy: {} signInPage: oauth2Proxy The following example shows the auth.providers and signInPage configuration after migrating the authentication provider to oidc : auth: environment: production session: secret: USD{SESSION_SECRET} providers: oidc: production: metadataUrl: USD{KEYCLOAK_METADATA_URL} clientId: USD{KEYCLOAK_CLIENT_ID} clientSecret: USD{KEYCLOAK_CLIENT_SECRET} prompt: USD{KEYCLOAK_PROMPT} # recommended to use auto signInPage: oidc Remove the OAuth2 Proxy sidecar container and update the upstream.service section of your Helm chart's values.yaml file as follows: service.ports.backend : 7007 service.ports.targetPort : backend The following example shows the service configuration for oauth2Proxy prior to migrating the authentication provider to oidc : service: ports: name: http-backend backend: 4180 targetPort: oauth2Proxy The following example shows the service configuration after migrating the authentication provider to oidc : service: ports: name: http-backend backend: 7007 targetPort: backend Upgrade the Developer Hub Helm chart.

Commands:
auth: environment: production # Providing an auth.session.secret will enable session support in the auth-backend session: secret: USD{SESSION_SECRET} providers: oidc: production: metadataUrl: USD{AUTH_OIDC_METADATA_URL} clientId: USD{AUTH_OIDC_CLIENT_ID} clientSecret: USD{AUTH_OIDC_CLIENT_SECRET} prompt: USD{AUTH_OIDC_PROMPT} # Recommended to use auto ## Uncomment for additional configuration options # callbackUrl: USD{AUTH_OIDC_CALLBACK_URL} # tokenEndpointAuthMethod: USD{AUTH_OIDC_TOKEN_ENDPOINT_METHOD} # tokenSignedResponseAlg: USD{AUTH_OIDC_SIGNED_RESPONSE_ALG} # scope: USD{AUTH_OIDC_SCOPE} ## Declarative resolvers to override the default resolver: `emailLocalPartMatchingUserEntityName` ## The authentication provider tries each sign-in resolver until it succeeds, and fails if none succeed. Uncomment the resolvers that you want to use. # signIn: # resolvers: # - resolver: preferredUsernameMatchingUserEntityName # - resolver: emailMatchingUserEntityProfileEmail # - resolver: emailLocalPartMatchingUserEntityName signInPage: oidc
auth: environment: production providers: oidc: production: clientId: USD{AUTH_KEYCLOAK_CLIENT_ID} clientSecret: USD{AUTH_KEYCLOAK_CLIENT_SECRET} metadataUrl: USD{KEYCLOAK_BASE_URL}/auth/realms/USD{KEYCLOAK_REALM} prompt: USD{KEYCLOAK_PROMPT} # recommended to use auto Uncomment for additional configuration options #callbackUrl: USD{KEYCLOAK_CALLBACK_URL} #tokenEndpointAuthMethod: USD{KEYCLOAK_TOKEN_ENDPOINT_METHOD} #tokenSignedResponseAlg: USD{KEYCLOAK_SIGNED_RESPONSE_ALG} #scope: USD{KEYCLOAK_SCOPE} If you are using the keycloak-backend plugin, use the preferredUsernameMatchingUserEntityName resolver to avoid a login error. signIn: resolvers: - resolver: preferredUsernameMatchingUserEntityName signInPage: oidc
auth: environment: production session: secret: USD{SESSION_SECRET} providers: oauth2Proxy: {} signInPage: oauth2Proxy
auth: environment: production session: secret: USD{SESSION_SECRET} providers: oidc: production: metadataUrl: USD{KEYCLOAK_METADATA_URL} clientId: USD{KEYCLOAK_CLIENT_ID} clientSecret: USD{KEYCLOAK_CLIENT_SECRET} prompt: USD{KEYCLOAK_PROMPT} # recommended to use auto signInPage: oidc
service: ports: name: http-backend backend: 4180 targetPort: oauth2Proxy
service: ports: name: http-backend backend: 7007 targetPort: backend