|
1 | 1 | --- |
2 | 2 | title: Organization access tokens |
3 | | -description: Learn how to create and manage organization access tokens |
4 | | - to securely push and pull images programmatically. |
5 | | -keywords: docker hub, security, OAT, organization access token |
6 | 3 | linkTitle: Organization access tokens |
| 4 | +description: Create and manage organization access tokens to securely authenticate automated systems and CI/CD pipelines with Docker Hub |
| 5 | +keywords: organization access tokens, OAT, docker hub security, programmatic access, automation |
7 | 6 | aliases: |
8 | 7 | - /security/for-admins/access-tokens/ |
9 | 8 | --- |
10 | 9 |
|
11 | 10 | {{< summary-bar feature_name="OATs" >}} |
12 | 11 |
|
| 12 | +Organization access tokens (OATs) provide secure, programmatic access to Docker Hub for automated systems, CI/CD pipelines, and other business-critical tasks. Unlike personal access tokens tied to individual users, OATs are associated with your organization and can be managed by any organization owner. |
| 13 | + |
13 | 14 | > [!WARNING] |
14 | 15 | > |
15 | | -> Organization access tokens (OATs) are incompatible with Docker Desktop, |
16 | | -> [Image Access Management (IAM)](/manuals/enterprise/security/hardened-desktop/image-access-management.md), and [Registry Access Management (RAM)](/manuals/enterprise/security/hardened-desktop/registry-access-management.md). |
17 | | -> |
18 | | -> If you use Docker Desktop, IAM, or RAM, you must use personal |
19 | | -> access tokens instead. |
20 | | -
|
21 | | -An organization access token (OAT) is like a [personal access token |
22 | | -(PAT)](/security/access-tokens/), but an OAT is associated with |
23 | | -an organization and not a single user account. Use an OAT instead of a PAT to |
24 | | -let business-critical tasks access Docker Hub repositories without connecting |
25 | | -the token to single user. You must have a [Docker Team or Business |
26 | | -subscription](/subscription/core-subscription/details/) to use OATs. |
27 | | - |
28 | | -OATs provide the following advantages: |
29 | | - |
30 | | -- You can investigate when the OAT was last used and then disable or delete it |
31 | | - if you find any suspicious activity. |
32 | | -- You can limit what each OAT has access to, which limits the impact if an OAT |
33 | | - is compromised. |
34 | | -- All company or organization owners can manage OATs. If one owner leaves the |
35 | | - organization, the remaining owners can still manage the OATs. |
36 | | -- OATs have their own Docker Hub usage limits that don't count towards your |
37 | | - personal account's limits. |
38 | | - |
39 | | -If you have existing [service accounts](/docker-hub/service-accounts/), |
40 | | -Docker recommends that you replace the service accounts with OATs. OATs offer |
41 | | -the following advantages over service accounts: |
42 | | - |
43 | | -- Access permissions are easier to manage with OATs. You can assign access |
44 | | - permissions to OATs, while service accounts require using teams for access |
45 | | - permissions. |
46 | | -- OATs are easier to manage. OATs are centrally managed in the Admin Console. |
47 | | - For service accounts, you may need to sign in to that service account to |
48 | | - manage it. If using single sign-on enforcement and the service account is not |
49 | | - in your IdP, you may not be able to sign in to the service account to manage |
50 | | - it. |
51 | | -- OATs are not associated with a single user. If a user with access to the |
52 | | - service account leaves your organization, you may lose access to the service |
53 | | - account. OATs can be managed by any company or organization owner. |
| 16 | +> Organization access tokens are incompatible with Docker Desktop, Image Access Management, and Registry Access Management. If you use these features, use [personal access tokens](/manuals/security/access-tokens.md) instead. |
| 17 | +
|
| 18 | +## Who should use organization access tokens? |
| 19 | + |
| 20 | +Use OATs for automated systems that need Docker Hub access without depending on individual user accounts: |
| 21 | + |
| 22 | +- CI/CD pipelines: Build and deployment systems that push and pull images |
| 23 | +- Production systems: Applications that pull images during deployment |
| 24 | +- Monitoring tools: Systems that need to check repository status or pull images |
| 25 | +- Backup systems: Tools that periodically pull images for archival |
| 26 | +- Integration services: Third-party tools that integrate with your Docker Hub repositories |
| 27 | + |
| 28 | +## Key benefits |
| 29 | + |
| 30 | +Benefits of using organization access tokens include: |
| 31 | + |
| 32 | +- Organizational ownership: Not tied to individual users who might leave the company |
| 33 | +- Shared management: All organization owners can create and manage OATs |
| 34 | +- Separate usage limits: OATs have their own Docker Hub rate limits, not counting against personal accounts |
| 35 | +- Better security audit: Track when tokens were last used and identify suspicious activity |
| 36 | +- Granular permissions: Limit access to specific repositories and operations |
| 37 | + |
| 38 | +## Prerequisites |
| 39 | + |
| 40 | +To create and use organization access tokens, you must have: |
| 41 | + |
| 42 | +- A Docker Team or Business subscription |
| 43 | +- Owner permissions |
| 44 | +- Repositories you want to grant access to |
54 | 45 |
|
55 | 46 | ## Create an organization access token |
56 | 47 |
|
57 | | -> [!IMPORTANT] |
58 | | -> |
59 | | -> Treat access tokens like a password and keep them secret. Store your tokens |
60 | | -> securely in a credential manager for example. |
| 48 | +Owners can create tokens with these limits: |
61 | 49 |
|
62 | | -Company or organization owners can create up to: |
63 | | -- 10 OATs for organizations with a Team subscription |
64 | | -- 100 OATs for organizations with a Business subscription |
| 50 | +- Team subscription: Up to 10 OATs per organization |
| 51 | +- Business subscription: Up to 100 OATs per organization |
65 | 52 |
|
66 | | -Expired tokens count towards the total amount of tokens. |
| 53 | +Expired tokens count toward your total limit. |
67 | 54 |
|
68 | 55 | To create an OAT: |
69 | 56 |
|
70 | 57 | 1. Sign in to [Docker Home](https://app.docker.com/) and select your |
71 | 58 | organization. |
72 | 59 | 1. Select **Admin Console**, then **Access tokens**. |
73 | 60 | 1. Select **Generate access token**. |
74 | | -1. Add a label and optional description for your token. Use something that |
75 | | -indicates the use case or purpose of the token. |
76 | | -1. Select the expiration date for the token. |
77 | | -1. Expand the **Repository** drop-down to set access permission |
78 | | -scopes for your token. To set Repository access scopes: |
79 | | - 1. Optional. Select **Read public repositories**. |
| 61 | +1. Configure token details: |
| 62 | + - Label: Descriptive name indicating the token's purpose |
| 63 | + - Description (optional): Additional details |
| 64 | + - Expiration date: When the token should expire |
| 65 | +1. Expand the **Repository** drop-down to set access permissions: |
| 66 | + 1. Optional. Select **Read public repositories** for access to public repositories. |
80 | 67 | 1. Select **Add repository** and choose a repository from the drop-down. |
81 | | - 1. Set the scopes for your repository — **Image Push** or |
82 | | - **Image Pull**. |
83 | | - 1. Add more repositories as needed. You can add up to 50 repositories. |
84 | | -1. Optional. Expand the **Organization** drop-down and select the |
85 | | -**Allow management access to this organization's resources** checkbox. This |
86 | | -setting enables organization management scopes for your token. The following |
87 | | -organization management scopes are available: |
| 68 | + 1. Set permissions for each repository: **Image Pull** or **Image Push**. |
| 69 | + 1. Add up to 50 repositories as needed. |
| 70 | +1. Optional. Configure organization management permissions by expanding the **Organization** drop-down and selecting the **Allow management access to this organization's resources**: |
88 | 71 | - **Member Edit**: Edit members of the organization |
89 | 72 | - **Member Read**: Read members of the organization |
90 | 73 | - **Invite Edit**: Invite members to the organization |
91 | 74 | - **Invite Read**: Read invites to the organization |
92 | 75 | - **Group Edit**: Edit groups of the organization |
93 | 76 | - **Group Read**: Read groups of the organization |
94 | | -1. Select **Generate token**. Copy the token that appears on the screen |
95 | | - and save it. You won't be able to retrieve the token once you exit the |
96 | | - screen. |
| 77 | +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. |
97 | 78 |
|
98 | | -## Use an organization access token |
| 79 | +> [!IMPORTANT] |
| 80 | +> |
| 81 | +> Treat organization access tokens like passwords. Store them securely in a credential manager and never commit them to source code repositories. |
99 | 82 |
|
100 | | -You can use an organization access token when you sign in using Docker CLI. |
| 83 | +## Use organization access tokens |
101 | 84 |
|
102 | | -Sign in from your Docker CLI client with the following command, replacing |
103 | | -`YOUR_ORG` with your organization name: |
| 85 | +Sign in to the Docker CLI using your organization access token: |
104 | 86 |
|
105 | 87 | ```console |
106 | | -$ docker login --username <YOUR_ORG> |
| 88 | +$ docker login --username <YOUR_ORGANIZATION_NAME> |
| 89 | +Password: [paste your OAT here] |
107 | 90 | ``` |
108 | 91 |
|
109 | | -When prompted for a password, enter your organization access token instead of a |
110 | | -password. |
| 92 | +When prompted for a password, enter your organization access token. |
111 | 93 |
|
112 | 94 | ## Modify existing tokens |
113 | 95 |
|
114 | | -You can rename, update the description, update the repository access, |
115 | | -deactivate, or delete a token as needed. |
| 96 | +To manage existing tokens: |
116 | 97 |
|
117 | 98 | 1. Sign in to [Docker Home](https://app.docker.com/) and select your |
118 | 99 | organization. |
119 | 100 | 1. Select **Admin Console**, then **Access tokens**. |
120 | | -1. Select the actions menu in the token row, then select **Deactivate**, **Edit**, or **Delete** to modify the token. For **Inactive** tokens, you can only select **Delete**. |
121 | | -1. If editing a token, select **Save** after specifying your modifications. |
| 101 | +1. Select the actions menu in the token row, you can: |
| 102 | + - **Edit** |
| 103 | + - **Deactivate** |
| 104 | + - **Delete** |
| 105 | +1. Select **Save** after making changes to a token. |
| 106 | + |
| 107 | +## Organization access token best practices |
| 108 | + |
| 109 | +- Regular token rotation: Set reasonable expiration dates and rotate tokens regularly to minimize security risks. |
| 110 | +- Principle of least privilege: Grant only the minimum repository access and permissions needed for each use case. |
| 111 | +- Monitor token usage: Regularly review when tokens were last used to identify unused or suspicious tokens. |
| 112 | +- Secure storage: Store tokens in secure credential management systems, never in plain text or source code. |
| 113 | +- Immediate revocation: Deactivate or delete tokens immediately if they're compromised or no longer needed. |
0 commit comments