Skip to content

Commit ad3a83e

Browse files
sarahsanders-dockersarahsanders-docker
committed
add OIDC docs
1 parent e6c52c8 commit ad3a83e

File tree

3 files changed

+171
-0
lines changed

3 files changed

+171
-0
lines changed

‎content/manuals/security/_index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,10 @@ grid_admins:
5959
description: Create organization access tokens as an alternative to a password.
6060
link: /security/for-admins/access-tokens/
6161
icon: password
62+
- title: OIDC connections
63+
description: Create and manage OIDC connections in Docker Home.
64+
link: /security/for-admins/OIDC-connections.md
65+
icon: lock
6266
- title: Enforce sign-in
6367
description: Enforce your users to sign in to Docker Desktop.
6468
link: /security/for-admins/enforce-sign-in/

‎content/manuals/security/for-admins/OIDC-connections.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
---
2+
description: Learn how to create and manage OIDC connections in Docker.
3+
keywords: OIDC, GitHub Actions, tokens
4+
title: OIDC connections
5+
---
6+
7+
{{< summary-bar feature_name="OIDC connections" >}}
8+
9+
Docker's OIDC connections enable secure authentication between GitHub Actions workflows and Docker without storing long-lived credentials. By using short-lived tokens, it reduces the risk of credential exposure and allows for fine-grained access control to your Docker resources.
10+
11+
When a GitHub Actions workflow needs to authenticate with Docker services, it can obtain a temporary OIDC token and exchange it for a Docker-issued access token.
12+
13+
## Authentication flow
14+
15+
1. A GitHub Actions workflow requests an OIDC token.
16+
2. GitHub issues a signed OIDC token.
17+
3. The workflow sends this token to Docker’s token service.
18+
4. Docker validates the token’s signature.
19+
5. If the token is valid and matches the configured rules, Docker returns a short-lived access token.
20+
6. The workflow uses this access token to access Docker services.
21+
22+
GitHub OIDC tokens identify the calling workflow or organization and are treated like passwords for authentication. They are valid for a short period, minimizing the risk of compromise.
23+
24+
## Core concepts
25+
26+
Docker Hub manages GitHub OIDC authentication through configurations and rulesets.
27+
28+
- Configurations define the type of OIDC connection. Currently, Docker only supports GitHub Actions connection types.
29+
- Rulesets determine which GitHub workflows can authenticate and what resources they can access. Each ruleset includes:
30+
- Label: The name of the ruleset.
31+
- Subject claims: Conditions based on OIDC claims (e.g., repository name, branch, workflow).
32+
- Resources: Docker Hub repositories or Docker Cloud resources accessible when the ruleset matches.
33+
- Scopes: The permissions granted.
34+
35+
You can define 1 to 5 rulesets per connection. These rulesets let you tailor access to the minimum required for each workflow.
36+
37+
> [!IMPORTANT]
38+
>
39+
> If multiple rulesets match an incoming token, Docker merges the resources across those rulesets and grants access to all of them.
40+
41+
### Subject claims
42+
43+
A subject claim is a string in the OIDC token that identifies the source workflow. It typically follows this format:
44+
45+
```PHP
46+
repo:<org>/<repo>:ref:refs/heads/<branch>
47+
```
48+
49+
For example, a subject claim could be: `repo:octo-org/octo-repo:ref:refs/heads/main`.
50+
51+
You can use wildcards (`*` and `?`) to match multiple repositories or branches.
52+
For example:
53+
54+
- `repo:my-org/my-repo:ref:refs/heads/main`: only the `main` branch
55+
- `repo:my-org/*`: all repos in the org
56+
- `repo:*:ref:refs/heads/release-*`: all branches starting with `release-`
57+
58+
See [GitHub’s example subject claims](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect#example-subject-claims) for more formats.
59+
60+
## Create an OIDC connection
61+
62+
To let GitHub Actions workflows authenticate with Docker Hub, create an OIDC connection and define one or more rulesets.
63+
64+
1. Sign in to the [Admin Console](https://app.docker.com/admin) and select your organization.
65+
2. In the left sidebar, go to **Security and access** > **OIDC connections**.
66+
3. Select **Create new OIDC connection**.
67+
4. Enter a **Connection name**.
68+
5. Optional. Add a **description**.
69+
6. Under **Connection type**, select **GitHub Actions**.
70+
7. Select **Add ruleset**, then:
71+
- Enter a **label**.
72+
- Enter a **subject claim**.
73+
- Select the Docker Hub repositories or Docker Cloud resources to allow access.
74+
8. Select **Next** and review the configuration.
75+
9. Select **Confirm**, then **Create OIDC connection**.
76+
77+
## Configure your GitHub Actions workflow
78+
79+
After setting up the connection and ruleset, update your workflow to use GitHub OIDC.
80+
81+
### Step 1: Request an OIDC token
82+
83+
```yaml
84+
permissions:
85+
id-token: write
86+
```
87+
88+
### Step 2: Exchange the OIDC token for a Docker access token
89+
90+
```yaml
91+
jobs:
92+
login:
93+
runs-on: ubuntu-latest
94+
steps:
95+
- name: Docker OIDC
96+
id: docker_oidc
97+
uses: docker/configure-credentials-action
98+
with:
99+
connection_id: 77537984-f27a-45c5-9b4c-f20b3f88817e
100+
```
101+
102+
### Use the access token
103+
104+
With Docker CLI:
105+
106+
```yaml
107+
- name: Login to Docker Hub
108+
uses: docker/login-action@v3
109+
with:
110+
username: docker # must match your Docker organization name
111+
password: ${{ steps.docker_oidc.outputs.token }}
112+
```
113+
114+
With Docker Hub API:
115+
116+
```yaml
117+
- name: List members of the org
118+
run: |
119+
curl \
120+
-H "Authorization: Bearer ${{ steps.docker_oidc.outputs.token }}" \
121+
https://hub.docker.com/v2/orgs/${ORG_ID}/members
122+
```
123+
124+
## Manage OIDC connections
125+
126+
After creating a connection, you can copy its ID, edit its details, or manage access based on your organization’s needs.
127+
128+
### Copy connection ID
129+
130+
You’ll need the connection ID to configure your workflows.
131+
132+
1. Sign in to the [Admin Console](https://app.docker.com/admin) and select your organization.
133+
2. Go to **Security and access** > **OIDC connections**.
134+
3. Select the **Actions menu**, then **Edit**.
135+
4. Copy the value in the Connection ID field.
136+
137+
### Edit a connection
138+
139+
You can edit a connection to rename the connection, update rulesets, or modify resources.
140+
141+
1. Sign in to the [Admin Console](https://app.docker.com/admin) and select your organization.
142+
2. In **Security and access**, select **OIDC connections**.
143+
3. Select the **Actions menu icon**, then **Edit**.
144+
4. You can:
145+
- Update connection name or description
146+
- Edit or remove rulesets
147+
- Add new rulesets
148+
- Update resources inside rulesets
149+
150+
### Deactivate a connection
151+
152+
You can deactivate a connection if you want to temporarily disable access or are rotating credentials and want to pause workflow authorization.
153+
154+
1. Sign in to the [Admin Console](https://app.docker.com/admin) and select your organization.
155+
2. In **Security and access**, select **OIDC connections**.
156+
3. Select the **Actions menu icon**, then **Deactivate**.
157+
158+
### Delete a connection
159+
160+
Delete a connection if it’s no longer needed or to clean up unused or outdated rulesets.
161+
162+
1. Sign in to the [Admin Console](https://app.docker.com/admin) and select your organization.
163+
2. In **Security and access**, select **OIDC connections**.
164+
3. Select the **Actions menu icon**, then **Delete**.

‎data/summary.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,9 @@ MSI installer:
195195
for: Administrators
196196
OATs:
197197
subscription: [Team, Business]
198+
OIDC connections:
199+
availability: Beta
200+
for: Administrators
198201
PKG installer:
199202
subscription: [Business]
200203
requires: Docker Desktop [4.36](/manuals/desktop/release-notes.md#4360) and later

0 commit comments

Comments
 (0)