Chapter 2. OAuth 2 access tokens

Procedure

1. On the Red Hat Quay UI, select your organization.
2. In the navigation pane, click OAuth Applications.

3. Create an application if you do not already have one:

   1. Click Create OAuth Application.
   2. Enter an application name and any required application details, such as homepage URL, description, avatar e-mail, and redirect/callback URL.
   3. Click Create application.
4. Click the name of your OAuth application.
5. Click API Access Tokens.
6. Click Generate New Token.

7. Configure the token:

   1. Enter a Token name.
   2. Set an expiration period, such as 10 years.
   3. Optional: Click Assign another user to assign this OAuth token to another user. When prompted, select the desired user.

   4. Select the permissions, or scopes, for the token. For example:

      1. Administer Organization. This application can administer your organizations, including creating robots, creating teams, adjusting team membership, and changing billing settings. Grant this permission only when you have absolute trust in the requesting application.
      2. Administer Repositories. This application has administrator access to all repositories to which the granting user has access.
      3. Create Repositories. This application can create repositories in all namespaces where the granting user can create repositories.
      4. View all visible repositories. This application can view and pull all repositories visible to the granting user.
      5. Read/Write to any accessible repositories. This application can view, push, and pull to all repositories to which the granting user has write access.
      6. Super User Access. This application can administer your installation, including managing users, managing organizations, and other features found in the superuser panel. Grant this permission only when you have absolute trust in the requesting application.
      7. Administer User. This application can administer your account, including creating robots and granting them permissions to your repositories. Grant this permission only when you have absolute trust in the requesting application.
      8. Read User Information. This application can read user information such as username and email address.
8. Click Generate token.

9. Review the requested permissions, then click Authorize Application. Confirm the authorization when prompted.

   Important

   Assign only the scopes that the token holder needs. Treat Administer Organization, Super User Access, and Administer User as high-trust permissions.

10. Copy and store the access token secret.

    Important

    This is the only opportunity to copy the token secret. Red Hat Quay does not show the full secret again after you leave the page.

Verification

1. Confirm that the new token appears on the API Access Tokens page for the application. The list can include the token name, creator, scopes, expiration, and last-used information when those columns are available.

2. Optional. Call an API endpoint with the token to confirm that it works. For example:

   $ curl -X GET "https://<quay-server.example.com>/api/v1/user/" \
        -H "Authorization: Bearer <access_token>"

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.
5. In the navigation pane, click OAuth Applications.
6. Click the proper application name.
7. In the navigation pane, click API Access Tokens.
8. Click Generate New Token.
9. Click Assign another user and enter the name of the user who takes over the OAuth token.

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

    The team role within an organization defines permission control 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 by using the config.yaml file and the box must be checked here.

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

12. 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. Ask the assigned user to log in to the Red Hat Quay registry.
2. After the assigned user has logged in, ask them to click their username under Users and Organizations.
3. In the navigation pane, ask them to click External Logins And Applications.
4. Under Authorized Applications, ask them to 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. Ask them to save this bearer token, because it cannot be viewed again.

Procedure

1. On the Red Hat Quay UI, click the name of the organization that hosts the application.
2. In the navigation pane, click OAuth Applications.
3. Click the application name that holds the OAuth 2 token that you want to revoke.
4. Click API Access Tokens.
5. Click the menu kebab of the appropriate token and then click Revoke. Confirm that you want to revoke the token by clicking Revoke token.

Verification

1. Confirm that the token no longer appears as an active token on the API Access Tokens page.

Procedure

1. On the Red Hat Quay UI, click Organization OAuth Applications.
2. Click the application name.
3. Click API Access Tokens.
4. Identify the legacy token to replace. Legacy tokens do not have a user-defined name, do not show a creation date, and have an expiration date of 10 years from the date of creation.
5. Click Generate New Token.

6. Configure a replacement token:

   1. Enter a Token name.
   2. Set an expiration appropriate for the workload, for example 7 days or 10 years.
   3. Select the scopes required by the client.
7. Click Generate Token, then click Authorize Application and confirm the authorization.
8. Copy the new token secret and store it securely.
9. Update the CI system, script, or client configuration to use the new token.
10. Verify that the client works with the new token.

11. Return to the OAuth Applications page and revoke the legacy token:

    1. Click the application name that owns the legacy token.
    2. Click the menu kebab icon for the legacy token.
    3. Click Revoke. Confirm that you want to revoke the token by clicking Revoke token.