OpenID Connect リファレンス

OpenID Connect (OIDC) を使用してクラウド プロバイダーで GitHub Actions ワークフローを認証する方法について確認します。

この記事で

OIDC トークン クレーム

          GitHubの OIDC プロバイダーでサポートされているすべての要求を表示するには、`claims_supported``https://HOSTNAME/_services/token/.well-known/openid-configuration`エントリを確認します。

OIDC トークンには、次の要求が含まれています。

標準の audience、issuer、subject 要求

要求要求の種類説明
aud対象ユーザー既定では、これはリポジトリ所有者 (リポジトリを所有する Organization など) の URL です。 ツールキットのコマンド (core.getIDToken(audience)) を使ってカスタムの対象ユーザーを設定できます
iss発行者OIDC トークンの発行者: https://HOSTNAME/_services/token
subサブジェクトクラウド プロバイダーによって検証されるサブジェクト要求を定義します。 常に予測可能な方法でアクセス トークンを割り当てるには、この設定が不可欠です。

追加の標準 JOSE ヘッダー パラメーターと要求

ヘッダー パラメーターパラメーターのタイプ説明
algアルゴリズムOIDC プロバイダーによって使用されるアルゴリズム。
kidキー識別子OIDC トークンの一意のキー。
typタイプトークンの種類について説明します。 これは JSON Web トークン (JWT) です。
要求要求の種類説明
exp有効期限JWT の有効期限を特定します。
iat発行日時JWT が発行された日時。
jtiJWT トークン識別子OIDC トークンの一意識別子。
nbfより前には可能ではありませんこの時刻より前に JWT を使用することはできません。

          GitHub によって提供されるカスタム要求
要求説明
actorワークフロー実行を開始した個人アカウント。
actor_idワークフロー実行を開始した個人アカウントの ID。
base_refワークフロー実行における pull request のターゲット ブランチ。
enterpriseワークフローが実行されているリポジトリを含む Enterprise の名前。
enterprise_idワークフローが実行されているリポジトリを含む Enterprise の ID。
environmentジョブが使う環境の名前。
          `environment` 要求が含まれている場合 (`include_claim_keys` 経由でも)、環境が必要であり、指定する必要があります。                   |

| event_name| ワークフローの実行をトリガーしたイベントの名前。 | | head_ref| ワークフロー実行における pull request のソース ブランチ。 | | job_workflow_ref| ジョブで再利用可能なワークフローを使用する場合は、再利用可能なワークフローへの参照パス。 詳しくは、「再利用可能なワークフローでの OpenID Connect の使用」をご覧ください。 | | job_workflow_sha| 再利用可能なワークフローを使うジョブの場合は、再利用可能なワークフロー ファイルのコミット SHA。 | | ref| (Reference) ワークフロー実行をトリガーした git ref。 | | ref_type| ref の種類。例: "branch"。 | | repository_visibility | ワークフローが実行されているリポジトリの可視性。 次の値を受け入れます: internal、private、または public。 | | repository| ワークフローが実行されているリポジトリ。 | | repository_id| ワークフローが実行されているリポジトリの ID。 | | repository_owner| repository が格納されている組織の名前。 | | repository_owner_id| repository が格納されている組織の ID。 | | | | run_id| ワークフローをトリガーしたワークフロー実行の ID。 | | run_number| このワークフローが実行された回数。 | | run_attempt| このワークフロー実行が再試行された回数。 | | runner_environment| ジョブで使用されるランナーの種類。 次の値を受け入れます: github-hosted または self-hosted。 | | workflow| ワークフローの名前です。 | | workflow_ref| ワークフローへの参照パス。 たとえば、「 octocat/hello-world/.github/workflows/my-workflow.yml@refs/heads/my_branch 」のように入力します。 | | workflow_sha| ワークフロー ファイルのコミット SHA。 |

クラウド ロールでの信頼条件を定義するために使われる OIDC 要求

オーディエンスとサブジェクトのクレームは、通常、クラウドロール/リソースの条件を設定して、GitHubワークフローへのアクセスに範囲を設定する際に組み合わせて使用されます。 * Audience: 既定では、この値には組織またはリポジトリ所有者の URL を使います。 これを使って、特定の組織内のワークフローのみがクラウド ロールにアクセスできるように条件を設定できます。 * 件名： 既定では、定義済みの形式があり、 GitHub 組織、リポジトリ、ブランチ、関連付けられた job 環境など、ワークフローに関する一部の主要なメタデータを連結したものです。 連結したメタデータからサブジェクト要求を組み立てる方法については、「サブジェクト要求の例」を参照してください。

より詳細な信頼条件が必要な場合は、JWT に含まれる subject (sub) クレームをカスタマイズできます。 詳細については、「トークン クレームのカスタマイズ」を参照してください。

また、OIDC トークンでサポートされている要求は他にも多数あり、これらの条件設定にも使用できます。 さらに、クラウド プロバイダーがアクセス トークンへのロール割り当てを許可していて、さらに細かいアクセス許可を指定できる場合があります。

メモ

クラウド プロバイダーがアクセス トークンを発行する方法を制御するには、少なくとも 1 つの条件を定義し、信頼できないリポジトリがクラウド リソースにアクセス トークンを要求できないようにする必要があります。

件名の主張の例

次の例は、"Subject" を条件として使う方法を示しています。また、連結したメタデータから "Subject" を組み立てる方法について説明します。 subject は job コンテキストの情報を使い、特定のブランチ、環境内で動作するワークフローからの要求に対してのみアクセス トークン要求を許可するようにクラウド プロバイダーに指示します。 以下のセクションでは、使用できる一般的な subject について説明します。

特定の環境用にフィルタリングを行う

ジョブから環境を参照するときに、subject 要求には環境名が含まれます。

特定の環境名にフィルター処理する subject を構成することができます。 この例で、ワークフロー実行は、Production 組織が所有する octo-repo というリポジトリ内にある octo-org という環境を持つジョブから開始されている必要があります。

  • 構文: repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME
  • 例: repo:octo-org/octo-repo:environment:Production

          `pull_request` イベントを絞り込む

pull request イベントによってワークフローがトリガーされたとき、ジョブが環境を参照していない場合に限り、subject 要求には pull_request 文字列が含まれます。

          [
          `pull_request`
          ](/actions/using-workflows/events-that-trigger-workflows#pull_request) イベントにフィルター処理する subject を構成することができます。 この例で、ワークフロー実行は、`pull_request` 組織が所有する `octo-repo` というリポジトリ内の `octo-org` イベントによってトリガーされている必要があります。
  • 構文: repo:ORG-NAME/REPO-NAME:pull_request
  • 例: repo:octo-org/octo-repo:pull_request

特定のブランチにフィルター処理する

ジョブから環境を参照していない場合、かつ pull request イベントによってトリガーされたワークフローではない場合にのみ、subject 要求にはワークフローのブランチ名が含まれます。

特定のブランチ名にフィルター処理する subject を構成することができます。 この例で、ワークフロー実行は、demo-branch 組織が所有する octo-repo というリポジトリ内にある octo-org というブランチから開始されている必要があります。

  • 構文: repo:ORG-NAME/REPO-NAME:ref:refs/heads/BRANCH-NAME
  • 例: repo:octo-org/octo-repo:ref:refs/heads/demo-branch

特定のタグをフィルター処理する

ジョブから環境を参照していない場合、かつ pull request イベントによってトリガーされたワークフローではない場合にのみ、subject 要求にはワークフローのタグ名が含まれます。

特定のタグに対してフィルターをかけるトピックを作成できます。 この例で、ワークフロー実行は、demo-tag 組織が所有する octo-repo というリポジトリ内の octo-org というタグで開始されている必要があります。

  • 構文: repo:ORG-NAME/REPO-NAME:ref:refs/tags/TAG-NAME
  • 例: repo:octo-org/octo-repo:ref:refs/tags/demo-tag

クラウド プロバイダーでの subject の構成

クラウド プロバイダーの信頼関係で subject を構成するには、その信頼の構成に subject 文字列を追加する必要があります。 次の例は、さまざまなクラウド プロバイダーが同じ repo:octo-org/octo-repo:ref:refs/heads/demo-branch subject を異なる方法で受け入れる方法を示しています。

クラウド プロバイダー例
アマゾン ウェブ サービス"HOSTNAME/_services/token:sub": "repo:octo-org/octo-repo:ref:refs/heads/demo-branch"
Azurerepo:octo-org/octo-repo:ref:refs/heads/demo-branch
Google Cloud Platform(assertion.sub=='repo:octo-org/octo-repo:ref:refs/heads/demo-branch')
HashiCorp Vaultbound_subject="repo:octo-org/octo-repo:ref:refs/heads/demo-branch"

特定のクラウド プロバイダーの構成について詳しくは、「デプロイメントのセキュリティ強化」に記載されているガイドをご覧ください。

トークン クレームのカスタマイズ

JWT に含まれる要求をカスタマイズすることで、OIDC 構成のセキュリティを強化できます。 これらのカスタマイズを使用すると、ワークフローがクラウドでホストされているリソースにアクセスできるときに、クラウド ロールに対してより詳しい信頼条件を定義できます。

  •         `audience`要求の値をカスタマイズできます。 「`audience`[値のカスタマイズ](#customizing-the-audience-value)」を参照してください。
  • 特定のリポジトリ、再利用可能なワークフロー、またはその他のソースからの JWT トークンを必要とする subject (sub) 要求に条件を設定することで、OIDC 構成の形式をカスタマイズできます。
  •         `repository_id` や `repository_visibility` などの追加の OIDC トークン要求を使用して、詳しい OIDC ポリシーを定義できます。 「[AUTOTITLE](/actions/concepts/security/openid-connect#understanding-the-oidc-token)」を参照してください。


          `audience` 値のカスタマイズ

ワークフローでカスタム アクションを使用する場合、これらのアクションでは GitHub Actions Toolkit を使用して、 audience 要求のカスタム値を指定できます。 また、一部のクラウド プロバイダーでは、公式のログイン アクションでこれを使って、audience 要求の既定値が適用されます。 たとえば、Azure Login の GitHub Action では、既定の 値 が提供されます。また、ワークフローでカスタム 値を設定できます。 GitHub Actions ツールキットの詳細については、ドキュメントの OIDC トークンセクションを参照してください。

アクションによって提供される既定の aud 値を使用しない場合は、audience 要求のカスタム値を指定できます。 これにより、特定のリポジトリまたは組織内のワークフローのみがクラウド ロールにアクセスできるように条件を設定できます。 使用するアクションでこれがサポートされている場合は、ワークフローで with キーワードを使って、カスタムの aud 値をアクションに渡すことができます。 詳しくは、「メタデータ構文リファレンス」をご覧ください。

組織またはリポジトリの subject 要求のカスタマイズ

セキュリティ、コンプライアンス、標準化を向上させるため、必要なアクセス条件に合わせて標準要求をカスタマイズできます。 クラウド プロバイダーが subject 要求に関する条件をサポートしている場合は、sub の値が "job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main" などの再利用可能なワークフローのパスと一致するかどうかをチェックする条件を作成できます。 正確な形式は、クラウド プロバイダーの OIDC 構成によって異なります。 GitHubで一致条件を構成するには、REST API を使用して、sub要求に常に特定のカスタム要求 (job_workflow_ref など) を含める必要があることを要求できます。 subREST API を使って、OIDC subject 要求のカスタマイズ テンプレートを適用できます。たとえば、OIDC トークン内の 要求に、job_workflow_refなどの特定のカスタム要求を常に含めるように要求できます。 詳しくは、「GITHUB ACTIONS OIDC の REST API エンドポイント」をご覧ください。

メモ

organization テンプレートが適用されている場合、リポジトリがカスタム organization テンプレートにオプトインしていない限り、OIDC を既に使用しているワークフローには影響しません。 既存および新規のすべてのリポジトリについて、リポジトリ所有者はリポジトリ レベルの REST API を使用して、use_default を false に設定することで、この構成を受け取ることをオプトインする必要があります。 または、リポジトリ所有者は REST API を使って、リポジトリに固有の別の構成を適用することもできます。 詳しくは、「GITHUB ACTIONS OIDC の REST API エンドポイント」をご覧ください。

          `sub` 要求のカスタマイズによって、`sub`で説明されているトークンにおける既定の事前定義された[](#example-subject-claims)形式が新しい形式に置き換えられます。

メモ

          `sub` 要求では、リポジトリを参照する `repo` の代わりに短縮形式 `repo:ORG-NAME/REPO-NAME` (たとえば `repository`) が使用されます。

コンテキスト値内の : は、 %3Aに置き換えられます。

次のテンプレート例は、subject 要求をカスタマイズするさまざまな方法を示しています。 GitHubでこれらの設定を構成するには、管理者は REST API を使用して、サブジェクト (sub) 要求に含める必要がある要求の一覧を指定します。

この構成を適用するには、API エンドポイントに要求を送信し、要求本文に必要な構成を含めます。 Organization については「GITHUB ACTIONS OIDC の REST API エンドポイント」を、リポジトリについては「GITHUB ACTIONS OIDC の REST API エンドポイント」を参照してください。

subject クレームをカスタマイズするには、クラウドプロバイダーの OIDC 構成で最初に一致条件を作成し、その後 REST API を使用して構成をカスタマイズする必要があります。 構成が完了すると、新しいジョブが実行されるたびに、そのジョブの間に生成された OIDC トークンが新しいカスタマイズ テンプレートに従うようになります。 ジョブの実行前にクラウド プロバイダーの OIDC 構成に一致条件が存在しない場合、クラウド条件が同期されない可能性があるため、生成されたトークンがクラウド プロバイダーによって受け入れられない可能性があります。

例: 可視性と所有者に基づいたリポジトリの許可

このテンプレート例では、sub 要求に repository_owner と repository_visibility を使用する新しい形式を指定できます。

{
   "include_claim_keys": [
       "repository_owner",
       "repository_visibility"
   ]
}

クラウド プロバイダーの OIDC 構成で、条件に sub と repository_owner の特定の値を含める必要があることを要求する repository_visibility 条件を構成します。 たとえば、 "sub": "repository_owner:monalisa:repository_visibility:private"と指定します。 この方法では、クラウド ロールのアクセスを、Organization または Enterprise 内のプライベート リポジトリのみに制限できます。

例: 特定の所有者が設定されているすべてのリポジトリへのアクセスの許可

このテンプレート例では、sub 要求に repository_owner の値のみを含む新しい形式を指定できます。

この構成を適用するには、API エンドポイントに要求を送信し、要求本文に必要な構成を含めます。 Organization については「GITHUB ACTIONS OIDC の REST API エンドポイント」を、リポジトリについては「GITHUB ACTIONS OIDC の REST API エンドポイント」を参照してください。

{
   "include_claim_keys": [
       "repository_owner"
   ]
}

クラウド プロバイダーの OIDC 構成で、条件に sub の特定の値を含める必要があることを要求する repository_owner 条件を構成します。 例: "sub": "repository_owner:monalisa"

例: 再利用可能なワークフローの要求

このテンプレート例では、sub クレームの値を含む新しい形式を job_workflow_ref クレームに設定できます。 これにより、Enterprise は再利用可能なワークフロー を使用して、Organization とリポジトリ全体に一貫した展開を適用できます。

この構成を適用するには、API エンドポイントに要求を送信し、要求本文に必要な構成を含めます。 Organization については「GITHUB ACTIONS OIDC の REST API エンドポイント」を、リポジトリについては「GITHUB ACTIONS OIDC の REST API エンドポイント」を参照してください。

  {
     "include_claim_keys": [
         "job_workflow_ref"
     ]
  }

クラウド プロバイダーの OIDC 構成で、条件に sub の特定の値を含める必要があることを要求する job_workflow_ref 条件を構成します。 たとえば、 "sub": "job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"と指定します。

例: 再利用可能なワークフローとその他の要求の要件化

次のテンプレート例では、特定の再利用可能なワークフローの要件と追加の要求を組み合わせています。

この構成を適用するには、API エンドポイントに要求を送信し、要求本文に必要な構成を含めます。 Organization については「GITHUB ACTIONS OIDC の REST API エンドポイント」を、リポジトリについては「GITHUB ACTIONS OIDC の REST API エンドポイント」を参照してください。

この例では、"context" を使用して条件を定義する方法も示しています。 これは、既定の sub の形式でリポジトリに続く部分です。 たとえば、ジョブが環境を参照する場合、コンテキストには environment:ENVIRONMENT-NAME が含まれています。

{
   "include_claim_keys": [
       "repo",
       "context",
       "job_workflow_ref"
   ]
}

クラウド プロバイダーの OIDC 構成で、条件に sub、repo、context の特定の値を含める必要があることを要求する job_workflow_ref 条件を構成します。

このカスタマイズ テンプレートでは、sub が repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME:job_workflow_ref:REUSABLE-WORKFLOW-PATH の形式を使用する必要があります。 例: "sub": "repo:octo-org/octo-repo:environment:prod:job_workflow_ref:octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main"

例: 特定のリポジトリへのアクセスの許可

このテンプレート例では、すべてのブランチやタグ、そして環境にわたって、クラウドが特定のリポジトリ内のすべてのワークフローにアクセスできるようになります。

この構成を適用するには、API エンドポイントに要求を送信し、要求本文に必要な構成を含めます。 Organization については「GITHUB ACTIONS OIDC の REST API エンドポイント」を、リポジトリについては「GITHUB ACTIONS OIDC の REST API エンドポイント」を参照してください。

{
   "include_claim_keys": [
       "repo"
   ]
}

クラウド プロバイダーの OIDC 構成で、必要な値と一致する sub 要求を必要とするように repo 条件を構成します。

例: システム生成 GUID の使用

このテンプレート例では、エンティティの名前変更 (リポジトリの名前変更など) 間で変更されないシステム生成 GUID を使用する予測可能な OIDC 要求が有効になります。

この構成を適用するには、API エンドポイントに要求を送信し、要求本文に必要な構成を含めます。 Organization については「GITHUB ACTIONS OIDC の REST API エンドポイント」を、リポジトリについては「GITHUB ACTIONS OIDC の REST API エンドポイント」を参照してください。

  {
     "include_claim_keys": [
         "repository_id"
     ]
  }

クラウド プロバイダーの OIDC 構成で、必要な値と一致する sub 要求を必要とするように repository_id 条件を構成します。

または

{
   "include_claim_keys": [
       "repository_owner_id"
   ]
}

クラウド プロバイダーの OIDC 構成で、必要な値と一致する sub 要求を必要とするように repository_owner_id 条件を構成します。

例: : を含むコンテキスト値

この例では、: を使ってコンテキスト値を処理する方法を示します。 たとえば、ジョブが production:eastus という名前の環境を参照する場合です。

この構成を適用するには、API エンドポイントに要求を送信し、要求本文に必要な構成を含めます。 Organization については「GITHUB ACTIONS OIDC の REST API エンドポイント」を、リポジトリについては「GITHUB ACTIONS OIDC の REST API エンドポイント」を参照してください。

{
   "include_claim_keys": [
       "environment",
       "repository_owner"
   ]
}

クラウド プロバイダーの OIDC 構成で、クレームの sub と environment に特定の値が含まれることを要求する repository_owner 条件を構成します。 たとえば、 "sub": "environment:production%3Aeastus:repository_owner:octo-org"と指定します。

組織テンプレートのカスタマイズのリセット

このテンプレート例では、subject 要求を既定の形式にリセットしています。 このテンプレートは、組織レベルのカスタマイズ ポリシーから実質的にオプトアウトします。

この構成を適用するには、API エンドポイントに要求を送信し、要求本文に必要な構成を含めます。 Organization については「GITHUB ACTIONS OIDC の REST API エンドポイント」を、リポジトリについては「GITHUB ACTIONS OIDC の REST API エンドポイント」を参照してください。

{
   "include_claim_keys": [
       "repo",
       "context"
   ]
}

クラウド プロバイダーの OIDC 構成で、条件に sub と repo の特定の値を含める必要があることを要求する context 条件を構成します。

リポジトリ テンプレートのカスタマイズのリセット

組織内のすべてのリポジトリには、(組織とリポジトリ レベルの) カスタマイズされた sub 要求テンプレートをオプトインまたはオプトアウトする機能があります。

リポジトリをオプトアウトし、既定の sub 要求形式にリセットするには、リポジトリ管理者が「GITHUB ACTIONS OIDC の REST API エンドポイント」の REST API エンドポイントを使用する必要があります。

既定の sub 要求形式を使うようにリポジトリを構成するには、PUT /repos/{owner}/{repo}/actions/oidc/customization/subREST API エンドポイントを使い、次の要求本文を指定する必要があります。

{
   "use_default": true
}

例: 組織のテンプレートを使うようにリポジトリを構成する

組織がテンプレートを作成したら、REST API を使って、組織内のリポジトリにカスタマイズされた sub 要求テンプレートをプログラムで適用することができます。 リポジトリ管理者は、自分の組織の管理者によって作成されたテンプレートを使うようにリポジトリを構成できます。

Organization のテンプレートを使うようにリポジトリを構成するには、リポジトリ管理者が PUT /repos/{owner}/{repo}/actions/oidc/customization/subREST API エンドポイントを使い、次の要求本文を指定する必要があります。 詳しくは、「GITHUB ACTIONS OIDC の REST API エンドポイント」をご覧ください。

{
   "use_default": false
}

OIDC 要求のデバッグ

          [
          `github/actions-oidc-debugger`
          ](https://github.com/github/actions-oidc-debugger) アクションを使用すると、クラウド プロバイダーと統合する前に、送信される要求を視覚化できます。 このアクションは JWT を要求し、 GitHub Actionsから受信した JWT に含まれる要求を出力します。

OIDC トークンを要求するためのワークフローのアクセス許可

必要な権限

  • ジョブまたはワークフローは、id-token: writeアクセス許可を付与してGitHubの OIDC プロバイダーが JSON Web トークン (JWT) を作成できるようにする必要があります。

    permissions:
  id-token: write

  •         `id-token: write` がないと、OIDC JWT ID トークンを要求できません。 この設定では、OIDC トークンのフェッチと設定のみが有効になります。他のリソースへの書き込みアクセスは許可されません。

アクセス許可の設定

  • ワークフローの OIDC トークンをフェッチするには、ワークフロー レベルでアクセス許可を設定します。

    permissions:
  id-token: write # This is required for requesting the JWT
  contents: read # This is required for actions/checkout

  • 1 つのジョブの OIDC トークンをフェッチするには、そのジョブ内でアクセス許可を設定します。

    permissions:
  id-token: write # This is required for requesting the JWT

  • ワークフローのニーズによっては、追加のアクセス許可が必要になる場合があります。

再利用可能なワークフロー

  • 呼び出し元と同じユーザー、organization、または Enterprise が所有する再利用可能なワークフローの場合は、再利用可能なワークフローで生成された OIDC トークンに呼び出し元のコンテキストからアクセスできます。
  • Enterprise または organization の外部の再利用可能なワークフローの場合は、permissions の id-token 設定を、呼び出し元のワークフローまたはジョブのレベルで明示的に write に設定します。 これにより、OIDC トークンは目的の呼び出し元ワークフローでのみ使用できるようになります。

OIDC トークンを要求するための方法

カスタム アクションでは、次を使用して OIDC トークンを要求できます。

  • アクション ツールキットの getIDToken() メソッド。 詳しくは、npm パッケージのドキュメントの「OIDC トークン」をご覧ください。

  • ランナーで設定される以下の環境変数。

    変数説明
    ACTIONS_ID_TOKEN_REQUEST_URL
            GitHubの OIDC プロバイダーの URL。 |

    | ACTIONS_ID_TOKEN_REQUEST_TOKEN | OIDC プロバイダーに対する要求のベアラー トークン。 |

    次に例を示します。

    Shell
    curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange"