From 16774c12a5c3ecfd871d8473bd0d31f9248fbd50 Mon Sep 17 00:00:00 2001 From: Josh Newman Date: Mon, 17 Feb 2025 19:29:10 -0700 Subject: [PATCH 1/8] Improve auth docs and add oat tags --- content/reference/api/hub/latest.yaml | 100 +++++++++++++++++++++++--- layouts/_default/api-baseof.html | 26 +++++++ 2 files changed, 117 insertions(+), 9 deletions(-) diff --git a/content/reference/api/hub/latest.yaml b/content/reference/api/hub/latest.yaml index b7bcc27129de..d51954bbe47c 100644 --- a/content/reference/api/hub/latest.yaml +++ b/content/reference/api/hub/latest.yaml @@ -50,6 +50,52 @@ tags: Additionally, similar to the Docker Hub UI features, API endpoint responses may vary depending on your plan (Personal, Pro, or Team) and your account's permissions. To learn more about the features available in each plan and to upgrade your existing plan, see [Docker Pricing](https://www.docker.com/pricing). + This section describes the different types of authentication available. + + # Types + + These are the types of authentication available for the Docker Hub API. + + Each authentication type should be used with the [Create access token](#tag/authentication-api/operation/AuthCreateAccessToken) + route to obtain a bearer token to be used. + + ## Password + Using a username and password is the most powerful, yet least secure way + to authenticate with Docker as a user. It allows for access to resources + for the user without scopes. + + _In general, it is recommended to use a personal access token (PAT) instead._ + + _**This is not available if your organization has SSO enforced.**_ + + ## Personal Access Token (PAT) + Using a username and PAT is the most secure way to authenticate with + Docker as a user. PATs are scoped to specific resources and scopes. + + Currently a PAT is a more secure password due to limited functionality, + but in the future we may add fine-grained access like organization + access tokens for enhanced usage and security. + + ## Organization Access Token (OAT) + Organization access tokens are scoped to specific resources and scopes + within an organization and are managed by organization owners. + + These tokens are meant for automation and are not meant to be used by + users. + + # Labels + + These labels will show up on routes in this document that allow for bearer + tokens issued from them to be used. + + + + - name: authentication-api + x-displayName: Authentication + description: | + The authentication endpoints allow you to authenticate with Docker Hub APIs. + + For more information, see [Authentication](#tag/authentication). - name: access-tokens x-displayName: Personal Access Tokens description: | @@ -110,7 +156,7 @@ paths: /v2/users/login: post: tags: - - authentication + - authentication-api summary: Create an authentication token operationId: PostUsersLogin security: [] @@ -123,7 +169,7 @@ paths: _**As of September 16, 2024, this route requires a personal access token (PAT) instead of a password if your organization has SSO enforced.**_
- Deprecated: Use [Create access token] instead. + Deprecated: Use [Create access token] instead.
requestBody: content: @@ -148,7 +194,7 @@ paths: /v2/users/2fa-login: post: tags: - - authentication + - authentication-api summary: Second factor authentication operationId: PostUsers2FALogin security: [] @@ -183,7 +229,7 @@ paths: /v2/auth/token: post: tags: - - authentication + - authentication-api security: [] summary: Create access token operationId: AuthCreateAccessToken @@ -709,7 +755,9 @@ paths: get: summary: List org members description: | - Returns a list of members for an organization" + Returns a list of members for an organization + + tags: - orgs security: @@ -739,6 +787,8 @@ paths: summary: Export org members CSV description: | Export members of an organization as a CSV + + tags: - orgs security: @@ -812,6 +862,8 @@ paths: description: | Updates the role of a member in the organization. ***Only users in the "owners" group of the organization can use this endpoint.*** + + tags: - orgs security: @@ -850,6 +902,8 @@ paths: summary: Remove member from org description: | Removes the member from the org, ie. all groups in the org, unless they're the last owner + + tags: - orgs security: @@ -873,6 +927,8 @@ paths: summary: List org invites description: | Return all pending invites for a given org, only team owners can call this endpoint + + tags: - invites security: @@ -901,6 +957,8 @@ paths: - $ref: '#/components/parameters/org_name' get: summary: Get groups of an organization + description: | + tags: - groups security: @@ -946,7 +1004,10 @@ paths: $ref: '#/components/responses/not_found' post: summary: Create a new group - description: Create a new group within an organization. + description: | + Create a new group within an organization. + + tags: - groups security: @@ -982,6 +1043,8 @@ paths: - $ref: '#/components/parameters/group_name' get: summary: Get a group of an organization + description: | + tags: - groups security: @@ -1001,6 +1064,8 @@ paths: $ref: '#/components/responses/not_found' put: summary: Update the details for an organization group + description: | + tags: - groups security: @@ -1031,6 +1096,8 @@ paths: $ref: '#/components/responses/not_found' patch: summary: Update some details for an organization group + description: | + tags: - groups security: @@ -1059,6 +1126,8 @@ paths: $ref: '#/components/responses/not_found' delete: summary: Delete an organization group + description: | + tags: - groups security: @@ -1091,6 +1160,8 @@ paths: description: | List the members (users) that are in a group. If user is owner of the org or has otherwise elevated permissions, they can search by email and the result will also contain emails. + + tags: - groups responses: @@ -1123,7 +1194,9 @@ paths: parameters: - $ref: '#/components/parameters/org_name' - $ref: '#/components/parameters/group_name' - summary: Adds a member to a group + summary: Add a member to a group + description: | + tags: - groups security: @@ -1148,7 +1221,9 @@ paths: - $ref: '#/components/parameters/group_name' - $ref: '#/components/parameters/username' delete: - summary: Removes a user from a group + summary: Remove a user from a group + description: | + tags: - groups security: @@ -1174,6 +1249,8 @@ paths: summary: Cancel an invite description: | Mark the invite as cancelled so it doesn't show up on the list of pending invites + + tags: - invites security: @@ -1199,6 +1276,8 @@ paths: summary: Resend an invite description: | Resend a pending invite to the user, any org owner can resend an invite + + tags: - invites security: @@ -1220,6 +1299,8 @@ paths: summary: Bulk create invites description: | Create multiple invites by emails or DockerIDs. Only a team owner can create invites. + + tags: - invites requestBody: @@ -2878,9 +2959,10 @@ x-tagGroups: tags: - resources - rate-limiting + - authentication - name: API tags: - - authentication + - authentication-api - access-tokens - images - audit-logs diff --git a/layouts/_default/api-baseof.html b/layouts/_default/api-baseof.html index f8002f19215b..a629f15c6bb4 100644 --- a/layouts/_default/api-baseof.html +++ b/layouts/_default/api-baseof.html @@ -19,6 +19,32 @@ background-color: #086dd7; padding: 16px; } + + .auth-tag,.pat,.oat { + border-radius: 4px; + color: #fff; + padding: 5px; + } + + .pat { + background-color: rgb(149, 80, 124); + } + + .pat::after { + content: "personal access token"; + } + + .oat::after { + content: "org access token"; + } + + .oat { + background-color: rgb(24, 111, 175); + } + + .auth-tag:not(:last-child) { + margin-right: 5px; + } From 4156257024722e3d5e3e9705310ec8e5418eddcf Mon Sep 17 00:00:00 2001 From: Josh Newman Date: Mon, 17 Feb 2025 19:43:16 -0700 Subject: [PATCH 2/8] Remove extra line --- content/reference/api/hub/latest.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/content/reference/api/hub/latest.yaml b/content/reference/api/hub/latest.yaml index d51954bbe47c..d03b381c1490 100644 --- a/content/reference/api/hub/latest.yaml +++ b/content/reference/api/hub/latest.yaml @@ -50,7 +50,6 @@ tags: Additionally, similar to the Docker Hub UI features, API endpoint responses may vary depending on your plan (Personal, Pro, or Team) and your account's permissions. To learn more about the features available in each plan and to upgrade your existing plan, see [Docker Pricing](https://www.docker.com/pricing). - This section describes the different types of authentication available. # Types From 98c6f74a833312cd9f9bb5dee2fb5d0ad64a792a Mon Sep 17 00:00:00 2001 From: Josh Date: Tue, 18 Feb 2025 12:03:40 -0700 Subject: [PATCH 3/8] Update content/reference/api/hub/latest.yaml Co-authored-by: Sarah Sanders --- content/reference/api/hub/latest.yaml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/content/reference/api/hub/latest.yaml b/content/reference/api/hub/latest.yaml index d03b381c1490..75beaece908a 100644 --- a/content/reference/api/hub/latest.yaml +++ b/content/reference/api/hub/latest.yaml @@ -53,10 +53,9 @@ tags: # Types - These are the types of authentication available for the Docker Hub API. + The Docker Hub API supports the following authentication types. - Each authentication type should be used with the [Create access token](#tag/authentication-api/operation/AuthCreateAccessToken) - route to obtain a bearer token to be used. + You must use each authentication type with the [Create access token](#tag/authentication-api/operation/AuthCreateAccessToken) route to obtain a bearer token. ## Password Using a username and password is the most powerful, yet least secure way From 6e561ef301fd4043a3f0219770f8477cd5152b7d Mon Sep 17 00:00:00 2001 From: Josh Date: Tue, 18 Feb 2025 12:04:52 -0700 Subject: [PATCH 4/8] Update content/reference/api/hub/latest.yaml Co-authored-by: Sarah Sanders --- content/reference/api/hub/latest.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/reference/api/hub/latest.yaml b/content/reference/api/hub/latest.yaml index 75beaece908a..04843f84cbe4 100644 --- a/content/reference/api/hub/latest.yaml +++ b/content/reference/api/hub/latest.yaml @@ -59,7 +59,7 @@ tags: ## Password Using a username and password is the most powerful, yet least secure way - to authenticate with Docker as a user. It allows for access to resources + to authenticate with Docker as a user. It allows access to resources for the user without scopes. _In general, it is recommended to use a personal access token (PAT) instead._ From 4f8694eb904723c629530c85c5c6833f9e9563df Mon Sep 17 00:00:00 2001 From: Josh Date: Tue, 18 Feb 2025 12:05:05 -0700 Subject: [PATCH 5/8] Update content/reference/api/hub/latest.yaml Co-authored-by: Sarah Sanders --- content/reference/api/hub/latest.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/reference/api/hub/latest.yaml b/content/reference/api/hub/latest.yaml index 04843f84cbe4..0ecc54d8576d 100644 --- a/content/reference/api/hub/latest.yaml +++ b/content/reference/api/hub/latest.yaml @@ -64,7 +64,7 @@ tags: _In general, it is recommended to use a personal access token (PAT) instead._ - _**This is not available if your organization has SSO enforced.**_ + _**The password authentication type is not available if your organization has SSO enforced.**_ ## Personal Access Token (PAT) Using a username and PAT is the most secure way to authenticate with From 4d1e669678ead021e0813673935b8f4370d59f53 Mon Sep 17 00:00:00 2001 From: Josh Date: Tue, 18 Feb 2025 12:05:37 -0700 Subject: [PATCH 6/8] Update content/reference/api/hub/latest.yaml Co-authored-by: Sarah Sanders --- content/reference/api/hub/latest.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/reference/api/hub/latest.yaml b/content/reference/api/hub/latest.yaml index 0ecc54d8576d..bebce3b8f6cd 100644 --- a/content/reference/api/hub/latest.yaml +++ b/content/reference/api/hub/latest.yaml @@ -70,8 +70,8 @@ tags: Using a username and PAT is the most secure way to authenticate with Docker as a user. PATs are scoped to specific resources and scopes. - Currently a PAT is a more secure password due to limited functionality, - but in the future we may add fine-grained access like organization + Currently, a PAT is a more secure password due to limited functionality. + In the future, we may add fine-grained access like organization access tokens for enhanced usage and security. ## Organization Access Token (OAT) From a59a05c3fe93bf2c3d90672227943df6de15faf9 Mon Sep 17 00:00:00 2001 From: Josh Date: Tue, 18 Feb 2025 12:05:58 -0700 Subject: [PATCH 7/8] Update content/reference/api/hub/latest.yaml Co-authored-by: Sarah Sanders --- content/reference/api/hub/latest.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/reference/api/hub/latest.yaml b/content/reference/api/hub/latest.yaml index bebce3b8f6cd..6ef819473d55 100644 --- a/content/reference/api/hub/latest.yaml +++ b/content/reference/api/hub/latest.yaml @@ -76,7 +76,7 @@ tags: ## Organization Access Token (OAT) Organization access tokens are scoped to specific resources and scopes - within an organization and are managed by organization owners. + in an organization. They are managed by organization owners. These tokens are meant for automation and are not meant to be used by users. From 646244322567334980e88bc4cc69b15d91f358d6 Mon Sep 17 00:00:00 2001 From: Josh Date: Tue, 18 Feb 2025 12:06:23 -0700 Subject: [PATCH 8/8] Update content/reference/api/hub/latest.yaml Co-authored-by: Sarah Sanders --- content/reference/api/hub/latest.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/reference/api/hub/latest.yaml b/content/reference/api/hub/latest.yaml index 6ef819473d55..b652d3850df4 100644 --- a/content/reference/api/hub/latest.yaml +++ b/content/reference/api/hub/latest.yaml @@ -83,8 +83,8 @@ tags: # Labels - These labels will show up on routes in this document that allow for bearer - tokens issued from them to be used. + These labels will show up on routes in this reference that allow for use of bearer + tokens issued from them.