SupportConsoleDevelopersStart a trialContact

Chapter 7. Red Hat Quay Robot Account overview

A robot account provides automated, credential-based access to repositories in your registry, similar to OpenShift Container Platform service accounts. You can use robot accounts to grant container clients push and pull permissions without sharing personal credentials.

Setting up a Robot Account results in the following:

  • Credentials are generated for the Robot Account.
  • Repositories and images that the Robot Account can push and pull images from are identified.
  • Generated credentials can be copied and pasted to use with different container clients, such as Docker, Podman, Kubernetes, Mesos, and so on, to access each defined repository.

Each Robot Account is limited to a single user namespace or Organization. For example, the Robot Account could provide access to all repositories for the user quayadmin. However, it cannot provide access to repositories that are not in the user’s list of repositories.

Robot Accounts can be created using the Red Hat Quay UI, or through the CLI using the Red Hat Quay API. After creation, Red Hat Quay administrators can leverage more advanced features with Robot Accounts, such as keyless authentication.

7.1. Creating a robot account by using the UI
Copy link

To automate access to your repositories, you can create a robot account by using the Red Hat Quay v2 UI. Robot accounts generate credentials that container clients can use to push and pull images without a personal login.

Procedure

  1. On the v2 UI, click Organizations.
  2. Click the name of the organization that you create the robot account for, for example, test-org.
  3. Click the Robot accounts tab Create robot account.
  4. In the Provide a name for your robot account box, enter a name, for example, robot1. The name of your Robot Account becomes a combination of your username plus the name of the robot, for example, quayadmin+robot1

  5. Optional. The following options are available if desired:

    1. Add the robot account to a team.
    2. Add the robot account to a repository.
    3. Adjust the robot account’s permissions.

  6. On the Review and finish page, review the information you have provided, then click Review and finish. The following alert appears: Successfully created robot account with robot name: <organization_name> + <robot_name>.

    Alternatively, if you tried to create a robot account with the same name as another robot account, you might receive the following error message: Error creating robot account.

  7. Optional. You can click Expand or Collapse to reveal descriptive information about the robot account.
  8. Optional. You can change permissions of the robot account by clicking the kebab menu Set repository permissions. The following message appears: Successfully updated repository permission.

  9. Optional. You can click the name of your robot account to obtain the following information:

    • Robot Account: Select this obtain the robot account token. You can regenerate the token by clicking Regenerate token now.
    • Kubernetes Secret: Select this to download credentials in the form of a Kubernetes pull secret YAML file.
    • Podman: Select this to copy a full podman login command line that includes the credentials.
    • Docker Configuration: Select this to copy a full docker login command line that includes the credentials.

7.2. Bulk managing robot account repository access
Copy link

To grant a robot account access to several repositories at once, you can set its permissions in bulk by using the Red Hat Quay v2 UI.

Prerequisites

  • You have created a robot account.
  • You have created multiple repositories under a single organization.

Procedure

  1. On the Red Hat Quay v2 UI landing page, click Organizations in the navigation pane.
  2. On the Organizations page, select the name of the organization that has multiple repositories. The number of repositories under a single organization can be found under the Repo Count column.
  3. On your organization’s page, click Robot accounts.
  4. For the robot account that you want to add to multiple repositories, click the kebab icon Set repository permissions.

  5. On the Set repository permissions page, check the boxes of the repositories that you want to add the robot account to. For example:

    Set repository permissions

  6. Set the permissions for the robot account, for example, None, Read, Write, Admin.
  7. Click save. An alert that says Success alert: Successfully updated repository permission appears on the Set repository permissions page, confirming the changes.
  8. Return to the Organizations Robot accounts page. Now, the Repositories column of your robot account shows the number of repositories that the robot account has been added to.

7.3. Disabling robot accounts
Copy link

To prevent users from creating new robot accounts, you can disable robot account creation in your Red Hat Quay configuration file. This setting also blocks robot accounts required for repository mirroring, so review your mirroring setup first.

Important

Robot accounts are mandatory for repository mirroring. Setting the ROBOTS_DISALLOW configuration field to True breaks mirroring configurations. Users mirroring repositories should not set ROBOTS_DISALLOW to True in their config.yaml file. This is a known issue in Red Hat Quay.

Prerequisites

  • You have created multiple robot accounts.

Procedure

  1. Update your config.yaml field to add the ROBOTS_DISALLOW variable, for example: 

    ROBOTS_DISALLOW: true
  2. Restart your Red Hat Quay deployment.

Verification

  1. Navigate to your Red Hat Quay repository.
  2. Click the name of a repository.
  3. In the navigation pane, click Robot Accounts.
  4. Click Create Robot Account.
  5. Enter a name for the robot account, for example, <organization-name/username>+<robot-name>.
  6. Click Create robot account to confirm creation. The following message appears: Cannot create robot account. Robot accounts have been disabled. Please contact your administrator.

  1. On the command-line interface (CLI), attempt to log in as one of the robot accounts by entering the following command: 

    $ podman login -u="<organization-name/username>+<robot-name>" -p="KETJ6VN0WT8YLLNXUJJ4454ZI6TZJ98NV41OE02PC2IQXVXRFQ1EJ36V12345678" <quay-server.example.com>

    The following error message is returned: 

    Error: logging into "<quay-server.example.com>": invalid username/password

  2. You can pass in the log-level=debug flag to confirm that robot accounts have been deactivated: 

    $ podman login -u="<organization-name/username>+<robot-name>" -p="KETJ6VN0WT8YLLNXUJJ4454ZI6TZJ98NV41OE02PC2IQXVXRFQ1EJ36V12345678" --log-level=debug <quay-server.example.com>
     
    ...
DEBU[0000] error logging into "quay-server.example.com": unable to retrieve auth token: invalid username/password: unauthorized: Robot accounts have been disabled. Please contact your administrator.

7.4. Deleting a robot account by using the UI
Copy link

To remove a robot account that you no longer need, you can delete it by using the Red Hat Quay UI.

Procedure

  1. Log into your Red Hat Quay registry:
  2. Click the name of the Organization that has the robot account.
  3. Click Robot accounts.
  4. Check the box of the robot account to be deleted.
  5. Click the kebab menu.
  6. Click Delete.
  7. Type confirm into the textbox, then click Delete.

7.5. Keyless authentication with robot accounts
Copy link

With keyless authentication in Red Hat Quay, you can exchange an OIDC token for a short-lived robot account token that expires after one hour.

In previous versions of Red Hat Quay, robot account tokens were valid for the lifetime of the token unless deleted or regenerated. Tokens that do not expire have security implications for users who do not want to store long-term passwords or manage the deletion or regeneration of authentication tokens.

Keyless authentication reduces the risk of robot token exposure by removing exchanged tokens after one hour.

Configuring keyless authentication with robot accounts is a multi-step procedure that requires setting a robot federation, generating an OAuth2 token from your OIDC provider, and exchanging the OAuth2 token for a robot account access token.

To exchange an external OIDC token for a Red Hat Quay robot account token, you can first generate an OAuth2 token by using Red Hat Single Sign-On.

Procedure

  1. On the Red Hat Single Sign-On UI:

    1. Click Clients and then the name of the application or service that can request authentication of a user.

    2. On the Settings page of your client, ensure that the following options are set or enabled:

      • Client ID
      • Valid redirect URI
      • Client authentication
      • Authorization
      • Standard flow

      • Direct access grants

        Note

        Settings can differ depending on your setup.

    3. On the Credentials page, store the Client Secret for future use.
    4. On the Users page, click Add user and enter a username, for example, service-account-quaydev. Then, click Create.
    5. Click the name of the user, for example service-account-quaydev on the Users page.
    6. Click the Credentials tab Set password and provide a password for the user. If warranted, you can make this password temporary by selecting the Temporary option.

    7. Click the Realm settings tab OpenID Endpoint Configuration. Store the /protocol/openid-connect/token endpoint. For example: 

      http://localhost:8080/realms/master/protocol/openid-connect/token

  2. On a web browser, navigate to the following URL: 

    http://<keycloak_url>/realms/<realm_name>/protocol/openid-connect/auth?response_type=code&client_id=<client_id>
  3. When prompted, log in with the service-account-quaydev user and the temporary password you set. Complete the login by providing the required information and setting a permanent password if necessary.

  4. You are redirected to the URI address provided for your client. For example: 

    https://localhost:3000/cb?session_state=5c9bce22-6b85-4654-b716-e9bbb3e755bc&iss=http%3A%2F%2Flocalhost%3A8080%2Frealms%2Fmaster&code=ea5b76eb-47a5-4e5d-8f71-0892178250db.5c9bce22-6b85-4654-b716-e9bbb3e755bc.cdffafbc-20fb-42b9-b254-866017057f43

    Take note of the code provided in the address. For example: 

    code=ea5b76eb-47a5-4e5d-8f71-0892178250db.5c9bce22-6b85-4654-b716-e9bbb3e755bc.cdffafbc-20fb-42b9-b254-866017057f43
    Note

    This is a temporary code that can only be used one time. If necessary, you can refresh the page or revisit the URL to obtain another code.

  5. On your terminal, use the following curl -X POST command to generate a temporary OAuth2 access token: 

    $ curl -X POST "http://localhost:8080/realms/master/protocol/openid-connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=quaydev" \
-d "client_secret=g8gPsBLxVrLo2PjmZkYBdKvcB9C7fmBz" \
-d "grant_type=authorization_code" \
-d "code=ea5b76eb-47a5-4e5d-8f71-0892178250db.5c9bce22-6b85-4654-b716-e9bbb3e755bc.cdffafbc-20fb-42b9-b254-866017057f43"

    where:

    http://localhost:8080/realms/master/protocol/openid-connect/token
    Specifies the protocol/openid-connect/token endpoint found on the Realm settings page of the Red Hat Single Sign-On UI.
    quaydev
    Specifies the Client ID used for this procedure.
    g8gPsBLxVrLo2PjmZkYBdKvcB9C7fmBz
    Specifies the Client Secret for the Client ID.
    ea5b76eb-47a5-4e5d-8f71-0892178250db.5c9bce22-6b85-4654-b716-e9bbb3e755bc.cdffafbc-20fb-42b9-b254-866017057f43

    Specifies the code returned from the redirect URI.

    Example output

    {"access_token":"<access_token>...",
"expires_in":60,"refresh_expires_in":1800,"refresh_token":"<refresh_token>","token_type":"Bearer","not-before-policy":0,"session_state":"5c9bce22-6b85-4654-b716-e9bbb3e755bc","scope":"profile email"}

  6. Store the access_token from the previous step so that you can exchange it for a Red Hat Quay robot account token in the following procedure.

To configure robot account federation in Red Hat Quay, you can map an OIDC issuer and subject to a robot account in the v2 UI.

This procedure uses Red Hat Single Sign-On, which is based on the Keycloak project. The steps, and the information used to configure a robot account federation, vary depending on your OIDC provider.

Prerequisites

  • You have created an organization. The following example uses fed_test.
  • You have created a robot account. The following example uses fest_test+robot1.
  • You have configured OIDC for your Red Hat Quay deployment. The following example uses Red Hat Single Sign-On.

Procedure

  1. On the Red Hat Single Sign-On main page:

    1. Select the appropriate realm that is authenticated for use with Red Hat Quay. Store the issuer URL, for example, https://keycloak-auth-realm.quayadmin.org/realms/quayrealm.
    2. Click Users the name of the user to be linked with the robot account for authentication. You must use the same user account that you used when generating the OAuth2 access token.

    3. On the Details page, store the ID of the user, for example, 449e14f8-9eb5-4d59-a63e-b7a77c75f770.

      Note

      The information collected in this step varies depending on your OIDC provider. For example, with Red Hat Single Sign-On, the ID of a user is used as the Subject to configure the robot account federation in a subsequent step. For a different OIDC provider, like Microsoft Entra ID, this information is stored as the Subject.

  2. On your Red Hat Quay registry:

    1. Navigate to Organizations and click the name of your organization, for example, fed_test.
    2. Click Robot Accounts.
    3. Click the menu kebab Set robot federation.
    4. Click the + symbol.

    5. In the popup window, include the following information:

      • Issuer URL: https://keycloak-auth-realm.quayadmin.org/realms/quayrealm. For Red Hat Single Sign-On, this is the URL of your Red Hat Single Sign-On realm. This might vary depending on your OIDC provider.
      • Subject: 449e14f8-9eb5-4d59-a63e-b7a77c75f770. For Red Hat Single Sign-On, the Subject is the ID of your Red Hat Single Sign-On user. This varies depending on your OIDC provider. For example, if you are using Microsoft Entra ID, the Subject is the Subject of your Entra ID user.

    6. Click Save.

      Note

      The Red Hat Quay v2 UI federation modal accepts Issuer URL and Subject only.

7.5.3. Configuring federation audiences
Copy link

To manage robot federation entries in Red Hat Quay, you can use the robot federation API to set the issuer and subject that map an OIDC identity to a robot account.

Each robot federation entry maps an external OIDC identity (issuer and subject) to a Red Hat Quay robot account. Starting in Red Hat Quay 3.18, robot federation supports an optional audiences array on each entry for token audience validation during federated robot token exchange (GET /oauth2/federation/robot/token).

Important

In Red Hat Quay 3.18, create and update requests persist issuer and subject only. The optional audiences field is not stored from API requests, and the Red Hat Quay v2 UI federation modal does not provide an audiences field. Until API support is available, federated robot token exchange skips audience validation and logs a deprecation warning when audiences is not stored for the matching federation entry. A later release requires audiences for federated robot authentication.

When audiences is present in stored federation configuration, configure it to match the aud claim values your OIDC provider issues—for example, a custom API audience such as api://quay-api for Microsoft Entra ID v2.0 tokens, or your OIDC client ID for standard flows. For Microsoft Entra ID v2.0, use an application-specific audience rather than the Microsoft Graph audience.

Prerequisites

  • You have created an organization and robot account.
  • You have configured OIDC for your Red Hat Quay deployment.
  • You have the issuer URL and subject identifier from your OIDC provider.

Procedure

  1. Create or update the robot federation configuration by using POST /api/v1/organization/{orgname}/robots/{robot_shortname}/federation. Include issuer and subject in each federation entry. For example: 

    $ curl -X POST "https://<quay-server.example.com>/api/v1/organization/fed_test/robots/robot1/federation" \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "issuer": "https://login.microsoftonline.com/<tenant-id>/v2.0",
      "subject": "<user-object-id>"
    }
  ]'
  2. After you configure federation, exchange an external OIDC access token for a Red Hat Quay robot token.

To authenticate with a federated robot account in Red Hat Quay, you can exchange an OAuth2 access token for a short-lived robot token by using a Python script.

Note

The following example uses a Python script to exchange the OAuth2 access token for a Red Hat Quay robot account token.

Prerequisites

  • You have the python3 CLI tool installed.

Procedure

  1. Save the following Python script in a .py file, for example, robot_fed_token_auth.py: 

    import requests
import os

TOKEN=os.environ.get('TOKEN')
robot_user = "fed-test+robot1"

def get_quay_robot_token(fed_token):
    URL = "https://<quay-server.example.com>/oauth2/federation/robot/token"
    response = requests.get(URL, auth=(robot_user,fed_token))
    print(response)
    print(response.text)

if __name__ == "__main__":
    get_quay_robot_token(TOKEN)

    where:

    response = requests.get(URL, auth=(robot_user,fed_token))
    Specifies the request that retrieves the robot token. If your Red Hat Quay deployment is using custom SSL/TLS certificates, the response must be response = requests.get(URL,auth=(robot_user,fed_token),verify=False), which includes the verify=False flag.

  2. Export the OAuth2 access token as TOKEN. For example: 

    $ export TOKEN=<export_token>...

  3. Run the robot_fed_token_auth.py script by entering the following command: 

    $ python3 robot_fed_token_auth.py

    Example output

    <Response [200]>
{"token": "string..."}

    Important

    This token expires after one hour. After one hour, you must generate a new token.

  4. Export the robot account access token as QUAY_TOKEN. For example: 

    $ export QUAY_TOKEN=<quay_token>

7.5.5. Pushing and pulling images
Copy link

To verify federated robot account access in Red Hat Quay, you can log in with the robot token and pull images that the robot is allowed to access.

Prerequisites

  • You have exported the OAuth2 access token into a new robot account access token.

Procedure

  1. Log in to your Red Hat Quay registry by using the fed_test+robot1 robot account and the QUAY_TOKEN access token. For example: 

    $ podman login <quay-server.example.com> -u fed_test+robot1 -p $QUAY_TOKEN

  2. Pull an image from a Red Hat Quay repository for which the robot account has the proper permissions. For example: 

    $ podman pull <quay-server.example.com>/<repository_name>/<image_name>

    Example output

    Getting image source signatures
Copying blob 900e6061671b done
Copying config 8135583d97 done
Writing manifest to image destination
Storing signatures
8135583d97feb82398909c9c97607159e6db2c4ca2c885c0b8f590ee0f9fe90d
0.57user 0.11system 0:00.99elapsed 68%CPU (0avgtext+0avgdata 78716maxresident)k
800inputs+15424outputs (18major+6528minor)pagefaults 0swaps

  3. Attempt to pull an image from a Red Hat Quay repository for which the robot account does not have the proper permissions. For example: 

    $ podman pull <quay-server.example.com>/<different_repository_name>/<image_name>

    Example output

    Error: initializing source docker://quay-server.example.com/example_repository/busybox:latest: reading manifest in quay-server.example.com/example_repository/busybox: unauthorized: access to the requested resource is not authorized

    After one hour, the credentials for this robot account expire. Afterwards, you must generate a new access token for this robot account.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Legal Notice

Theme

© 2026 Red HatBack to top