SupportConsoleDevelopersStart a trialContact

Chapter 2. OAuth 2 access tokens

OAuth 2 access tokens (considered "API tokens" for Red Hat Quay) enable user-authenticated access to the Red Hat Quay API, suitable for applications that require user identity verification. These tokens are obtained through an OAuth 2 authorization process, where a Red Hat Quay administrator generates a token on behalf of themselves or another user to access Red Hat Quay API endpoints. OAuth 2 tokens authorize actions on API endpoints based on the scopes defined for the token.

Note

Although OAuth 2 tokens authorize actions on API endpoints based on the scopes defined for the token, access to the resources themselves is governed by Red Hat Quay’s role-based access control (RBAC) mechanisms. Actions can be created on a resource, for example, a repository, provided that you have the proper role (Admin or Creator) to do so for that namespace. This is true even if the API token was granted the repo:admin scope.

OAuth 2 access tokens can only be created by using the Red Hat Quay UI; there is no way to create an OAuth 2 access token by using the CLI. When creating an OAuth 2 token, the following options can be selected for a token holder:

  • Administer Organization. When selected, allows the user to be able to administer organizations, including creating robots, creating teams, adjusting team membership, and changing billing settings.
  • Administer Repositories. When selected, provides the user administrator access to all repositories to which the granting user has access.
  • Create Repositories. When selected, provides the user the ability to create repositories in any namespaces that the granting user is allowed to create repositories.
  • View all visible repositories. When selected, provides the user the ability to view and pull all repositories visible to the granting user.
  • Read/Write to any accessible repositories. When selected, provides the user the ability to view, push and pull to all repositories to which the granting user has write access.
  • Super User Access. When selected, provides the user the ability to administer your installation including managing users, managing organizations and other features found in the superuser panel.
  • Administer User When selected, provides the user the ability to administer your account including creating robots and granting them permissions to your repositories.
  • Read User Information. When selected, provides the user the ability to read user information such as username and email address.

Token distributors should be mindful of the permissions that they are granting when generating a token on behalf of a user, and should have absolute trust in a user before granting such permissions as Administer organization, Super User Access, and Administer User. Additionally, the access token is only revealed at the time of creation; they cannot be listed from the CLI, nor can they be found on the Red Hat Quay UI. If an access token is lost or forgotten, a new token must be created; a token cannot be recovered.

OAuth 2 access tokens are passed as a Bearer token in the Authorization header of an API call and, as a result, are used to provide authentication and authorization to the defined API endpoint, such as an image tag, a repository, an organization, and so on.

The API is available from the /api/v1 endpoint of your Red Hat Quay host. For example, https://<quay-server.example.com>/api/v1. It allows users to connect to endpoints through their browser to GET, POST, DELETE, and PUT Red Hat Quay settings by enabling the Swagger UI. The API can be accessed by applications that make API calls and use OAuth tokens, and it sends and receives data as JSON.

With Red Hat Quay, there is currently no way to rotate or to set an expiration time on an OAuth 2 access token, and the token lifespan is 10 years. Tokens can be deleted by deleting the applications in which they were created in the event that they are compromised, however, this deletes all tokens that were made within that specific application.

Note

In practice, Red Hat Quay administrators could create a new OAuth application on the Applications page of their organization each time they wanted to create a new OAuth token for a user. This would ensure that a single application is not responsible for all OAuth tokens. As a result, in the event that a user’s token is compromised, the administrator would delete the application of the compromised token. This would help avoid disruption for other users whose tokens might be part of the same application.

The following sections shows you how to generate and reassign an OAuth 2 access token.

2.1. Creating an OAuth 2 access token

With Red Hat Quay, you must create an OAuth 2 access token before you can access the API endpoints of your organization. OAuth 2 access token can only be generated by using the Red Hat Quay UI; the CLI cannot be used to generate an OAuth 2 access token.

Use the following procedure to create an OAuth2 access token.

Prerequisites

  • You have logged in to Red Hat Quay as an administrator.
  • You have created an OAuth 2 application.

Procedure

  1. On the main page, select an Organization.
  2. In the navigation pane, select Applications.
  3. Click the name of your application, for example, Test application.
  4. In the navigation pane, select Generate Token.

  5. Check the boxes for the following options:

    1. Administer Organization. When selected, allows the user to be able to administer organizations, including creating robots, creating teams, adjusting team membership, and changing billing settings.
    2. Administer Repositories. When selected, provides the user administrator access to all repositories to which the granting user has access.
    3. Create Repositories. When selected, provides the user the ability to create repositories in any namespaces that the granting user is allowed to create repositories.
    4. View all visible repositories. When selected, provides the user the ability to view and pull all repositories visible to the granting user.
    5. Read/Write to any accessible repositories. When selected, provides the user the ability to view, push and pull to all repositories to which the granting user has write access.
    6. Super User Access. When selected, provides the user the ability to administer your installation including managing users, managing organizations and other features found in the superuser panel.
    7. Administer User When selected, provides the user the ability to administer your account including creating robots and granting them permissions to your repositories.
    8. Read User Information. When selected, provides the user the ability to read user information such as username and email address.
  6. Click Generate Access Token. You are redirected to a new page.
  7. Review the permissions that you are allowing, then click Authorize Application. Confirm your decision by clicking Authorize Application.

  8. You are redirected to the Access Token page. Copy and save the access token.

    Important

    This is the only opportunity to copy and save the access token. It cannot be reobtained after leaving this page.

2.2. Reassigning an OAuth access token

Organization administrators can assign OAuth API tokens to be created by other user’s with specific permissions. This allows the audit logs to be reflected accurately when the token is used by a user that has no organization administrative permissions to create an OAuth API token.

Note

The following procedure only works on the current Red Hat Quay UI. It is not currently implemented in the Red Hat Quay v2 UI.

Prerequisites

  • You are logged in as a user with organization administrative privileges, which allows you to assign an OAuth API token.

    Note

    OAuth API tokens are used for authentication and not authorization. For example, the user that you are assigning the OAuth token to must have the Admin team role to use administrative API endpoints. For more information, see Managing access to repositories.

Procedure

  1. Optional. If not already, update your Red Hat Quay config.yaml file to include the FEATURE_ASSIGN_OAUTH_TOKEN: true field: 

    # ...
FEATURE_ASSIGN_OAUTH_TOKEN: true
# ...
  2. Optional. Restart your Red Hat Quay registry.
  3. Log in to your Red Hat Quay registry as an organization administrator.
  4. Click the name of the organization in which you created the OAuth token for.
  5. In the navigation pane, click Applications.
  6. Click the proper application name.
  7. In the navigation pane, click Generate Token.
  8. Click Assign another user and enter the name of the user that will take over the OAuth token.

  9. Check the boxes for the desired permissions that you want the new user to have. For example, if you only want the new user to be able to create repositories, click Create Repositories.

    Important

    Permission control is defined by the team role within an organization and must be configured regardless of the options selected here. For example, the user that you are assigning the OAuth token to must have the Admin team role to use administrative API endpoints.

    Solely checking the Super User Access box does not actually grant the user this permission. Superusers must be configured via the config.yaml file and the box must be checked here.

  10. Click Assign token. A popup box appears that confirms authorization with the following message and shows you the approved permissions: 

    This will prompt user <username> to generate a token with the following permissions:
repo:create

  11. Click Assign token in the popup box. You are redirected to a new page that displays the following message: 

    Token assigned successfully

Verification

  1. After reassigning an OAuth token, the assigned user must accept the token to receive the bearer token, which is required to use API endpoints. Request that the assigned user logs into the Red Hat Quay registry.
  2. After they have logged in, they must click their username under Users and Organizations.
  3. In the navigation pane, they must click External Logins And Applications.
  4. Under Authorized Applications, they must confirm the application by clicking Authorize Application. They are directed to a new page where they must reconfirm by clicking Authorize Application.
  5. They are redirected to a new page that reveals their bearer token. They must save this bearer token, as it cannot be viewed again.

2.3. Deleting an OAuth 2 access token

Because OAuth 2 access tokens are created through the OAuth application, they cannot be rotated or renewed. In the event that a token is compromised, or you need to delete a token, you must deleted its associated application through the Red Hat Quay UI.

Important

Deleting an application deletes all tokens that were made within that specific application. Use with caution.

Prerequisites

  • You have created an OAuth 2 access token.

Procedure

  1. On the Red Hat Quay UI, click the name of the organization hosting the application. Then, in the navigation pane, click Applications.
  2. Click the application name, for example, Test application.
  3. In the navigation pane, click Delete Application. You are redirected to a new page. Click Delete application and confirm your decision.
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.