diff --git a/content/manuals/enterprise/security/access-tokens.md b/content/manuals/enterprise/security/access-tokens.md index f7432821dac5..9013dc21feeb 100644 --- a/content/manuals/enterprise/security/access-tokens.md +++ b/content/manuals/enterprise/security/access-tokens.md @@ -62,18 +62,24 @@ organization. - Label: Descriptive name indicating the token's purpose - Description (optional): Additional details - Expiration date: When the token should expire -1. Expand the **Repository** drop-down to set access permissions: +1. Expand the **Repository** drop-down to set per-repository access permissions: 1. Optional. Select **Read public repositories** for access to public repositories. 1. Select **Add repository** and choose a repository from the drop-down. - 1. Set permissions for each repository: **Image Pull** or **Image Push**. + 1. Set the permission level for each repository. Available scopes range from + pulling and pushing images to managing tags, webhooks, repository groups, + and immutable tag settings. See [Repository scopes](#repository-scopes) + for the full list. 1. Add up to 50 repositories as needed. -1. Optional. Configure organization management permissions by expanding the **Organization** drop-down and selecting the **Allow management access to this organization's resources**: +1. Optional. Configure organization-level permissions by expanding the **Organization** drop-down and selecting **Allow management access to this organization's resources**: - **Member Edit**: Edit members of the organization - **Member Read**: Read members of the organization - **Invite Edit**: Invite members to the organization - **Invite Read**: Read invites to the organization - **Group Edit**: Edit groups of the organization - **Group Read**: Read groups of the organization + - **Repository List**: List all repositories, including private ones (`scope-repository-list`) + - **Repository Create**: Create new repositories (`scope-repository-create`) + - **Registry Usage Read**: Read namespace-level registry usage metrics (`scope-registry-usage-read`) 1. Select **Generate token**. Copy the token that appears on the screen and save it. You won't be able to retrieve the token once you exit the screen. > [!IMPORTANT] @@ -104,6 +110,71 @@ organization. - **Delete** 1. Select **Save** after making changes to a token. +## Available scopes + +Scopes control what an OAT can do. Repository-level scopes are assigned per +repository when you create the token. Organization-level scopes apply to the +whole organization. + +Higher scopes include the permissions of lower ones where noted. + +### Repository scopes + +| Scope | Description | Includes | +|---|---|---| +| `scope-image-pull` | Pull images from the registry | — | +| `scope-image-push` | Push images to the registry | `scope-image-pull` | +| `scope-image-delete` | Delete images and tags via registry endpoints | `scope-image-push` | +| `scope-repository-read` | Read repository metadata, Dockerfile, and stars | — | +| `scope-repository-edit` | Edit repository privacy, categories, Dockerfile, description, and stars | `scope-repository-read` | +| `scope-repository-admin` | Delete the repository | `scope-repository-edit` | +| `scope-tag-read` | List and read tags, image lists, attestations, and compose files | — | +| `scope-tag-admin` | Delete tags | `scope-tag-read` | +| `scope-webhook-read` | List webhook pipelines and delivery history | — | +| `scope-webhook-edit` | Create webhook pipelines | `scope-webhook-read` | +| `scope-webhook-admin` | Delete webhook pipelines | `scope-webhook-edit` | +| `scope-repo-group-read` | List and read repository group assignments | — | +| `scope-repo-group-edit` | Create and update repository group assignments | `scope-repo-group-read` | +| `scope-repo-group-admin` | Delete repository group assignments | `scope-repo-group-edit` | +| `scope-repository-settings-admin` | Configure immutable tag rules | — | + +### Organization scopes + +| Scope | Description | +|---|---| +| `scope-repository-list` | List all repositories in the namespace, including private ones | +| `scope-repository-create` | Create new repositories | +| `scope-registry-usage-read` | Read namespace-level registry usage metrics | + +## Hub API support + +OATs can authenticate requests to most Docker Hub API endpoints under +`/v2/namespaces/{namespace}/repositories/`. Pass the token as a Bearer token +in the `Authorization` header with your organization name as the username. + +### Supported endpoints + +The following endpoint categories accept OAT authentication: + +- Repository management: list, create, get, update, and delete repositories +- Tags: list, get, and delete tags; get tag images, attestations, and compose files +- Dockerfile: get and update a repository's linked Dockerfile +- Repository groups: list, get, create, update, and delete group assignments +- Stars: list, count, add, and remove repository stars +- Immutable tags: update and verify immutable tag policies +- Repository categories, privacy, and webhook pipeline settings +- Namespace metrics + +### Listing behavior + +`GET /v2/namespaces/{namespace}/repositories` returns results based on the +token's configured scopes: + +- **With `scope-repository-list` scope** (or equivalent): all repositories are + returned, including private ones. +- **Without that scope**: only public repositories are returned. + + ## Organization access token best practices - Regular token rotation: Set reasonable expiration dates and rotate tokens regularly to minimize security risks. diff --git a/content/reference/api/hub/latest.yaml b/content/reference/api/hub/latest.yaml index 38034331654a..a7466d2efd88 100644 --- a/content/reference/api/hub/latest.yaml +++ b/content/reference/api/hub/latest.yaml @@ -1039,6 +1039,10 @@ paths: get: operationId: ListRepositoryTags summary: List repository tags + description: | + Returns the list of tags for the specified repository. + + tags: - repositories security: @@ -1065,6 +1069,10 @@ paths: $ref: "#/components/responses/NotFound" head: summary: Check repository tags + description: | + Checks whether the repository has any tags. + + tags: - repositories security: @@ -1084,6 +1092,10 @@ paths: get: operationId: GetRepositoryTag summary: Read repository tag + description: | + Returns details for a specific tag in the specified repository. + + tags: - repositories security: @@ -1097,6 +1109,10 @@ paths: $ref: "#/components/responses/NotFound" head: summary: Check repository tag + description: | + Checks whether the specified tag exists in the repository. + + tags: - repositories security: @@ -1119,6 +1135,8 @@ paths: Updates the immutable tags configuration for this repository. **Only users with administrative privileges for the repository can modify these settings.** + + tags: - repositories security: @@ -1144,9 +1162,11 @@ paths: operationId: VerifyRepositoryImmutableTags summary: "Verify repository immutable tags" description: | - Validates the immutable tags regex pass in parameter and returns a list of tags matching it in this repository. + Validates the immutable tags regex passed in the request body and returns a list of tags matching it in this repository. - **Only users with administrative privileges for the repository call this endpoint.** + **Only users with administrative privileges for the repository can call this endpoint.** + + tags: - repositories security: @@ -1170,6 +1190,10 @@ paths: - $ref: "#/components/parameters/repository" post: summary: Assign a group (Team) to a repository for access + description: | + Assigns an organization group (team) to a repository with a specified permission level. + + tags: - repositories operationId: CreateRepositoryGroup @@ -1217,6 +1241,10 @@ paths: Returns a list of repositories within the specified namespace (organization or user). Public repositories are accessible to everyone, while private repositories require appropriate authentication and permissions. + + + + **OAT listing behavior**: an OAT with the `scope-repository-list` scope sees all repositories including private ones. An OAT without that scope only sees public repositories. tags: - repositories security: @@ -1360,6 +1388,8 @@ paths: description: | Creates a new repository within the specified namespace. The repository will be created with the provided metadata including name, description, and privacy settings. + + operationId: CreateRepository tags: - repositories @@ -1431,6 +1461,8 @@ paths: Returns a repository within the specified namespace (organization or user). Public repositories are accessible to everyone, while private repositories require appropriate authentication and permissions. + + tags: - repositories security: @@ -1482,6 +1514,8 @@ paths: Check a repository within the specified namespace (organization or user). Public repositories are accessible to everyone, while private repositories require appropriate authentication and permissions. + + tags: - repositories security: