SupportConsoleDevelopersStart a trialContact

Chapter 7. Red Hat Quay Robot Account overview

Robot Accounts are used to set up automated access to the repositories in your Quay.io registry. They are similar to OpenShift Container Platform service accounts.

Setting up a Robot Account results in the following:

  • Credentials are generated that are associated with 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

Use the following procedure to create a robot account using the v2 UI.

Procedure

  1. On the v2 UI, click Organizations.
  2. Click the name of the organization that you will 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

Use the following procedure to manage, in bulk, robot account repository access 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 will be added to multiple repositories, click the kebab icon Set repository permissions.

  5. On the Set repository permissions page, check the boxes of the repositories that the robot account will be added 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 by using the UI

Red Hat Quay administrators can manage robot accounts by disallowing users to create new robot accounts.

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 and will be fixed in a future release of Red Hat Quay.

Use the following procedure to disable robot account creation.

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: Creating a new robot account

  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.

Verification: Logging into a robot account

  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

Use the following procedure to delete a robot account 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

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, or new authentication tokens.

With Red Hat Quay 3.13, Red Hat Quay administrators are provided the ability to exchange external OIDC token for short-lived, or ephemeral robot account tokens with either Red Hat Single Sign-On (based on the Keycloak project) or Microsoft Entra ID. This allows robot accounts to leverage tokens that last one hour, which are are refreshed regularly and can be used to authenticate individual transactions.

This feature greatly enhances the security of your Red Hat Quay registry by mitigating the possibility of robot token exposure by removing the 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.

7.5.1. Generating an OAuth2 token with Red Hat Sign Sign-On

The following procedure shows you how to generate an OAuth2 token using Red Hat Single Sign-On. Depending on your OIDC provider, these steps will vary.

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 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" 1
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=quaydev" 2
-d "client_secret=g8gPsBLxVrLo2PjmZkYBdKvcB9C7fmBz" 3
-d "grant_type=authorization_code"
-d "code=ea5b76eb-47a5-4e5d-8f71-0892178250db.5c9bce22-6b85-4654-b716-e9bbb3e755bc.cdffafbc-20fb-42b9-b254-866017057f43" 4
    1
    The protocol/openid-connect/token endpoint found on the Realm settings page of the Red Hat Single Sign-On UI.
    2
    The Client ID used for this procedure.
    3
    The Client Secret for the Client ID.
    4
    The code returned from the redirect URI.

    Example output

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

  6. Store the access_token from the previously step, as it will be exchanged for a Red Hat Quay robot account token in the following procedure.

7.5.2. Setting up a robot account federation by using the Red Hat Quay v2 UI

The following procedure shows you how to set up a robot account federation by using the Red Hat Quay v2 UI. This procedure uses Red Hat Single Sign-On, which is based on the Keycloak project. These steps, and the information used to set up a robot account federation, will 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 a 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 will vary depending on your OIDC provider. For example, with Red Hat Single Sign-On, the ID of a user is used as the Subject to set up 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 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 will be the Subject or your Entra ID user.
    6. Click Save.

7.5.3. Exchanging an OAuth2 access token for a Red Hat Quay robot account token

The following procedure leverages the access token generated in the previous procedure to create a new Red Hat Quay robot account token. The new Red Hat Quay robot account token is used for authentication between your OIDC provider and Red Hat Quay.

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)) 1
    print(response)
    print(response.text)

if __name__ == "__main__":
    get_quay_robot_token(TOKEN)
    1
    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 = eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJTVmExVHZ6eDd2cHVmc1dkZmc1SHdua1ZDcVlOM01DN1N5T016R0QwVGhVIn0...

  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": "291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6InByb2ZpbGUgZW1haWwiLCJlbWFpbF92ZXJpZ..."}

    Important

    This token expires after one hour. After one hour, a new token must be generated.

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

    $ export QUAY_TOKEN=291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6InByb2ZpbGUgZW1haWwiLCJlbWFpbF92ZXJpZ

7.5.4. Pushing and pulling images

After you have generated a new robot account access token and exported it, you can log in and the robot account using the access token and push and pull images.

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 using the fest_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 are set to expire. Afterwards, you must generate a new access token for this robot account.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

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

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

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

© 2024 Red Hat, Inc.