Quay on TechBlog about OpenShift/Ansible/Satellite and much more

Red Hat Quay Registry - Integrate Keycloak

Fri, 19 Sep 2025 00:00:00 +0000

This guide shows you how to configure Keycloak as an OpenID Connect (OIDC) provider for Red Hat Quay Registry. It covers what to configure in Keycloak, what to put into Quay’s config.yaml (or Operator config), how to verify the login flow, and how to switch your Quay initial/admin account (stored locally in Quay’s DB) to an admin user that authenticates via Keycloak.

Prerequisites

Before starting this integration, ensure you have:

OpenShift cluster with admin access
Red Hat Quay Registry 3.15+ installed (via Operator)
Red Hat build of Keycloak stable-v22+ installed and configured (via Operator)
Valid SSL certificates for both Quay and Keycloak
Admin access to both Keycloak Admin Console and Quay configuration
Basic understanding of OIDC/OAuth2 concepts

Here we are using the Quay Operator and the Keycloak Operator on OpenShift.

Quick overview (what happens)

Create a Keycloak client for Quay (OIDC).
Configure Quay’s OIDC provider section in config.yaml to point to Keycloak (client id/secret, endpoints, scopes, claim names).
Restart Quay, test login via Keycloak. The first time an OIDC user logs in, Quay creates a local user record that is linked to the OIDC identity.
Promote that Quay user to superuser by adding their Quay username to SUPER_USERS (or use the UI/API).

Keycloak: create a client for Quay

Steps in Keycloak Admin console:

Log in to the Keycloak Admin Console and select the realm you will use for Quay or create a new realm.
Select that realm and go to clients
Press Create client to create and configure a new client for Quay. Not much must be configured here, but at least the following:
1. Client type: OpenID Connect
2. Client ID: quay-enterprise (The ID we will use in the Quay configuration as well)
3. Client authentication: ON
4. Valid redirects URIs:

The service-id is the parent key you’ll use in Quay config — e.g. keycloak.

Save the client.
1. Go to Credentials and create or copy the client secret you will use in Quay.

(Optional) If you intend to use groups/roles from Keycloak for Quay team synchronization, ensure your Keycloak users or groups are populated and that Keycloak includes group membership in tokens or exposes group claims (you may need to add a protocol mapper in the client to include groups or roles in the ID token or userinfo response). Refer to Keycloak docs for adding protocol mappers.

Keycloak: create users and groups

Go to Users and create a new user or use an existing one.
If you created a new user, set a password for them in the Credentials tab.
Go to Groups and create a new group or use an existing one.
You can assign users to that group.

Quay: add OIDC configuration

Quay’s OIDC block is a nested object under AUTHENTICATION_TYPE: OIDC. The parent key can be any name (e.g., KEYCLOAK_LOGIN_CONFIG) — Quay uses the parent key name to form the callback paths.

The parent key name (before _LOGIN_CONFIG) must match the service-id used in Keycloak redirect URIs.

Example config.yaml snippet for Keycloak:

Using Quay Operator this configuration is stored as a secret in the namespace where Quay is installed.

AUTHENTICATION_TYPE: OIDC (1)
KEYCLOAK_LOGIN_CONFIG: (2)
CLIENT_ID: quay-enterprise (3)
CLIENT_SECRET: <client-secret> (4)
LOGIN_SCOPES:
- openid
- email
- profile
- groups
OIDC_SERVER: https://<keycloak hostname>/realms/quay/ (5)
SERVICE_NAME: keycloak (6)
PREFERRED_USERNAME_CLAIM_NAME: preferred_username
VERIFIED_EMAIL_CLAIM_NAME: email
PREFERRED_GROUP_CLAIM_NAME: groups
OIDC_DISABLE_USER_ENDPOINT: false (7)

1	Set this parameter to OIDC.
2	parent key name can be any string (use KEYCLOAK_LOGIN_CONFIG here). This is important, and the part in front of _LOGIN_CONFIG must match the service-id you used in Keycloak.
3	The client id you used in Keycloak.
4	The client secret you used in Keycloak.
5	The realm base URL (no trailing /protocol…), e.g.: https://<keycloak_hostname>/realms/quay/ — Quay will discover .well-known/openid-configuration endpoints automatically.
6	The service name you used in Keycloak.
7	Set this parameter to false to allow Quay to fetch user information from Keycloak. If using Azure Entra ID set this to true.

Since we are using Quay Operator, the operator will pick up the changes automatically and restart Quay. If you are using a standalone Quay installation, you need to restart Quay for the change to take effect. (Config is not hot-reloaded.)

Testing Login

Let’s do some tests to verify the configuration. Above we have created some users and groups in Keycloak. Let’s try to log in with one of them.

Open your Quay UI ( https://<quay_hostname>; ) in a browser. On the login page you should see the external login option labelled Keycloak (or the SERVICE_NAME you set).

Click the "Sign in with Keycloak" option. and you will be redirected to Keycloak’s login screen. Here you can authenticate with a Keycloak user.

After successful authentication, Keycloak redirects back to Quay and Quay creates a local user mapped to the OIDC claims (username, email). If you set USERNAME_CLAIM to preferred_username, look at the created Quay username in the UI under your user’s profile.

Make the Keycloak user a Quay admin

In Quay only one identity provider can be used at a time. If you previously set up a local admin account, you need to make a Keycloak user a Quay admin by adding their Quay username to SUPER_USERS where all administrators are listed.

In the Quay configuration, you can define administrators using the SUPER_USERS array.

Make sure the Keycloak user has logged in once so Quay has created a local user record

Edit the Quay configuration once more and add the Quay username (exact username created by Quay).

For example, let’s say we have created a user called "alice" in Keycloak. We need to add this user to the SUPER_USERS array.

SETUP_COMPLETE: true
SUPER_USERS:
- admin # existing local admin (optional)
- alice # alice is the Quay username created from Keycloak login

After restart, the Quay account alice will have superuser privileges (same as if created in the UI).

Working with Podman on CLI

Now, as we changed the authentication method, we need to verify if we can push/pull images from/to the registry. The command line tool of the choice is podman.

However, podman does not redirect to SSO login, so it needs a token to authenticate. We can generate a new token for a user in the Quay UI.

In the Quay UI, go to the Account Settings (upper right corner)
In the settings section, under Docker CLI and other Application Tokens, click on Create Application Token
Enter a name for the token
Select the newly created token and copy the podman login command (or any other command you need)
The command for podman will look like this:

podman login -u='$app' -p='<token>' <quay-url>
Login Succeeded!

Now you can push/pull images from/to the registry.

Troubleshooting

Common issues and their solutions:

Redirect URI Mismatch

Problem: Keycloak returns "Invalid redirect URI" error

Solution: Ensure all three redirect URIs are configured in Keycloak client:

https://<quay-hostname>/oauth2/keycloak/callback
https://<quay-hostname>/oauth2/keycloak/callback/attach
https://<quay-hostname>/oauth2/keycloak/callback/cli

Username Mapping Issues

Problem: Quay creates unexpected usernames

Solution:

Check which claim Keycloak sends: inspect ID token in browser dev tools
Common claims: preferred_username, email, sub, name
Update PREFERRED_USERNAME_CLAIM_NAME in Quay config accordingly

SSL Certificate Issues

Problem: Quay cannot reach Keycloak due to TLS verification errors

Solutions:

Install your internal CA certificate in the Quay container
Use publicly trusted certificates for both services
For testing only: disable SSL verification (not recommended for production)

Authentication Flow Failures

Problem: Login redirects but fails to create user in Quay

Debugging steps:

Check Quay logs: oc logs deployment/quay-app
Verify OIDC discovery endpoint: https://<keycloak>/realms/<realm>/.well-known/openid-configuration
Confirm client secret matches between Keycloak and Quay
Test with curl: curl -k https://<keycloak>/realms/<realm>/.well-known/openid-configuration

Conclusion

Integrating Quay 3.15 with Keycloak via OIDC centralizes authentication, simplifies user management, and allows you to leverage enterprise identity features. The key steps are straightforward: create a Keycloak client with the correct redirect URIs, configure the corresponding OIDC block in Quay’s config.yaml.

By switching the initial database-backed admin to an identity managed in Keycloak, you reduce the risk of "orphaned" local accounts and align Quay administration with your organization’s identity and access management strategy.

Stumbling into Quay: Upgrading from 3.3 to 3.4 with the quay-operator

Sat, 16 Oct 2021 00:00:00 +0000

We had the task of answering various questions related to upgrading Red Hat Quay 3.3 to 3.4 and to 3.5 with the help of the quay-operator.

Thankfully (sic!) everything changed in regards to the Quay operator between Quay 3.3 and Quay 3.4.

So this is a brain dump of the things to consider.

Operator changes

With Quay 3.4 the operator was completely reworked and it basically changed from opinionated to very opinionated. The upgrade works quite well but you have to be aware about the following points:

The name of the custom resource changed from QuayEcosystem to QuayRegistry
The configHostname, used for providing the quay configuration UI, is no longer configurable
The password for the configuration UI is always regenerated after a configuration re-deployment
The volume size of the PostgreSQL PVC will change to 50G

In my test cluster I was using a 10G Ceph block device and the StorageClass did not support volume expansion. So my upgrade stopped at this point and I had to allow volume expansion in the storage class.

A horizontal pod autoscaler is also deploy during the upgrade. The default is to scale automatically to 20 pods, you might reconsider this…
With the Quay operator version 3.5 the operator is monitoring all namespaces for custom resources and needs to be installed in the openshift-operators namespace, this is how we upgraded Quay to 3.5 including the operator:
- change the quay operator channel to 3.5
- trigger an upgrade
- now Quay gets upgraded to version 3.5
- after the Quay upgrade you need to reinstall the operator:
  - deinstall the quay operator, Quay is not affected by this
  - reinstall the Quay operator (3.5) in all-namespaces
  - the re-installation of the operator triggers a quay deployment, all Quay pods are restarted!
You have to manually cleanup old
- postgres-config-secrets and
- quay-config-bundle's

Backup and restore considerations

Red Hat is working on providing documentation on how to backup and restore Quay in various scenarios. There's an open task for this that provides more information https://issues.redhat.com/browse/PROJQUAY-2242.

Red Hat Quay Registry - Overview and Installation

Wed, 13 May 2020 00:00:00 +0000

Red Hat Quay is an enterprise-quality container registry, which is responsible to build, scan, store and deploy containers. The main features of Quay include:

High Availability
Security Scanning (with Clair)
Registry mirroring
Docker v2
Continuous integration

and much more.

Quay can be installed as:

Standalone single service
High Availibility service
On OpenShift with an Operator
On OpenShift without an Operator.

For the following Quay Tutorial Quay version 3.3 on OpenShift 4.3/4.4 with an Operator is used. Moreover, a local storage is used, to make the deployment easier and independent to a storage provider. In any case, be sure that for a production environment a "real" storage is used.

Further details can be found at the official Red Hat documentation at: Deploy Red Hat Quay on OpenShift with an Operator

Quay Architecture

Several components are used to build Quay

Database: used to store metadata (not images)
Redis: stores live builder logs
Quay container registry: Runs Quay as a service

Two types of storages are supported:

Public cloud storage, like Amazon S3, Google Cloud Storage
Private cloud storage, S3 compliant Object Store, Like Ceph RADOS or OpenStack Swift.

Since I perform the example setup in a limited lab environment, I used local storage. This is not supported for production installations.

Installation

This example installation, covers the configuration of all credentials, but it ignores the configuration of a storage engine. Instead it is using local storage.

Create a new project and install the Quay Operator

Note: Before you begin create a new project called "quay".

From the OpenShift console goto Operators > OperationHub and search for "Red Hat Quay Operator". Be sure NOT to select the community version. Install the Operator using the following settings:

Installation Mode: select the namespace "quay"
Leave the other settings as default.

Figure 1. Operator Installation

Once you select "Subscribe", the installation process will take a few minutes. At the end, the operator pods should run inside your namespace and is ready to bse used.

Figure 2. Operator Running

Configure Quay

To configure Quay the Custom Resource Definition "QuayEcosystem" must be defined. Below example shows a ready to use example to test the deployment. Several secrets are used in this QuayEcosystem which must be created first. If they are not specified in the QuayEcosystem, then default values would be used. However, it always makes sense to specify passwords :)

Create a Pull Secret to pull from Quay.io

Check the article Accessing Red Hat Quay to find the appropriate credentials you need to fetch images from quay.io. Find the section "Red Hat Quay v3 on OpenShift", copy the secret into the file redhat_secret.yaml and create the object in OpenShift:

oc create -f redhat_secret.yaml

Create Quay Superuser Credentials

The Quay superuser will be able to manage other users or projects. Create the secret by defining username, password and e-mail address:

The password must have a minimum length of 8 characters.

oc create secret generic quay-credentials \
--from-literal=superuser-username=<username> \
--from-literal=superuser-password=<password> \
--from-literal=superuser-email=<email>

Create Quay Configuration Credentials

The Quay configuration is done, by a separate pod, with a separate accessible route. To set the password, create the following secret:

The password must have a minimum length of 8 characters.

oc create secret generic quay-config-app \
--from-literal=config-app-password=<password>

Specify database credentials

As next let’s create the credentials for the database:

oc create secret generic <secret_name> \
--from-literal=database-username=<username> \
--from-literal=database-password=<password> \
--from-literal=database-root-password=<root-password> \
--from-literal=database-name=<database-name>

It is also possible to use and existing database. To configure this, create the secret as described and add the server parameter, containing the hostname, to the QuayEcosystem definition+

Setting Redis password

By default, the operator would install Redis without any password. To specify a password, create the following secret:

oc create secret generic quay-redis-password \
--from-literal=password=<password>

Create QuayEcosystem Resource

With all the secrets created above, it is time to create the QuayEcosystem. Once it is defined, the operator will automatically start all required services.

The following is an example, using the different secret names (The names should be self explaining) In addition, the following has been defined:

volumeSize = 10GI for the database
keepConfigDeployment to false, this will remove the configuration pod after the deployment.
hostname: to reach the Quay registry under a defined hostname (otherwise a default name would be created)
Clair container scanning is enabled

apiVersion: redhatcop.redhat.io/v1alpha1
kind: QuayEcosystem
metadata:
name: quayecosystem
spec:
quay:
imagePullSecretName: redhat-quay-pull-secret
superuserCredentialsSecretName: quay-credentials
configSecretName: quay-config-app
deploymentStrategy: Recreate
skipSetup: false
keepConfigDeployment: false
externalAccess:
hostname: quay.apps.ocp.ispworld.at
database:
volumeSize: 10Gi
credentialsSecretName: quay-database-credential
registryBackends:
- name: local
local:
storagePath: /opt/quayregistry
redis:
credentialsSecretName: quay-redis-password
imagePullSecretName: redhat-quay-pull-secret
clair:
enabled: true
imagePullSecretName: redhat-quay-pull-secret

Quay WebUI

Once the Quay Operator has deployed all containers, you should see one route (or 2 if you kept Configuration Deployment Container) and can access your Quay installation.

Figure 3. Quay WebUI

Optional: Disable self account creation

Many customers want to disable the "Create Account" link on the login page (see Figure #3), to prevent that anybody could create a new account. To remove this option, the configuration pod must run.

Verify if the Configuration pod is running

If the following does not return anything, then the container is not running:

oc get routes -n quay | grep config

If this is the case, modify the resource QuayEcosystem to enable the Configuration UI.

Edit:

oc edit QuayEcosystem/quayecosystem

and set "KeepConfigDeployment" to true:

 quay:
[...]
keepConfigDeployment: true

After a few minutes another pod, called "quayecosystem-quay-config" will be started and a new route is created:

oc get routes -n quay | grep config
quayecosystem-quay-config quayecosystem-quay-config-quay.apps.ocp.ispworld.at quayecosystem-quay-config 8443 passthrough/Redirect None

Configure Account Creation and Anonymous Access

Login to the Configuration Web Interface with the credentials you specified during the deployment and scroll down to the section "Access Settings".

Figure 4. Quay Configuration

There remove the checkbox from:

Anonymous Access
User Creation

and save and build the configuration.

This will trigger a change on the Quay pod. After it has been recreated (this will take a few minutes), the feature to create a new account is removed from the Login page.

Working with Quay

The following quick steps through Quay are the steps of the Quay tutorial, which can be seen at the Quay WebUI at the "Tutorial" tab.

Login via Docker CLI

To login via docker CLI simply use:

docker login <your selected hostname for quay>

Docker expects a valid certificate. Such certificate could be added to the definition of QuayEcosystem. However, I did not create a certificate for this lab. To allow untrusted certificates, on a Mac, simply download the certificates (For Chrome: you can drag and drop the certificate from the browser to your Desktop, for Firefox, you need to open the Options menu and export the certificates.). After that double click both certificates (the root and the site certificate), which will install them on you local Keychain. Open the Keychain on you Mac, find the appropriate certificates and set both to "Always trust"

Create an example container

The next step to create a new image is to create a container. For this example the busybox base image is used.

docker run busybox echo "fun" > newfile

This will pull the latest image of busybox and create a container:

Unable to find image 'busybox:latest' locally
latest: Pulling from library/busybox
d9cbbca60e5f: Pulling fs layer
d9cbbca60e5f: Verifying Checksum
d9cbbca60e5f: Download complete
d9cbbca60e5f: Pull complete
Digest: sha256:836945da1f3afe2cfff376d379852bbb82e0237cb2925d53a13f53d6e8a8c48c
Status: Downloaded newer image for busybox:latest

With "docker ps" the running container is shown. Remember the Container ID for further steps. In this case fc3e9bb1e9da.

docker ps -l
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
fc3e9bb1e9da busybox "echo fun" 3 minutes ago Exited (0) 3 minutes ago relaxed_proskuriakova

Create the image

Once a container has terminated in Docker, the next step is to commit the container to an image. To do so we will use "docker commit" command. As name for the repository I took superapp.

docker commit fc3e9bb1e9da quay.apps.ocp.ispworld.at/quay/superapp

Push the image to Red Hat Quay

The final step is to push the image to our repository, where it will be stored for future use.

docker push quay.apps.ocp.ispworld.at/quay/superapp

Figure 5. Quay Repository

Test Container Security Scanner

Clair is used to scan containers about possible security risks. It imports vulnerability data permanently from a known source and creates a list of threats for an image.

To test such scanning, we pull the "Universal Base Image RHEL 7" from Red Hat. I am using version 7.6 since this is already quite old and we expect some known vulnerabilities for this image.

First you need to login to Red Hat Registry:

docker login registry.redhat.io
Username: <Username>
Password: <Password>
Login Succeeded

Then let’s pull the UBI Image 7.6 (instead of the latest)

docker pull registry.redhat.io/ubi7/ubi:7.6

Before we can push it to our Quay registry, we need to tag it:

docker tag registry.redhat.io/ubi7/ubi:7.6 quay.apps.ocp.ispworld.at/quay/ubi7:7.6

If we now check the local images, we see that there are two UBI images.

docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
quay.apps.ocp.ispworld.at/quay/ubi7 7.6 247ee58855fd 10 months ago 204MB
registry.redhat.io/ubi7/ubi 7.6 247ee58855fd 10 months ago 204MB

Now it is possible to push the image to the Quay repository.

docker push quay.apps.ocp.ispworld.at/quay/ubi7:7.6

Finally the image is available inside our Registry and Clair will queue it for a security scan.

Once the scan is finished, possible found issues are shown under the "Repository Tags".

Figure 6. Clair Security Scanning

When you click on then, you will see a detailed result page, with all vulnerabilities found:

Figure 7. Clair Security Scanning Result