Docker での OpenID Connect の構成

ワークフロー内で OpenID Connect を使用して、有効期間の長い認証情報を格納せずに Docker で認証します。

この記事で

Overview

OpenID Connect (OIDC) を使用すると、GitHub Actions ワークフローは Docker を使用して認証を行い、docker パスワード、personal access tokens、または組織アクセストークン（OAT）をGitHubに格納せずに、Docker Hubおよび Docker Build Cloud にアクセスできます。

有効期間の長い資格情報を管理する代わりに、あなたの GitHub 組織と Docker 組織の間に信頼関係を構成します。 ワークフローを実行すると、GitHub は、構成されたルールセットに対して Docker が検証する有効期間の短い OIDC トークンを発行し、その後 Docker がワークフロー用のスコープ付きアクセストークンを発行します。

このガイドでは、Docker が GitHub の OIDC をフェデレーション ID として信頼するように構成する方法の概要を示し、さらにこの構成を GitHub Actions ワークフローで使用する方法を説明します。

詳細については、Docker ドキュメントの OIDC 接続 を参照してください。

Prerequisites

  • GitHubで OpenID Connect (OIDC) を使用する方法の基本的な概念とそのアーキテクチャと利点については、OpenID Connect を参照してください。

  • 先に進む前に、アクセス トークンが予測可能な方法でのみ割り当てられるようにセキュリティ戦略を計画する必要があります。 クラウド プロバイダーがアクセス トークンを発行する方法を制御するには、少なくとも 1 つの条件を定義し、信頼できないリポジトリがクラウド リソースにアクセス トークンを要求できないようにする必要があります。 詳細については、「 OpenID Connect リファレンス」を参照してください。

  • Dependabot 更新ジョブ用に要求される OIDC トークンの dynamic クレームは event_name です。 信頼ポリシーが GitHub Actions ワークフローのみを承認することを目的としており、クラウド プロバイダーが event_nameの条件をサポートしている場合は、ワークフローで予期されるイベント名のみを許可します。 詳細については、「 OpenID Connect リファレンス」を参照してください。

  • Docker 組織は、Docker Business、Docker Team、または Docker Hardened Images を使用するか、Docker Sponsored Open Source Program に登録する必要があります。

  • Docker 組織の組織の所有者またはエディターである必要があります。

  • どのリポジトリ、ブランチ、ワークフローに Docker へのアクセスが必要かを見極め、それに応じてルールセットを構成する必要があります。

Docker への ID プロバイダーの追加

Docker で OIDC を使用するには、OIDC 接続を作成して、 GitHub Actions と Docker の間に信頼関係を確立します。 このプロセスの詳細については、Docker ドキュメントの OIDC 接続の作成と管理 を参照してください。

  1. Docker Home にサインインし、組織に移動します。
  2. ID と認証 > OIDC 接続に移動します。
  3. [OIDC 接続の作成] を選択します。
  4. どの GitHub リポジトリ、ブランチ、またはワークフローが認証できるかを定義するように、少なくとも 1 つのルール セットを構成します。 各ルールセットは次を指定します。
    • ルール: OIDC トークン クレーム (リポジトリ、ブランチ、ワークフロー パス) と一致する条件。 repo:my-org/*などのワイルドカード パターンがサポートされています。
    • リソース: ワークフローがアクセスできる Docker Hub リポジトリまたは Docker Build Cloud プロジェクト。
    • スコープ: アクセス許可レベル (read、 write)。
  5. 接続を保存し、ワークフローで使用する 接続 ID をコピーしてください。

GitHub Actions ワークフローの更新

Docker で OIDC 接続を作成したら、認証に docker/login-action アクションを使用するようにワークフローを更新します。

次の例では、Docker からコピーした接続 ID にはプレースホルダー YOUR-CONNECTION-ID を使用し、Docker 組織名には YOUR-DOCKER-ORG を使用します。

# このワークフローはGitHubによって認定されていないアクションを使用します。
# それらはサードパーティによって提供され、
# 別個の利用規約、プライバシーポリシー、
# ドキュメントを参照してください。
permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - 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

主要ワークフロー設定

  • permissions.id-token: write は、 GitHub がワークフローの OIDC トークンを発行できるようにするために必要です。
  • passwordが設定され、docker/login-actionを省略すると、DOCKERHUB_OIDC_CONNECTIONIDは OIDC トークン交換と Docker ログインを 1 つのステップで処理します。
  • username フィールドは、Docker organization名である必要があります。

サブジェクト クレーム照合

Docker は、GitHub OIDC トークンからのsubクレームを、構成したルールセットに照らして評価します。 既定のサブジェクト クレーム形式は次のとおりです。

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

メモ

2026 年 7 月 15 日以降に作成されたリポジトリと、その日以降に名前変更または移管されたリポジトリでは、所有者 ID とリポジトリ ID を含む不変の既定の OIDC sub クレームを使用します。 既存のリポジトリは、オプトインしない限り、以前の形式を保持します。 詳細については、「OpenID Connect リファレンス」を参照してください。

ワークフロー トリガーが異なると、異なるサブジェクト クレームが生成されます。 例えば次が挙げられます。

Triggerサブジェクト クレームの形式
ブランチをプッシュrepo:my-org/my-repo:ref:refs/heads/main
Pull request（プルリクエスト）repo:my-org/my-repo:pull_request
タグrepo:my-org/my-repo:ref:refs/tags/v1.0
Environmentrepo:my-org/my-repo:environment:production

ルールセットでワイルドカード パターンを使用して、複数のリポジトリまたはブランチと一致させることができます。 レガシ サブジェクト要求の場合、repo:my-org/* は組織内のすべてのリポジトリに一致します。 変更できないサブジェクト クレームの場合は、repo:my-org@OWNER-ID/*を使用します。組織に両方の形式を使用するリポジトリが含まれている場合は、両方のパターンを設定します。

詳細については、Docker ドキュメントの ルールセットとサブジェクト クレーム を参照してください。