Chapter 12. Configuring OIDC for Red Hat Quay

Configuring OpenID Connect (OIDC) for Red Hat Quay can provide several benefits to your Red Hat Quay 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 Red Hat Single Sign-On and Azure AD. Collectively, these procedures include configuring OIDC on the Red Hat Quay Operator, and on standalone deployments by using the Red Hat Quay config tool.

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.

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

12.1.1. Configuring the Red Hat Single Sign-On Operator for 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 configured Red Hat Single Sign-On for the Red Hat Quay Operator. For more information, see Red Hat Single Sign-On Operator.
  • You have configured TLS/SSL for your Red Hat Quay 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.
  • You are logged into your OpenShift Container Platform cluster.
  • You have installed the OpenShift CLI (oc).

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 will use to configure Red Hat Quay.
  3. 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.

  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:

  8. Click Save and navigate to the new Credentials setting.
  9. Copy the value of the Secret.

12.1.2. 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 configured the Red Hat Single Sign-On Operator for the Red Hat Quay Operator.

Procedure

  1. Enter the Red Hat Quay config editor tool by navigating to Operators → Installed Operators. Click Red Hat Quay → Quay Registry. Then, click the name of your Red Hat Quay registry, and the URL listed with Config Editor Endpoint.

  2. Upload a custom SSL/TLS certificate to your OpenShift Container Platform deployment.

    1. Navigate to the Red Hat Quay config tool UI.
    2. Under Custom SSL Certificates, click Select file and upload your custom SSL/TLS certificates.
    3. Reconfigure your Red Hat Quay deployment.
  3. Scroll down to the External Authorization (OAuth) section.
  4. Click Add OIDC Provider.
  5. When prompted, enter redhatsso.

  6. Enter the following information:

    • OIDC Server: 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>/.
    • Client ID: The client ID of the application that is being reistered with the identity provider, for example, quay-enterprise.
    • Client Secret: The Secret from the Credentials tab of the quay-enterprise OIDC client settings.
    • Service Name: The name that is displayed on the Red Hat Quay login page, for example, Red hat Single Sign On.
    • Verified Email Address Claim: The name of the claim that is used to verify the email address of the user.
    • Login Scopes: The scopes to send to the OIDC provider when performing the login flow, for example, openid. After configuration, you must click Add.
  7. Scroll down and click Validate Configuration Changes. Then, click Restart Now to deploy the Red Hat Quay Operator with OIDC enabled.

12.2. Configuring Azure AD OIDC for Red Hat Quay

By integrating Azure AD authentication with Red Hat Quay, your organization can take advantage of the centralized user management and security features offered by Azure AD. Some features include the ability to manage user access to Red Hat Quay repositories based on their Azure AD roles and permissions, and the ability to enable multi-factor authentication and other security features provided by Azure AD.

Azure Active Directory (Azure AD) authentication for Red Hat Quay allows users to authenticate and access Red Hat Quay using their Azure AD credentials.

12.2.1. Configuring Azure AD by using the Red Hat Quay config tool

The following procedure configures Azure AD for Red Hat Quay using the config tool.

Procedure

  1. Enter the Red Hat Quay config editor tool.

    1. If you are running a standalone Red Hat Quay deployment, you can enter the following command: 

      $ sudo podman run --rm -it --name quay_config -p 80:8080 -p 443:8443 registry.redhat.io/quay/quay-rhel8:v3.8.15 config secret

      Use your browser to navigate to the user interface for the configuration tool and log in.

    2. If you are on the Red Hat Quay Operator, navigate to Operators → Installed Operators. Click Red Hat Quay → Quay Registry. Then, click the name of your Red Hat Quay registry, and the URL listed with Config Editor Endpoint.
  2. Scroll down to the External Authorization (OAuth) section.
  3. Click Add OIDC Provider.

  4. When prompted, enter the ID for the ODIC provider.

    Note

    Your OIDC server must end with /.

  5. After the ODIC provider has been added, Red Hat Quay lists three callback URLs that must be registered on Azure. These addresses allow Azure to direct back to Red Hat Quay after authentication is confirmed. For example:

    • 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
  6. After all required fields have been set, validate your settings by clicking Validate Configuration Changes. If any errors are reported, continue editing your configuration until the settings are valid and Red Hat Quay can connect to your database and Redis servers.

12.2.2. Configuring Azure AD by updating the Red Hat Quay config.yaml file

Use the following procedure to configure Azure AD 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.

  1. Add the following information to your Red Hat Quay config.yaml file: 

    AZURE_LOGIN_CONFIG: 1
    CLIENT_ID: <client_id> 2
    CLIENT_SECRET: <client_secret> 3
    OIDC_SERVER: <oidc_server_address_> 4
    SERVICE_NAME: Azure AD 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 respecitve 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 reistered 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.

  2. Proper configuration of Azure AD 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
  3. Restart your Red Hat Quay deployment.