Chapter 11. Configuring OIDC for Red Hat Quay
Chapter 11. Configuring OIDC for Red Hat Quay Configuring OpenID Connect (OIDC) for Red Hat Quay can provide several benefits to your deployment. For example, OIDC allows users to authenticate to Red Hat Quay using their existing credentials from an OIDC provider, such as Red Hat Single Sign-On , Google, Github, Microsoft, or others. Other benefits of OIDC include centralized user management, enhanced security, and single sign-on (SSO). Overall, OIDC configuration can simplify user authentication and management, enhance security, and provide a seamless user experience for Red Hat Quay users. The following procedures show you how to configure Microsoft Entra ID on a standalone deployment of Red Hat Quay, and how to configure Red Hat Single Sign-On on an Operator-based deployment of Red Hat Quay. These procedures are interchangeable depending on your deployment type. Note By following these procedures, you will be able to add any OIDC provider to Red Hat Quay, regardless of which identity provider you choose to use. 11.1. Configuring Microsoft Entra ID OIDC on a standalone deployment of Red Hat Quay By integrating Microsoft Entra ID authentication with Red Hat Quay, your organization can take advantage of the centralized user management and security features offered by Microsoft Entra ID. Some features include the ability to manage user access to Red Hat Quay repositories based on their Microsoft Entra ID roles and permissions, and the ability to enable multi-factor authentication and other security features provided by Microsoft Entra ID. Azure Active Directory (Microsoft Entra ID) authentication for Red Hat Quay allows users to authenticate and access Red Hat Quay using their Microsoft Entra ID credentials. Use the following procedure to configure Microsoft Entra ID by updating the Red Hat Quay config.yaml file directly. Procedure Using the following procedure, you can add any ODIC provider to Red Hat Quay, regardless of which identity provider is being added. If your system has a firewall in use, or proxy enabled, you must whitelist all Azure API endpoints for each Oauth application that is created. Otherwise, the following error is returned: x509: certificate signed by unknown authority . Use the following reference and update your config.yaml file with your desired OIDC provider's credentials: AUTHENTICATION_TYPE: OIDC # ... AZURE_LOGIN_CONFIG: 1 CLIENT_ID: <client_id> 2 CLIENT_SECRET: <client_secret> 3 OIDC_SERVER: <oidc_server_address_> 4 SERVICE_NAME: Microsoft Entra ID 5 VERIFIED_EMAIL_CLAIM_NAME: <verified_email> 6 # ... 1 The parent key that holds the OIDC configuration settings. In this example, the parent key used is AZURE_LOGIN_CONFIG , however, the string AZURE can be replaced with any arbitrary string based on your specific needs, for example ABC123 .However, the following strings are not accepted: GOOGLE , GITHUB . These strings are reserved for their respective identity platforms and require a specific config.yaml entry contingent upon when platform you are using. 2 The client ID of the application that is being registered with the identity provider. 3 The client secret of the application that is being registered with the identity provider. 4 The address of the OIDC server that is being used for authentication. In this example, you must use sts.windows.net as the issuer identifier. Using https://login.microsoftonline.com results in the following error: Could not create provider for AzureAD. Error: oidc: issuer did not match the issuer returned by provider, expected "https://login.microsoftonline.com/73f2e714-xxxx-xxxx-xxxx-dffe1df8a5d5" got "https://sts.windows.net/73f2e714-xxxx-xxxx-xxxx-dffe1df8a5d5/" . 5 The name of the service that is being authenticated. 6 The name of the claim that is used to verify the email address of the user. Proper configuration of Microsoft Entra ID results three redirects with the following format: https://QUAY_HOSTNAME/oauth2/<name_of_service>/callback https://QUAY_HOSTNAME/oauth2/<name_of_service>/callback/attach https://QUAY_HOSTNAME/oauth2/<name_of_service>/callback/cli Restart your Red Hat Quay deployment. 11.2. Configuring Red Hat Single Sign-On for Red Hat Quay Based on the Keycloak project, Red Hat Single Sign-On (RH-SSO) is an open source identity and access management (IAM) solution provided by Red Hat. RH-SSO allows organizations to manage user identities, secure applications, and enforce access control policies across their systems and applications. It also provides a unified authentication and authorization framework, which allows users to log in one time and gain access to multiple applications and resources without needing to re-authenticate. For more information, see Red Hat Single Sign-On . By configuring Red Hat Single Sign-On on Red Hat Quay, you can create a seamless authentication integration between Red Hat Quay and other application platforms like OpenShift Container Platform. 11.2.1. Configuring the Red Hat Single Sign-On Operator for use with the Red Hat Quay Operator Use the following procedure to configure Red Hat Single Sign-On for the Red Hat Quay Operator on OpenShift Container Platform. Prerequisites You have set up the Red Hat Single Sign-On Operator. For more information, see Red Hat Single Sign-On Operator . You have configured SSL/TLS for your Red Hat Quay on OpenShift Container Platform deployment and for Red Hat Single Sign-On. You have generated a single Certificate Authority (CA) and uploaded it to your Red Hat Single Sign-On Operator and to your Red Hat Quay configuration. Procedure Navigate to the Red Hat Single Sign-On Admin Console . On the OpenShift Container Platform Web Console , navigate to Network Route . Select the Red Hat Single Sign-On project from the drop-down list. Find the Red Hat Single Sign-On Admin Console in the Routes table. Select the Realm that you will use to configure Red Hat Quay. Click Clients under the Configure section of the navigation panel, and then click the Create button to add a new OIDC for Red Hat Quay. Enter the following information. Client ID: quay-enterprise Client Protocol: openid-connect Root URL: https://<quay_endpoint>/ Click Save . This results in a redirect to the Clients setting panel. Navigate to Access Type and select Confidential . 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 Click Save and navigate to the new Credentials setting. Copy the value of the Secret. 11.2.1.1. Configuring the Red Hat Quay Operator to use Red Hat Single Sign-On Use the following procedure to configure Red Hat Single Sign-On with the Red Hat Quay Operator. Prerequisites You have set up the Red Hat Single Sign-On Operator. For more information, see Red Hat Single Sign-On Operator . You have configured SSL/TLS for your Red Hat Quay on OpenShift Container Platform deployment and for Red Hat Single Sign-On. You have generated a single Certificate Authority (CA) and uploaded it to your Red Hat Single Sign-On Operator and to your Red Hat Quay configuration. Procedure 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. Add the following information to your Red Hat Quay on OpenShift Container Platform config.yaml file: # ... RHSSO_LOGIN_CONFIG: 1 CLIENT_ID: <client_id> 2 CLIENT_SECRET: <client_secret> 3 OIDC_SERVER: <oidc_server_url> 4 SERVICE_NAME: <service_name> 5 SERVICE_ICON: <service_icon> 6 VERIFIED_EMAIL_CLAIM_NAME: <example_email_address> 7 PREFERRED_USERNAME_CLAIM_NAME: <preferred_username> 8 LOGIN_SCOPES: 9 - 'openid' # ... 1 The parent key that holds the OIDC configuration settings. In this example, the parent key used is AZURE_LOGIN_CONFIG , however, the string AZURE can be replaced with any arbitrary string based on your specific needs, for example ABC123 .However, the following strings are not accepted: GOOGLE , GITHUB . These strings are reserved for their respective identity platforms and require a specific config.yaml entry contingent upon when platform you are using. 2 The client ID of the application that is being registered with the identity provider, for example, quay-enterprise . 3 The Client Secret from the Credentials tab of the quay-enterprise OIDC client settings. 4 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/<keycloak_realm_name>/ . 5 The name that is displayed on the Red Hat Quay login page, for example, Red hat Single Sign On . 6 Changes the icon on the login screen. For example, /static/img/RedHat.svg . 7 The name of the claim that is used to verify the email address of the user. 8 The name of the claim that is used to verify the email address of the user. 9 The scopes to send to the OIDC provider when performing the login flow, for example, openid . Restart your Red Hat Quay on OpenShift Container Platform deployment with Red Hat Single Sign-On enabled. 11.3. Team synchronization for Red Hat Quay OIDC deployments Administrators can leverage an OpenID Connect (OIDC) identity provider that supports group or team synchronization to apply repository permissions to sets of users in Red Hat Quay. This allows administrators to avoid having to manually create and sync group definitions between Red Hat Quay and the OIDC group. 11.3.1. Enabling synchronization for Red Hat Quay OIDC deployments Use the following procedure to enable team synchronization when your Red Hat Quay deployment uses an OIDC authenticator. Important The following procedure does not use a specific OIDC provider. Instead, it provides a general outline of how best to approach team synchronization between an OIDC provider and Red Hat Quay. Any OIDC provider can be used to enable team synchronization, however, setup might vary depending on your provider. Procedure Update your config.yaml file with the following information: AUTHENTICATION_TYPE: OIDC # ... OIDC_LOGIN_CONFIG: CLIENT_ID: 1 CLIENT_SECRET: 2 OIDC_SERVER: 3 SERVICE_NAME: 4 PREFERRED_GROUP_CLAIM_NAME: 5 LOGIN_SCOPES: [ 'openid', '<example_scope>' ] 6 OIDC_DISABLE_USER_ENDPOINT: false 7 # ... FEATURE_TEAM_SYNCING: true 8 FEATURE_NONSUPERUSER_TEAM_SYNCING_SETUP: true 9 FEATURE_UI_V2: true # ... 1 Required. The registered OIDC client ID for this Red Hat Quay instance. 2 Required. The registered OIDC client secret for this Red Hat Quay instance. 3 Required. 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 configuration information is essential for the relying party (RP) to interact securely with the OpenID Connect provider and obtain necessary details for authentication and authorization processes. 4 Required. The name of the service that is being authenticated. 5 Required. 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. 6 Required. Adds additional scopes that Red Hat Quay uses to communicate with the OIDC provider. Must include 'openid' . Additional scopes are optional. 7 Whether to allow or disable the /userinfo endpoint. If using Azure Entra ID, set this field to true . Defaults to false . 8 Required. Whether to allow for team membership to be synced from a backing group in the authentication engine. 9 Optional. If enabled, non-superusers can setup team synchronization. Restart your Red Hat Quay registry. 11.3.2. Setting up your Red Hat Quay deployment for team synchronization Log in to your Red Hat Quay registry via your OIDC provider. On the Red Hat Quay v2 UI dashboard, click Create Organization . Enter and Organization name, for example, test-org . Click the name of the Organization. In the navigation pane, click Teams and membership . Click Create new team and enter a name, for example, testteam . On the Create team pop-up: Optional. Add this team to a repository. Add a team member, for example, user1 , by typing in the user's account name. Add a robot account to this team. This page provides the option to create a robot account. Click . On the Review and Finish page, review the information that you have provided and click Review and Finish . To enable team synchronization for your Red Hat Quay OIDC deployment, click Enable Directory Sync on the Teams and membership page. 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. Note the message in the popup: Warning Please note that once team syncing is enabled, the membership of users who are already part of the team will be revoked. OIDC group will be the single source of truth. This is a non-reversible action. Team's user membership from within Quay will be ready-only. Click Enable Sync . 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 is synchronized with appears. Log out of your Red Hat Quay registry and continue on to the verification steps. Verification Use the following verification procedure to ensure that user1 appears as a member of the team. Log back in to your Red Hat Quay registry. Click Organizations test-org test-team Teams and memberships . user1 now appears as a team member for this team. Verification Use the following procedure to remove user1 from a group via your OIDC provider, and subsequently remove them from the team on Red Hat Quay. Navigate to your OIDC provider's administration console. Navigate to the Users page of your OIDC provider. The name of this page varies depending on your provider. Click the name of the user associated with Red Hat Quay, for example, user1 . Remove the user from group in the configured identity provider. Remove, or unassign, the access permissions from the user. Log in to your Red Hat Quay registry. Click Organizations test-org test-team Teams and memberships . user1 has been removed from this team.
AUTHENTICATION_TYPE: OIDC AZURE_LOGIN_CONFIG: 1 CLIENT_ID: <client_id> 2 CLIENT_SECRET: <client_secret> 3 OIDC_SERVER: <oidc_server_address_> 4 SERVICE_NAME: Microsoft Entra ID 5 VERIFIED_EMAIL_CLAIM_NAME: <verified_email> 6 RHSSO_LOGIN_CONFIG: 1 CLIENT_ID: <client_id> 2 CLIENT_SECRET: <client_secret> 3 OIDC_SERVER: <oidc_server_url> 4 SERVICE_NAME: <service_name> 5 SERVICE_ICON: <service_icon> 6 VERIFIED_EMAIL_CLAIM_NAME: <example_email_address> 7 PREFERRED_USERNAME_CLAIM_NAME: <preferred_username> 8 LOGIN_SCOPES: 9 - 'openid' AUTHENTICATION_TYPE: OIDC OIDC_LOGIN_CONFIG: CLIENT_ID: 1 CLIENT_SECRET: 2 OIDC_SERVER: 3 SERVICE_NAME: 4 PREFERRED_GROUP_CLAIM_NAME: 5 LOGIN_SCOPES: [ 'openid', '<example_scope>' ] 6 OIDC_DISABLE_USER_ENDPOINT: false 7 FEATURE_TEAM_SYNCING: true 8 FEATURE_NONSUPERUSER_TEAM_SYNCING_SETUP: true 9 FEATURE_UI_V2: true This team is synchronized with a group in OIDC and its user membership is therefore read-only.