Chapter 2. Programmatic OAuth token provisioning

Procedure

1. Set the following fields in your Red Hat Quay config.yaml file:

   FEATURE_PROGRAMMATIC_BOOTSTRAP: true
   SUPER_USERS:
     - quayadmin
   BOOTSTRAP_TOKEN_OWNER: quayadmin
   BOOTSTRAP_TOKEN_EXPIRATION: 7776000
   BOOTSTRAP_TOKEN_SCOPE: "org:admin repo:admin repo:create repo:read repo:write super:user user:admin user:read"
   BOOTSTRAP_TOKEN_PATH: /datastorage/bootstrap-token.json

   Set BOOTSTRAP_TOKEN_PATH to a directory that the Red Hat Quay process can write. In containerized standalone deployments, use a mounted storage path such as /datastorage/bootstrap-token.json. Quote the BOOTSTRAP_TOKEN_SCOPE value so YAML does not misparse scopes that contain :.

2. Restart Red Hat Quay after you update the configuration.

   Note

   If you enable FEATURE_PROGRAMMATIC_BOOTSTRAP on a deployment that is already running, you must restart Red Hat Quay so the bootstrap token is provisioned and the POST /api/v1/bootstrap/renew endpoint is registered. A full restart is required; reloading configuration without restarting does not register the bootstrap API endpoints.

3. Verify bootstrap provisioning:

   1. Check Red Hat Quay startup logs for a Bootstrap token provisioned message.

   2. Confirm that the bootstrap token file exists at the configured storage location. For example:

      $ ls -l <BOOTSTRAP_TOKEN_PATH>

Procedure

1. Retrieve the name of the configBundleSecret resource:

   $ oc get quayregistry <quayregistry_name> -n <quay_namespace> \
     -o jsonpath='{.spec.configBundleSecret}{"\n"}'

   Example output

   example-registry-config-bundle-abc12

2. Export the current config.yaml file from the secret:

   $ oc get secret -n <quay_namespace> <config_bundle_secret_name> \
     -o jsonpath='{.data.config\.yaml}' | base64 -d > config.yaml

3. Edit config.yaml and add the programmatic bootstrap fields. For example:

   FEATURE_PROGRAMMATIC_BOOTSTRAP: true
   SUPER_USERS:
     - quayadmin
   BOOTSTRAP_TOKEN_OWNER: quayadmin
   BOOTSTRAP_TOKEN_EXPIRATION: 7776000
   BOOTSTRAP_TOKEN_SCOPE: "org:admin repo:admin repo:create repo:read repo:write super:user user:admin user:read"

   Important
   • BOOTSTRAP_TOKEN_OWNER must be an existing superuser that is also listed under SUPER_USERS.
   • Quote the BOOTSTRAP_TOKEN_SCOPE value. Unquoted scope strings that contain : can be misparsed by YAML.
   • Do not set BOOTSTRAP_TOKEN_PATH for Operator deployments. The Operator stores the token in a Kubernetes Secret.
   • You do not need to set PROGRAMMATIC_TOKEN_K8S_SECRET, PROGRAMMATIC_TOKEN_K8S_KEY, or PROGRAMMATIC_TOKEN_K8S_NAMESPACE. The Operator injects those values and creates the Secret named <quayregistry_name>-bootstrap-token.

4. Create a new config bundle secret that includes the updated config.yaml file:

   $ oc create secret generic <new_config_bundle_secret_name> \
     --from-file=config.yaml=./config.yaml \
     -n <quay_namespace>

5. Update the QuayRegistry CR to reference the new secret:

   $ oc patch quayregistry <quayregistry_name> -n <quay_namespace> \
     --type=merge -p '{"spec":{"configBundleSecret":"<new_config_bundle_secret_name>"}}'

   The Operator reconciles the change, creates the <quayregistry_name>-bootstrap-token Secret with accompanying Role and RoleBinding resources, mounts the Secret into the Quay application pods, and restarts Quay-related pods.

6. Wait for the Quay application pods to become ready:

   $ oc get pods -n <quay_namespace> -l quay-component=quay-app

7. Verify that the Operator created the bootstrap token Secret:

   $ oc get secret <quayregistry_name>-bootstrap-token -n <quay_namespace>

8. Read the bootstrap token from the Secret:

   $ BOOTSTRAP_TOKEN=$(oc get secret <quayregistry_name>-bootstrap-token -n <quay_namespace> \
     -o jsonpath='{.data.token\.json}' | base64 -d | jq -r '.access_token')

   Note

   Secret propagation can take up to 60 seconds after the Quay pods start. If token.json is missing, wait and retry the command.

9. Optional. Confirm that Quay startup logs include a bootstrap provisioning message:

   $ oc logs -n <quay_namespace> deploy/<quayregistry_name>-quay-app -c quay-app \
     | grep -i 'bootstrap token'

Procedure

1. For standalone or virtual machine deployments, read the token from the BOOTSTRAP_TOKEN_PATH file:

   $ BOOTSTRAP_TOKEN=$(jq -r '.access_token' /var/lib/quay/quay-machine-token.json)

   Note

   Red Hat Quay writes the bootstrap token file with 0600 permissions owned by the Red Hat Quay process user. If you cannot read the file from the host, read it from inside the Red Hat Quay container instead. For example:

   $ BOOTSTRAP_TOKEN=$(docker exec quay cat /datastorage/bootstrap-token.json | jq -r '.access_token')

2. For Red Hat Quay on OpenShift Container Platform Operator deployments, read the token from the Operator-managed Secret. The Secret name is <quayregistry_name>-bootstrap-token:

   $ BOOTSTRAP_TOKEN=$(oc get secret <quayregistry_name>-bootstrap-token -n <quay_namespace> \
     -o jsonpath='{.data.token\.json}' | base64 -d | jq -r '.access_token')

   Example

   $ BOOTSTRAP_TOKEN=$(oc get secret example-registry-bootstrap-token -n quay-operator \
     -o jsonpath='{.data.token\.json}' | base64 -d | jq -r '.access_token')

   Note

   Secret propagation can take up to 60 seconds after renewal or initial provisioning. If the token.json key is missing, wait for the Quay application pods to finish starting and retry the command.

Procedure

1. Export the bootstrap token. For example:

   $ export BOOTSTRAP_TOKEN=<bootstrap_token_value>

2. Create an organization:

   $ curl -H "Authorization: Bearer $BOOTSTRAP_TOKEN" -X POST \
     -H "Content-Type: application/json" \
     -d '{"name": "myorg", "email": "admin@example.com"}' \
     https://<quay-server.example.com>/api/v1/organization/

3. Create an OAuth application in the organization:

   $ curl -H "Authorization: Bearer $BOOTSTRAP_TOKEN" -X POST \
     -H "Content-Type: application/json" \
     -d '{"name": "ci-automation", "description": "CI/CD token source"}' \
     https://<quay-server.example.com>/api/v1/organization/myorg/applications

4. Create a scoped OAuth API token for the application:

   $ curl -H "Authorization: Bearer $BOOTSTRAP_TOKEN" -X POST \
     -H "Content-Type: application/json" \
     -d '{"name": "ci-job-token", "scope": "repo:read repo:write", "expiration": 2592000}' \
     https://<quay-server.example.com>/api/v1/organization/myorg/applications/<client_id>/tokens

5. Store the token value from the response for your automation workflow. The token secret is returned only in the create response.

Procedure

1. List existing tokens for an application:

   $ curl -H "Authorization: Bearer <access_token>" -X GET \
     https://<quay-server.example.com>/api/v1/organization/myorg/applications/<client_id>/tokens

2. Create a token with a custom expiration and scope:

   $ curl -H "Authorization: Bearer <access_token>" -X POST \
     -H "Content-Type: application/json" \
     -d '{"name": "short-lived-token", "scope": "repo:read", "expiration": 3600}' \
     https://<quay-server.example.com>/api/v1/organization/myorg/applications/<client_id>/tokens

3. Revoke a token by UUID:

   $ curl -H "Authorization: Bearer <access_token>" -X DELETE \
     https://<quay-server.example.com>/api/v1/organization/myorg/applications/<client_id>/tokens/<token_uuid>

Procedure

1. Renew the token by using the bootstrap token as Bearer authentication:

   $ curl -H "Authorization: Bearer $BOOTSTRAP_TOKEN" -X POST \
     https://<quay-server.example.com>/api/v1/bootstrap/renew

   The following example shows a successful response:

   {"status": "rotated"}

2. Read the new token value from BOOTSTRAP_TOKEN_PATH or the configured Kubernetes Secret. The previous bootstrap token is invalidated immediately.

   Note

   If the bootstrap token is already expired, renewal is accepted only from localhost. On Kubernetes and OpenShift Container Platform, use port forwarding to send the renewal request through the local ingress path.