From 411ad2282fe35419e08f6a67d0543e1f71ee35b6 Mon Sep 17 00:00:00 2001 From: Greg Mondello <72952982+gmondello@users.noreply.github.com> Date: Tue, 21 Jul 2026 16:28:23 -0500 Subject: [PATCH 1/5] 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. --- .../security-harden-deployments/index.md | 1 + .../oidc-in-docker.md | 123 ++++++++++++++++++ 2 files changed, 124 insertions(+) create mode 100644 content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md diff --git a/content/actions/how-tos/secure-your-work/security-harden-deployments/index.md b/content/actions/how-tos/secure-your-work/security-harden-deployments/index.md index 77ef5ef2a711..3d072238b1e0 100644 --- a/content/actions/how-tos/secure-your-work/security-harden-deployments/index.md +++ b/content/actions/how-tos/secure-your-work/security-harden-deployments/index.md @@ -13,6 +13,7 @@ versions: children: - /oidc-in-aws - /oidc-in-azure + - /oidc-in-docker - /oidc-in-google-cloud-platform - /oidc-in-hashicorp-vault - /oidc-in-jfrog diff --git a/content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md b/content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md new file mode 100644 index 000000000000..51b70b165731 --- /dev/null +++ b/content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md @@ -0,0 +1,123 @@ +--- +title: Configuring OpenID Connect in Docker +shortTitle: OIDC in Docker +intro: Use OpenID Connect within your workflows to authenticate with Docker Hub without storing long-lived credentials. +versions: + fpt: '*' + ghec: '*' +contentType: how-tos +category: + - Secure your workflows +--- + +## Overview + +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 %}. + +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. + +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. + +For more information, see [OIDC connections](https://docs.docker.com/enterprise/security/oidc-connections/) in the Docker documentation. + +## Prerequisites + +{% data reusables.actions.oidc-link-to-intro %} + +{% data reusables.actions.oidc-security-notice %} + +{% data reusables.actions.oidc-on-ghecom %} + +* You must have a Docker Business or Docker Team subscription. +* You must be an organization owner or editor in your Docker organization. +* 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. + +## Adding the identity provider to Docker Hub + +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. + +1. Sign in to [Docker Home](https://app.docker.com/) and navigate to your organization. +1. Go to **Identity & auth** > **OIDC connections**. +1. Select **Create OIDC connection**. +1. Configure at least one ruleset to define which GitHub repositories, branches, or workflows can authenticate. Each ruleset specifies: + * **Rules**: Conditions matched against OIDC token claims (repository, branch, workflow path). Wildcard patterns like `repo:my-org/*` are supported. + * **Resources**: Docker Hub repositories or Docker Build Cloud projects the workflow can access. + * **Scopes**: Permission levels (`read`, `write`). +1. Save the connection and copy the **connection ID** for use in your workflow. + +## Updating your {% data variables.product.prodname_actions %} workflow + +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. + +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. + +```yaml +name: Build and push with OIDC + +on: + push: + branches: [main] + +permissions: + id-token: write + contents: read + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Get Docker OIDC token + id: docker-oidc + uses: docker/oidc-action@v1 + with: + connection_id: YOUR_CONNECTION_ID + + - name: Sign in to Docker Hub + uses: docker/login-action@v4 + with: + username: YOUR_DOCKER_ORG + password: {% raw %}${{ steps.docker-oidc.outputs.token }}{% endraw %} + + - name: Build and push + uses: docker/build-push-action@v6 + with: + push: true + tags: YOUR_DOCKER_ORG/my-image:latest +``` + +### Key workflow settings + +* **`permissions.id-token: write`** is required so that {% data variables.product.prodname_dotcom %} can issue an OIDC token for the workflow. +* 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. +* The `docker/login-action` uses the token output to authenticate with Docker Hub. The `username` field should be your Docker organization name. + +### Subject claim matching + +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: + +```text +repo:/:ref:refs/heads/ +``` + +Different workflow triggers produce different subject claims. For example: + +| Trigger | Subject claim format | +|---------|---------------------| +| Branch push | `repo:my-org/my-repo:ref:refs/heads/main` | +| Pull request | `repo:my-org/my-repo:pull_request` | +| Tag | `repo:my-org/my-repo:ref:refs/tags/v1.0` | +| Environment | `repo:my-org/my-repo:environment:production` | + +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. + +For more information, see [Rulesets and subject claims](https://docs.docker.com/enterprise/security/oidc-connections/rulesets-claims/) in the Docker documentation. + +## Further reading + +* [OIDC connections overview](https://docs.docker.com/enterprise/security/oidc-connections/) in the Docker documentation +* [Create and manage OIDC connections](https://docs.docker.com/enterprise/security/oidc-connections/create-manage/) in the Docker documentation +* [Rulesets and subject claims](https://docs.docker.com/enterprise/security/oidc-connections/rulesets-claims/) in the Docker documentation +* [AUTOTITLE](/actions/concepts/security/openid-connect) From 1791b9b26026190ee4233beae72b97a785ca5974 Mon Sep 17 00:00:00 2001 From: Greg Mondello <72952982+gmondello@users.noreply.github.com> Date: Tue, 21 Jul 2026 17:34:01 -0500 Subject: [PATCH 2/5] Use immutable SHA refs for all GitHub Actions in workflow example --- .../security-harden-deployments/oidc-in-docker.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md b/content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md index 51b70b165731..a258f5b57784 100644 --- a/content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md +++ b/content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md @@ -71,18 +71,18 @@ jobs: - name: Get Docker OIDC token id: docker-oidc - uses: docker/oidc-action@v1 + uses: docker/oidc-action@3f002d200df5620744c973221788e401898c6f86 # v1.0.0 with: connection_id: YOUR_CONNECTION_ID - name: Sign in to Docker Hub - uses: docker/login-action@v4 + uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0 with: username: YOUR_DOCKER_ORG password: {% raw %}${{ steps.docker-oidc.outputs.token }}{% endraw %} - name: Build and push - uses: docker/build-push-action@v6 + uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6 with: push: true tags: YOUR_DOCKER_ORG/my-image:latest From 6559ae5d698ca31a30a4bf66c84f6d1000fbc502 Mon Sep 17 00:00:00 2001 From: Greg Mondello <72952982+gmondello@users.noreply.github.com> Date: Tue, 21 Jul 2026 17:41:30 -0500 Subject: [PATCH 3/5] Address all Copilot review feedback - Use Liquid variables instead of hardcoded product names - Add third-party actions disclaimer reusable to workflow example - Use action-checkout reusable for actions/checkout - Add note about immutable subject claim format (post July 15 2026) - Remove duplicate external links per style guide - Pin version comments to major version only (v1, v4, v6) --- .../oidc-in-docker.md | 23 ++++++++----------- 1 file changed, 9 insertions(+), 14 deletions(-) diff --git a/content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md b/content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md index a258f5b57784..da4ddaae01b1 100644 --- a/content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md +++ b/content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md @@ -30,7 +30,7 @@ For more information, see [OIDC connections](https://docs.docker.com/enterprise/ * You must have a Docker Business or Docker Team subscription. * You must be an organization owner or editor in your Docker organization. -* 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. +* You should plan which repositories, branches, and workflows need access to Docker Hub, and configure rulesets accordingly. ## Adding the identity provider to Docker Hub @@ -39,7 +39,7 @@ To use OIDC with Docker, establish a trust relationship between {% data variable 1. Sign in to [Docker Home](https://app.docker.com/) and navigate to your organization. 1. Go to **Identity & auth** > **OIDC connections**. 1. Select **Create OIDC connection**. -1. Configure at least one ruleset to define which GitHub repositories, branches, or workflows can authenticate. Each ruleset specifies: +1. Configure at least one ruleset to define which {% data variables.product.prodname_dotcom %} repositories, branches, or workflows can authenticate. Each ruleset specifies: * **Rules**: Conditions matched against OIDC token claims (repository, branch, workflow path). Wildcard patterns like `repo:my-org/*` are supported. * **Resources**: Docker Hub repositories or Docker Build Cloud projects the workflow can access. * **Scopes**: Permission levels (`read`, `write`). @@ -52,12 +52,7 @@ Once you have created an OIDC connection in Docker Hub, update your workflow to 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. ```yaml -name: Build and push with OIDC - -on: - push: - branches: [main] - +{% data reusables.actions.actions-not-certified-by-github-comment %} permissions: id-token: write contents: read @@ -67,16 +62,16 @@ jobs: runs-on: ubuntu-latest steps: - name: Check out repository - uses: actions/checkout@v4 + uses: {% data reusables.actions.action-checkout %} - name: Get Docker OIDC token id: docker-oidc - uses: docker/oidc-action@3f002d200df5620744c973221788e401898c6f86 # v1.0.0 + uses: docker/oidc-action@3f002d200df5620744c973221788e401898c6f86 # v1 with: connection_id: YOUR_CONNECTION_ID - name: Sign in to Docker Hub - uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0 + uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4 with: username: YOUR_DOCKER_ORG password: {% raw %}${{ steps.docker-oidc.outputs.token }}{% endraw %} @@ -102,6 +97,9 @@ Docker evaluates the `sub` claim from the {% data variables.product.prodname_dot repo:/:ref:refs/heads/ ``` +> [!NOTE] +> Repositories created or renamed after July 15, 2026 use immutable owner and repository identifiers in the subject claim, for example: `repo:octocat@123456/my-repo@456789:ref:refs/heads/main`. For more information, see [AUTOTITLE](/actions/concepts/security/openid-connect). + Different workflow triggers produce different subject claims. For example: | Trigger | Subject claim format | @@ -117,7 +115,4 @@ For more information, see [Rulesets and subject claims](https://docs.docker.com/ ## Further reading -* [OIDC connections overview](https://docs.docker.com/enterprise/security/oidc-connections/) in the Docker documentation -* [Create and manage OIDC connections](https://docs.docker.com/enterprise/security/oidc-connections/create-manage/) in the Docker documentation -* [Rulesets and subject claims](https://docs.docker.com/enterprise/security/oidc-connections/rulesets-claims/) in the Docker documentation * [AUTOTITLE](/actions/concepts/security/openid-connect) From bc657adbdd9bc039ab4affe14818c4c03e0264d5 Mon Sep 17 00:00:00 2001 From: Greg Mondello <72952982+gmondello@users.noreply.github.com> Date: Wed, 22 Jul 2026 08:22:22 -0500 Subject: [PATCH 4/5] Replace literal 'personal access tokens' with Liquid variable --- .../security-harden-deployments/oidc-in-docker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md b/content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md index da4ddaae01b1..ceab49e2bab1 100644 --- a/content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md +++ b/content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md @@ -12,7 +12,7 @@ category: ## Overview -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 %}. +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, {% data variables.product.pat_generic_plural %}, or organization access tokens (OATs) in {% data variables.product.company_short %}. 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. From 18f1857cf48841808780b2becbafd08df6934cd5 Mon Sep 17 00:00:00 2001 From: Greg Mondello <72952982+gmondello@users.noreply.github.com> Date: Wed, 22 Jul 2026 14:02:36 -0500 Subject: [PATCH 5/5] Replace Docker Hub with Docker where scope is broader than registry OIDC connections scope access to Docker Hub and Docker Build Cloud, not just Docker Hub. Keep Docker Hub only where specifically referring to registry operations. --- .../oidc-in-docker.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md b/content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md index ceab49e2bab1..9259b63f7068 100644 --- a/content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md +++ b/content/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-docker.md @@ -1,7 +1,7 @@ --- title: Configuring OpenID Connect in Docker shortTitle: OIDC in Docker -intro: Use OpenID Connect within your workflows to authenticate with Docker Hub without storing long-lived credentials. +intro: Use OpenID Connect within your workflows to authenticate with Docker without storing long-lived credentials. versions: fpt: '*' ghec: '*' @@ -12,11 +12,11 @@ category: ## Overview -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, {% data variables.product.pat_generic_plural %}, or organization access tokens (OATs) in {% data variables.product.company_short %}. +OpenID Connect (OIDC) allows your {% data variables.product.prodname_actions %} workflows to authenticate with [Docker](https://www.docker.com/) to access Docker Hub and Docker Build Cloud without storing Docker passwords, {% data variables.product.pat_generic_plural %}, or organization access tokens (OATs) in {% data variables.product.company_short %}. 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. -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. +This guide gives an overview of how to configure Docker 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. For more information, see [OIDC connections](https://docs.docker.com/enterprise/security/oidc-connections/) in the Docker documentation. @@ -30,11 +30,11 @@ For more information, see [OIDC connections](https://docs.docker.com/enterprise/ * You must have a Docker Business or Docker Team subscription. * You must be an organization owner or editor in your Docker organization. -* You should plan which repositories, branches, and workflows need access to Docker Hub, and configure rulesets accordingly. +* You should plan which repositories, branches, and workflows need access to Docker, and configure rulesets accordingly. -## Adding the identity provider to Docker Hub +## Adding the identity provider to Docker -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. +To use OIDC with Docker, establish a trust relationship between {% data variables.product.prodname_actions %} and Docker 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. 1. Sign in to [Docker Home](https://app.docker.com/) and navigate to your organization. 1. Go to **Identity & auth** > **OIDC connections**. @@ -47,9 +47,9 @@ To use OIDC with Docker, establish a trust relationship between {% data variable ## Updating your {% data variables.product.prodname_actions %} workflow -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. +Once you have created an OIDC connection in Docker, 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. -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. +The following example uses the placeholder `YOUR_CONNECTION_ID` for the connection ID you copied from Docker, and `YOUR_DOCKER_ORG` for your Docker organization name. ```yaml {% data reusables.actions.actions-not-certified-by-github-comment %}