Create and manage OIDC connections

Organization owners and editors can create OIDC connections or manage existing ones from OIDC connections in Docker Home. Establishing an OIDC connection occurs in two phases. First, you create the OIDC connection in Docker Home, then you configure your GitHub Actions workflow YAML file.

Note

OIDC connections support only GitHub as a trusted third party.

Set up GitHub Actions authentication

Step 1: Create the 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.
   • You must 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.

Step 2: Define the GitHub Actions workflow

1. Add a top-level permissions key that requests a GitHub OIDC ID token:

   permissions:
     id-token: write

2. Define a job that triggers the OIDC exchange. Update connection_id with the connection ID you copied from Docker:

   jobs:
     login:
       runs-on: ubuntu-latest
       steps:
         - name: OIDC connections
           id: docker_oidc
           uses: docker/oidc-action@v1
           with:
             connection_id: <YOUR_CONNECTION_ID>

3. Add a step that signs in to Docker with an access token once the ID token passes authentication:

   - name: Sign in to Docker Hub
     uses: docker/login-action@v4
     with:
       username: <DOCKER_ORGANIZATION_NAME>
       password: ${{ steps.docker_oidc.outputs.token }}

   The username value must be an organization name. Personal accounts aren't supported.

   Your updated workflow YAML should look like this:

   permissions:
     id-token: write
   
   jobs:
     login:
       runs-on: ubuntu-latest
       steps:
         - name: OIDC connections
           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_ORGANIZATION_NAME>
             password: ${{ steps.docker_oidc.outputs.token }}

4. Run your GitHub Action and verify the workflow can sign in to Docker.

Manage OIDC connections

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

1. From Identity & auth, go to OIDC connections.
2. From the OIDC connections page, 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.

Deactivation and deletion

You can deactivate an OIDC connection to pause GitHub workflow access to your Docker resources without deleting the connection. While a connection is deactivated:

• It can't issue Docker access tokens.
• Without Docker access tokens, docker/oidc-action fails at the token-exchange step until you activate the connection.

Unlike deactivation, deleting an OIDC connection is permanent. Any workflow whose docker/oidc-action step still references the deleted connection_id fails at the token-exchange step. Update that input with a replacement connection's ID in every affected workflow before it runs again.

What's next

• OIDC connections rulesets and subject claims