Chapter 3. Enabling the OpenID Connect authentication provider

Procedure

1. In Keycloak, create a new realm, for example RHDH.

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

3. Click Create.
4. Navigate to the Credentials tab.
5. Click Set password.
6. Enter the Password for the user account and toggle Temporary to Off.

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

8. Navigate to the Credentials tab and copy the Client secret.
9. Save the Client ID and the Client Secret for the next step.

10. In Developer Hub, add your Keycloak credentials in your Developer Hub secrets.

    1. Edit your Developer Hub secrets, such as secrets-rhdh.

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

11. Set up the OIDC authentication provider in your Developer Hub custom configuration.

    1. Edit your custom Developer Hub ConfigMap, such as app-config-rhdh.

    2. 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: ${AUTH_KEYCLOAK_CLIENT_ID}
             clientSecret: ${AUTH_KEYCLOAK_CLIENT_SECRET}
             metadataUrl: ${KEYCLOAK_BASE_URL}/auth/realms/${KEYCLOAK_REALM}
             prompt: ${KEYCLOAK_PROMPT} # recommended to use auto
              Uncomment for additional configuration options #callbackUrl: ${KEYCLOAK_CALLBACK_URL} #tokenEndpointAuthMethod: ${KEYCLOAK_TOKEN_ENDPOINT_METHOD} #tokenSignedResponseAlg: ${KEYCLOAK_SIGNED_RESPONSE_ALG} #scope: ${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

1. Restart your backstage-developer-hub application to apply the changes.
2. Your Developer Hub sign-in page displays Sign in using OIDC.

Procedure

1. 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.
2. Replace the oauth2Proxy configuration values in the auth section of your app-config.yaml file with the oidc configuration values.

3. 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: ${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: ${SESSION_SECRET}
     providers:
       oidc:
         production:
           metadataUrl: ${KEYCLOAK_METADATA_URL}
           clientId: ${KEYCLOAK_CLIENT_ID}
           clientSecret: ${KEYCLOAK_CLIENT_SECRET}
           prompt: ${KEYCLOAK_PROMPT} # recommended to use auto
   signInPage: oidc

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

5. Upgrade the Developer Hub Helm chart.