Share feedback
Answers are generated based on the documentation.

Create and manage OIDC connections

Table of contents
Subscription: Team Business
For: Administrators

Organization owners and editors create and manage OIDC connections from OIDC connections in Docker Home. After you create a connection, configure your GitHub Actions workflow so it can sign in to Docker Hub with a short-lived token.

Note

OIDC connections support only GitHub as a trusted third party. GitHub Enterprise Cloud (GHEC) and GitHub Enterprise Server (GHES) are not supported.

Create an OIDC connection

  1. Sign in to Docker Home, select your organization, then go to Identity & auth.
  2. Select OIDC connections.
  3. Select Create OIDC connection and fill in the form.
  4. Select Create connection.
  5. Copy your OIDC connection ID.

Configure a GitHub Actions workflow

Use docker/login-action version 4.5.0 or later. The action exchanges the GitHub OIDC token and signs in to Docker Hub in a single step.

  1. Add the following to your workflow YAML. Replace <YOUR_ORG_NAME> with your Docker organization name and <YOUR_CONNECTION_ID> with the ID you copied from Docker Home:

    permissions:
  contents: read
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Docker login
        uses: docker/login-action@v4 # v4.5.0+
        with:
          username: <YOUR_ORG_NAME>
        env:
          DOCKERHUB_OIDC_CONNECTIONID: <YOUR_CONNECTION_ID>

    The username value must be a Docker organization name. Only organization accounts can sign in using OIDC.

  2. Run the workflow and confirm it can sign in to Docker.

Manage OIDC connections

You can view, edit, deactivate, or delete connections from the OIDC connections page.

  1. Select Identity & auth, then OIDC connections.
  2. Find the row with your target connection ID.
  3. Select the action menu icon for your options.
    • Edit opens the Edit OIDC connection page where you can copy your connection ID, update rulesets, or open the Failures tab. See View connection failures.
    • Deactivate temporarily disables access to your GitHub workflow.
    • Activate restores access to your GitHub workflow.
    • Delete permanently deletes a connection.

Deactivate or delete a connection

Deactivate an OIDC connection to pause GitHub workflow access to your Docker resources without deleting the connection. A deactivated connection does not issue Docker access tokens, so docker/login-action fails at the token-exchange step until you activate the connection.

Warning

Deleting an OIDC connection is permanent. Any workflow that still sets DOCKERHUB_OIDC_CONNECTIONID to the deleted ID fails at the token-exchange step. Update that environment variable with a replacement connection ID in every affected workflow before it runs again.

View connection failures

Docker records a failure when a workflow reaches the token-exchange step for your connection and no ruleset matches the token's claims. For GitHub Actions, Docker only logs the failure when the token's repository namespace matches a namespace in a sub rule on the connection. An unrelated repository can still receive access denied without a Failures row.

  1. Sign in to Docker Home, select your organization, then go to Identity & auth.
  2. Select OIDC connections.
  3. Find the connection, open the action menu, and select Edit.
  4. On the Edit OIDC connection page, select the Failures tab.

The Failures tab is view-only. It lists past failed exchanges so you can compare claims to rulesets. It does not run a test or accept inputs.

If Docker has not recorded any failures for the connection, the tab shows No failures have been reported for this connection.

Note

Wrong connection IDs, deactivated connections, and token problems that fail before claim matching do not appear on Failures. See Troubleshoot OIDC connections.

Read a failure entry

Each failure row includes:

  • The date and time of the failed exchange
  • The ruleset rule that did not match, shown as claim = expected value (for example, sub = repo:my-org/my-repo:ref:refs/heads/main)
  • The incoming claim value from the GitHub ID token, marked with ❌ when it does not match

To inspect every claim in the token, expand Show all claims. The expanded table lists Incoming claim and Value. Claims that failed validation appear with ❌.

Use the unmatched expected value and the incoming value together to decide whether to update the ruleset or the workflow that produced the token.

Next steps