Chapter 9. Configuring OIDC for Red Hat Quay

Procedure

1. Navigate to the Red Hat Single Sign-On Admin Console.

   1. On the OpenShift Container Platform Web Console, navigate to Network Route.
   2. Select the Red Hat Single Sign-On project from the drop-down list.
   3. Find the Red Hat Single Sign-On Admin Console in the Routes table.
2. Select the Realm that you use to configure Red Hat Quay.
3. Click Clients under the Configure section of the navigation panel, and then click Create to add a new OIDC client for Red Hat Quay.

4. Enter the following information:

   • Client ID: quay-enterprise
   • Client Protocol: openid-connect
   • Root URL: https://<quay_endpoint>/
5. Click Save. This results in a redirect to the Clients setting panel.
6. Navigate to Access Type and select Confidential.

7. Navigate to Valid Redirect URIs. You must provide three redirect URIs. The value should be the fully qualified domain name of the Red Hat Quay registry appended with /oauth2/redhatsso/callback. For example:

   • https://<quay_endpoint>/oauth2/redhatsso/callback
   • https://<quay_endpoint>/oauth2/redhatsso/callback/attach
   • https://<quay_endpoint>/oauth2/redhatsso/callback/cli
8. Click Save and navigate to the new Credentials setting.
9. Copy the value of the Secret.

Procedure

1. Edit your Red Hat Quay config.yaml file by navigating to Operators Installed Operators Red Hat Quay Quay Registry Config Bundle Secret. Then, click Actions Edit Secret. Alternatively, you can update the config.yaml file locally.

2. Add the following information to your Red Hat Quay on OpenShift Container Platform config.yaml file:

   # ...
   RHSSO_LOGIN_CONFIG:
     CLIENT_ID: <client_id>
     CLIENT_SECRET: <client_secret>
     OIDC_SERVER: <oidc_server_url>
     SERVICE_NAME: <service_name>
     SERVICE_ICON: <service_icon>
     VERIFIED_EMAIL_CLAIM_NAME: <example_email_address>
     PREFERRED_USERNAME_CLAIM_NAME: <preferred_username>
     LOGIN_SCOPES: [ 'openid', 'roles' ]
     USE_PKCE: true
     PKCE_METHOD: "S256"
   # ...

   where:

   RHSSO_LOGIN_CONFIG

   Specifies the parent key that holds the OIDC configuration settings. In this example, the parent key used is RHSSO_LOGIN_CONFIG. The string can be replaced with any arbitrary string based on your specific needs, for example ABC123. However, the strings GOOGLE and GITHUB are not accepted. These strings are reserved for their respective identity platforms and require a specific config.yaml entry contingent upon which platform you are using.

   CLIENT_ID

   Specifies the client ID of the application that is being registered with the identity provider. For example, quay.

   CLIENT_SECRET

   Specifies the client secret.

   OIDC_SERVER

   Specifies the fully qualified domain name (FQDN) of the Red Hat Single Sign-On instance, appended with /auth/realms/ and the Realm name. You must include the forward slash at the end, for example, https://sso-redhat.example.com/auth/realms/<your_realm_name>/.

   SERVICE_NAME

   Specifies the name that is displayed on the Red Hat Quay login page, for example, Red Hat Single Sign-On.

   SERVICE_ICON

   Specifies the icon on the login screen. For example, /static/img/RedHat.svg.

   VERIFIED_EMAIL_CLAIM_NAME

   Specifies the name of the claim that is used to verify the email address of the user.

   PREFERRED_USERNAME_CLAIM_NAME

   Specifies the name of the claim that is used for the preferred username of the user.

   LOGIN_SCOPES

   Specifies the scopes to send to the OIDC provider when performing the login flow, for example, openid.

   USE_PKCE

   Specifies whether to enable Proof Key for Code Exchange (PKCE). Defaults to false.

   PKCE_METHOD

   Specifies the code challenge method used to generate the code_challenge sent in the initial authorization request. Defaults to S256.

3. Restart your Red Hat Quay on OpenShift Container Platform deployment with Red Hat Single Sign-On enabled.

Procedure

1. Update your config.yaml file with the following information:

   AUTHENTICATION_TYPE: OIDC
   # ...
   OIDC_LOGIN_CONFIG:
     CLIENT_ID:
     CLIENT_SECRET:
     OIDC_SERVER:
     SERVICE_NAME:
     PREFERRED_GROUP_CLAIM_NAME:
     LOGIN_SCOPES: [ 'openid', '<example_scope>' ]
     OIDC_DISABLE_USER_ENDPOINT: false
   # ...
   FEATURE_TEAM_SYNCING: true
   FEATURE_NONSUPERUSER_TEAM_SYNCING_SETUP: true
   FEATURE_UI_V2: true
   # ...

   where:

   CLIENT_ID

   Specifies the registered OIDC client ID for this Red Hat Quay instance. This field is required.

   CLIENT_SECRET

   Specifies the registered OIDC client secret for this Red Hat Quay instance. This field is required.

   OIDC_SERVER

   Specifies the address of the OIDC server that is being used for authentication. This URL should be such that a GET request to <OIDC_SERVER>/.well-known/openid-configuration returns the provider’s configuration information. This field is required.

   SERVICE_NAME

   Specifies the name of the service that is being authenticated. This field is required.

   PREFERRED_GROUP_CLAIM_NAME

   Specifies the key name within the OIDC token payload that holds information about the user’s group memberships. This field allows the authentication system to extract group membership information from the OIDC token so that it can be used with Red Hat Quay. This field is required.

   LOGIN_SCOPES

   Specifies the scopes Red Hat Quay requests during login. Must include 'openid'. Each scope must also be listed in the identity provider’s scopes_supported from /.well-known/openid-configuration. This field is required.

   OIDC_DISABLE_USER_ENDPOINT

   Specifies whether to allow or disable the /userinfo endpoint. If using Azure Entra ID, set this field to true. Defaults to false.

   FEATURE_TEAM_SYNCING

   Specifies whether to allow team membership to be synced from a backing group in the authentication engine. This field is required.

   FEATURE_NONSUPERUSER_TEAM_SYNCING_SETUP

   Optional. If enabled, non-superusers can configure team synchronization.

2. Restart your Red Hat Quay registry.

Procedure

1. Log in to your Red Hat Quay registry by using your OIDC provider.
2. On the Red Hat Quay v2 UI dashboard, click Create Organization.
3. Enter an organization name, for example, test-org.
4. Click the name of the organization.
5. In the navigation pane, click Teams and membership.
6. Click Create new team and enter a name, for example, testteam.

7. On the Create team pop-up:

   1. Optional. Add this team to a repository.
   2. Add a team member, for example, user1, by typing in the user’s account name.
   3. Add a robot account to this team. This page provides the option to create a robot account.
8. Click Next.
9. On the Review and Finish page, review the information that you have provided and click Review and Finish.
10. To enable team synchronization for your Red Hat Quay OIDC deployment, click Enable Directory Sync on the Teams and membership page.

11. You are prompted to enter the group Object ID if your OIDC authenticator is Azure Entra ID, or the group name if using a different provider.

    Warning

    After you enable team syncing, membership of users who are already part of the team is revoked. The OIDC group is the single source of truth. This action is not reversible. Team user membership from within Red Hat Quay is read-only.

12. Click Enable Sync.

13. You are returned to the Teams and membership page. Note that users of this team are removed and are re-added upon logging back in. At this stage, only the robot account is still part of the team.

    A banner at the top of the page confirms that the team is synced:

    This team is synchronized with a group in OIDC and its user membership is therefore read-only.

    By clicking the Directory Synchronization Config accordion, the OIDC group that your deployment syncs with appears.

14. Log out of your Red Hat Quay registry.

Verification

1. Log back in to your Red Hat Quay registry.
2. Click Organizations test-org test-team Teams and memberships. user1 now appears as a team member for this team.
3. Navigate to your OIDC provider’s administration console.
4. Navigate to the Users page of your OIDC provider. The name of this page varies depending on your provider.
5. Click the name of the user associated with Red Hat Quay, for example, user1.
6. Remove the user from the group in the configured identity provider.
7. Remove, or unassign, the access permissions from the user.
8. Log in to your Red Hat Quay registry.
9. Click Organizations test-org test-team Teams and memberships. user1 has been removed from this team.