Create and manage OIDC connections

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.

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 OIDC connection form.
   • Provide rulesets and subject claims. Other values are optional.
   • For rulesets, subject claims, and resources, see OIDC connections rulesets and subject claims.
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 view the Failures table.
   • 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.

Next steps

• OIDC connections rulesets and subject claims