oidc-in-docker.md

title	Configuring OpenID Connect in Docker
shortTitle	OIDC in Docker
intro	Use OpenID Connect within your workflows to authenticate with Docker 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 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 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 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 must plan which repositories, branches, and workflows need access to Docker, and configure rulesets accordingly.

Adding the identity provider to Docker

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 in the Docker documentation.

1. Sign in to Docker Home and navigate to your organization.
2. Go to Identity & auth > OIDC connections.
3. Select Create OIDC connection.
4. 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).
5. 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, update your workflow to authenticate using the docker/login-action action.

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.

{% data reusables.actions.actions-not-certified-by-github-comment %}
permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: {% data reusables.actions.action-checkout %}

      - name: Sign in to Docker Hub with OIDC
        uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4.5.1
        with:
          username: YOUR_DOCKER_ORG
        env:
          DOCKERHUB_OIDC_CONNECTIONID: YOUR_CONNECTION_ID

      - name: Build and push
        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # 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/login-action handles the OIDC token exchange and Docker login in a single step when DOCKERHUB_OIDC_CONNECTIONID is set and password is omitted.
• The username field should be your Docker organization name.

Using the token as an output

If your workflow needs the Docker access token as a separate output (for example, for API calls or custom authentication flows), use docker/oidc-action to perform the token exchange explicitly:

{% data reusables.actions.actions-not-certified-by-github-comment %}
permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Get Docker OIDC token
        id: docker-oidc
        uses: docker/oidc-action@3f002d200df5620744c973221788e401898c6f86 # v1
        with:
          connection_id: YOUR_CONNECTION_ID

      - name: Sign in to Docker Hub
        uses: docker/login-action@abd2ef45e78c5afb21d64d4ca52ee8550d9572c7 # v4.5.1
        with:
          username: YOUR_DOCKER_ORG
          password: {% raw %}${{ steps.docker-oidc.outputs.token }}{% endraw %}

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:

repo:<owner>/<repo>:ref:refs/heads/<branch>

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.

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 in the Docker documentation.

Further reading

• AUTOTITLE