Merge pull request #20731 from craig-osterhout/engdocs-2167

admin: add org access tokens

Author: technicallyjosh

_vale/config/vocabularies/Docker/accept.txt

@@ -92,6 +92,7 @@ Netplan
 Nginx
 NTLM
 Nuxeo
+OAT
 OAuth
 OCI
 OTel

content/manuals/admin/organization/activity-logs.md

@@ -66,6 +66,9 @@ Refer to the following section for a list of events and their descriptions:
 | Single Sign-On domain added | Details of the single sign-on domain added to your organization |
 | Single Sign-On domain removed | Details of the single sign-on domain removed from your organization |
 | Single Sign-On domain verified | Details of the single sign-on domain verified for your organization |
+| Access token created | Access token created in organization |
+| Access token updated | Access token updated in organization |
+| Access token deleted | Access token deleted in organization |
 
 ### Repository events
 

content/manuals/docker-hub/release-notes.md

@@ -254,7 +254,7 @@ Each organization page now breaks down into these tabs:
 
 ### New features
 
-* You can now [create personal access tokens](access-tokens.md) in Docker Hub and use them to authenticate from the Docker CLI. Find them in your account settings, under the new **[Security](https://hub.docker.com/settings/security)** section.
+* You can now [create personal access tokens](/security/for-developers/access-tokens/) in Docker Hub and use them to authenticate from the Docker CLI. Find them in your account settings, under the new **[Security](https://hub.docker.com/settings/security)** section.
 
 ### Known Issues
 

content/manuals/docker-hub/service-accounts.md

@@ -11,6 +11,10 @@ weight: 50
 >
 > Service accounts require a
 > [Docker Team, or Business subscription](../subscription/_index.md).
+>
+> Docker recommends that you use organization access tokens instead of service
+> accounts. For more details, see [Organization access
+> tokens](/security/for-admins/access-tokens/).
 
 A service account is a Docker ID used for automated management of container images or containerized applications. Service accounts are typically used in automated workflows, and don't share Docker IDs with the members in the organization. Common use cases for service accounts include mirroring content on Docker Hub, or tying in image pulls from your CI/CD process.
 
@@ -49,7 +53,7 @@ To create a new service account for your Team account:
 2. Create a [team](manage-a-team.md) in your organization and grant it read-only access to your private repositories.
 3. Add the new Docker ID to your [organization](orgs.md).
 4. Add the new Docker ID  to the [team](manage-a-team.md) you created earlier.
-5. Create a new [personal access token (PAT)](access-tokens.md) from the user account and use it for CI.
+5. Create a new [personal access token (PAT)](/security/for-developers/access-tokens/) from the user account and use it for CI.
 
 > [!NOTE]
 >

content/manuals/security/for-admins/access-tokens.md

@@ -0,0 +1,120 @@
+---
+title: Organization access tokens
+description: Learn how to create and manage organization access tokens
+  to securely push and pull images programmatically.
+keywords: docker hub, security, OAT, organization access token
+linkTitle: Organization access tokens (Beta)
+---
+
+{{% experimental title="Beta" %}}
+The organization access tokens feature is currently in [Beta](../../release-lifecycle.md#beta).
+{{% /experimental %}}
+
+> [!WARNING]
+>
+> Organization access tokens aren't currently compatible with Docker Build Cloud. If you
+> are using Docker Build Cloud, you must use personal access tokens instead.
+
+An organization access token (OAT) is like a [personal access token
+(PAT)](/security/for-developers/access-tokens/), but an OAT is associated with
+an organization and not a single user account. Use an OAT instead of a PAT to
+let business-critical tasks access Docker Hub repositories without connecting
+the token to single user. You must have a [Docker Team or Business
+subscription](/subscription/core-subscription/details/) to use OATs.
+
+OATs provide the following advantages:
+
+- You can investigate when the OAT was last used and then disable or delete it
+  if you find any suspicious activity.
+- You can limit what each OAT has access to, which limits the impact if an OAT
+  is compromised.
+- All organization owners can manage OATs. If one owner leaves the organization,
+  the remaining owners can still manage the OATs.
+- OATs have their own Docker Hub usage limits that don't count towards your
+  personal account's limits.
+
+If you have existing [service accounts](/docker-hub/service-accounts/), Docker recommends that you replace the service accounts with OATs. OATs offer the following advantages over service accounts:
+
+- Access permissions are easier to manage with OATs. You can assign access
+  permissions to OATs, while service accounts require using teams for access
+  permissions.
+- OATs are easier to manage. OATs are centrally managed in the Admin Console.
+  For service accounts, you may need to sign in to that service account to
+  manage it. If using single sign-on enforcement and the service account is not
+  in your IdP, you may not be able to sign in to the service account to manage
+  it.
+- OATs are not associated with a single user. If a user with access to the
+  service account leaves your organization, you may lose access to the service
+  account. OATs can be managed by any organization owner.
+
+## Create an organization access token
+
+> [!IMPORTANT]
+>
+> Treat access tokens like a password and keep them secret. Store your tokens securely in a credential manager for example.
+
+Organization owners can create up to 10 organization access tokens (OATs) for
+organizations with a Team subscription and up to 100 OATs for organizations with
+a Business subscription. Expired tokens count towards the total amount of
+tokens.
+
+To create an OAT:
+
+1. Sign in to the [Admin Console](https://app.docker.com/admin).
+
+2. Select the organization you want to create an access token for.
+
+3. Under **Security and access**, select **Access tokens**.
+
+4. Select **Generate access token**.
+
+5. Add a label and optional description for your token. Use something that indicates the use case or purpose of the token.
+
+6. Select the expiration date for the token.
+
+7. Select the repository access for the token.
+
+   The access permissions are scopes that set restrictions in your repositories.
+   For example, for Read & Write permissions, an automation pipeline can build
+   an image and then push it to a repository. However, it can't delete the
+   repository. You can select one of the following options:
+
+   - **Public repositories (read only)**
+   - **All repositories**: You can select read access, or read and write access.
+   - **Select repositories**: You can select up to 50 repositories, and then
+     select read access, or read and write access for each repository.
+
+8. Select **Generate token** and then 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.
+
+## Use an organization access token
+
+You can use an organization access token when you sign in using Docker CLI.
+
+Sign in from your Docker CLI client with the following command, replacing
+`YOUR_ORG` with your organization name:
+
+```console
+$ docker login --username <YOUR_ORG>
+```
+
+When prompted for a password, enter your organization access token instead of a
+password.
+
+## Modify existing tokens
+
+You can rename, update the description, update the repository access,
+deactivate, or delete a token as needed.
+
+1. Sign in to the [Admin Console](https://app.docker.com/admin).
+
+2. Select the organization you want to modify an access token for.
+
+3. Under **Security and access**, select **Access tokens**.
+
+4. Select the actions menu on the far right of a token row, then select
+   **Deactivate**, **Edit**, or **Delete** to modify the token. For **Inactive**
+   tokens, you can only select **Delete**.
+
+5. If editing a token, select **Save** after specifying your modifications.