Skip to content

Commit 411ad22

Browse files
gmondellogmondello
committed
Add OIDC in Docker guide for GitHub Actions deployments
Adds a new guide for configuring OpenID Connect between GitHub Actions and Docker Hub, following the same format as existing provider guides (AWS, Azure, GCP, JFrog, etc.). Docker Hub OIDC connections let workflows authenticate using short-lived tokens instead of long-lived PATs or OATs. The guide covers creating a connection in Docker Hub, configuring rulesets for claim matching, and a complete workflow example using docker/oidc-action and docker/login-action.
1 parent 7b5b3c9 commit 411ad22

2 files changed

Lines changed: 124 additions & 0 deletions

File tree

‎content/actions/how-tos/secure-your-work/security-harden-deployments/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ versions:
1313
children:
1414
- /oidc-in-aws
1515
- /oidc-in-azure
16+
- /oidc-in-docker
1617
- /oidc-in-google-cloud-platform
1718
- /oidc-in-hashicorp-vault
1819
- /oidc-in-jfrog

‎content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
title: Configuring OpenID Connect in Docker
3+
shortTitle: OIDC in Docker
4+
intro: Use OpenID Connect within your workflows to authenticate with Docker Hub without storing long-lived credentials.
5+
versions:
6+
fpt: '*'
7+
ghec: '*'
8+
contentType: how-tos
9+
category:
10+
- Secure your workflows
11+
---
12+
13+
## Overview
14+
15+
OpenID Connect (OIDC) allows your {% data variables.product.prodname_actions %} workflows to authenticate with [Docker Hub](https://hub.docker.com/) to push and pull container images without storing Docker passwords, personal access tokens (PATs), or organization access tokens (OATs) in {% data variables.product.company_short %}.
16+
17+
Instead of managing long-lived credentials, you configure a trust relationship between your {% data variables.product.prodname_dotcom %} organization and your Docker organization. When a workflow runs, {% data variables.product.prodname_dotcom %} issues a short-lived OIDC token that Docker validates against your configured rulesets, then issues a scoped access token for the workflow.
18+
19+
This guide gives an overview of how to configure Docker Hub to trust {% data variables.product.prodname_dotcom %}'s OIDC as a federated identity, and demonstrates how to use this configuration in a {% data variables.product.prodname_actions %} workflow.
20+
21+
For more information, see [OIDC connections](https://docs.docker.com/enterprise/security/oidc-connections/) in the Docker documentation.
22+
23+
## Prerequisites
24+
25+
{% data reusables.actions.oidc-link-to-intro %}
26+
27+
{% data reusables.actions.oidc-security-notice %}
28+
29+
{% data reusables.actions.oidc-on-ghecom %}
30+
31+
* You must have a Docker Business or Docker Team subscription.
32+
* You must be an organization owner or editor in your Docker organization.
33+
* You should plan which repositories, branches, and workflows need access to Docker Hub, and configure rulesets accordingly. For more information, see [Rulesets and subject claims](https://docs.docker.com/enterprise/security/oidc-connections/rulesets-claims/) in the Docker documentation.
34+
35+
## Adding the identity provider to Docker Hub
36+
37+
To use OIDC with Docker, establish a trust relationship between {% data variables.product.prodname_actions %} and Docker Hub by creating an OIDC connection. For more information about this process, see [Create and manage OIDC connections](https://docs.docker.com/enterprise/security/oidc-connections/create-manage/) in the Docker documentation.
38+
39+
1. Sign in to [Docker Home](https://app.docker.com/) and navigate to your organization.
40+
1. Go to **Identity & auth** > **OIDC connections**.
41+
1. Select **Create OIDC connection**.
42+
1. Configure at least one ruleset to define which GitHub repositories, branches, or workflows can authenticate. Each ruleset specifies:
43+
* **Rules**: Conditions matched against OIDC token claims (repository, branch, workflow path). Wildcard patterns like `repo:my-org/*` are supported.
44+
* **Resources**: Docker Hub repositories or Docker Build Cloud projects the workflow can access.
45+
* **Scopes**: Permission levels (`read`, `write`).
46+
1. Save the connection and copy the **connection ID** for use in your workflow.
47+
48+
## Updating your {% data variables.product.prodname_actions %} workflow
49+
50+
Once you have created an OIDC connection in Docker Hub, update your workflow to authenticate using the [`docker/oidc-action`](https://github.com/docker/oidc-action) and [`docker/login-action`](https://github.com/docker/login-action) actions.
51+
52+
The following example uses the placeholder `YOUR_CONNECTION_ID` for the connection ID you copied from Docker Hub, and `YOUR_DOCKER_ORG` for your Docker organization name.
53+
54+
```yaml
55+
name: Build and push with OIDC
56+
57+
on:
58+
push:
59+
branches: [main]
60+
61+
permissions:
62+
id-token: write
63+
contents: read
64+
65+
jobs:
66+
build:
67+
runs-on: ubuntu-latest
68+
steps:
69+
- name: Check out repository
70+
uses: actions/checkout@v4
71+
72+
- name: Get Docker OIDC token
73+
id: docker-oidc
74+
uses: docker/oidc-action@v1
75+
with:
76+
connection_id: YOUR_CONNECTION_ID
77+
78+
- name: Sign in to Docker Hub
79+
uses: docker/login-action@v4
80+
with:
81+
username: YOUR_DOCKER_ORG
82+
password: {% raw %}${{ steps.docker-oidc.outputs.token }}{% endraw %}
83+
84+
- name: Build and push
85+
uses: docker/build-push-action@v6
86+
with:
87+
push: true
88+
tags: YOUR_DOCKER_ORG/my-image:latest
89+
```
90+
91+
### Key workflow settings
92+
93+
* **`permissions.id-token: write`** is required so that {% data variables.product.prodname_dotcom %} can issue an OIDC token for the workflow.
94+
* The `docker/oidc-action` exchanges the {% data variables.product.prodname_dotcom %} OIDC token for a short-lived Docker access token based on your connection's rulesets.
95+
* The `docker/login-action` uses the token output to authenticate with Docker Hub. The `username` field should be your Docker organization name.
96+
97+
### Subject claim matching
98+
99+
Docker evaluates the `sub` claim from the {% data variables.product.prodname_dotcom %} OIDC token against the rulesets you configured. The default subject claim format is:
100+
101+
```text
102+
repo:<owner>/<repo>:ref:refs/heads/<branch>
103+
```
104+
105+
Different workflow triggers produce different subject claims. For example:
106+
107+
| Trigger | Subject claim format |
108+
|---------|---------------------|
109+
| Branch push | `repo:my-org/my-repo:ref:refs/heads/main` |
110+
| Pull request | `repo:my-org/my-repo:pull_request` |
111+
| Tag | `repo:my-org/my-repo:ref:refs/tags/v1.0` |
112+
| Environment | `repo:my-org/my-repo:environment:production` |
113+
114+
You can use wildcard patterns in your rulesets to match multiple repositories or branches. For example, `repo:my-org/*` matches all repositories in your organization.
115+
116+
For more information, see [Rulesets and subject claims](https://docs.docker.com/enterprise/security/oidc-connections/rulesets-claims/) in the Docker documentation.
117+
118+
## Further reading
119+
120+
* [OIDC connections overview](https://docs.docker.com/enterprise/security/oidc-connections/) in the Docker documentation
121+
* [Create and manage OIDC connections](https://docs.docker.com/enterprise/security/oidc-connections/create-manage/) in the Docker documentation
122+
* [Rulesets and subject claims](https://docs.docker.com/enterprise/security/oidc-connections/rulesets-claims/) in the Docker documentation
123+
* [AUTOTITLE](/actions/concepts/security/openid-connect)

0 commit comments

Comments
 (0)