# OpenID Connect リファレンス OpenID Connect (OIDC) を使用してクラウド プロバイダーで GitHub Actions ワークフローを認証する方法について確認します。 ## OIDC トークン クレーム ``` GitHubの OIDC プロバイダーでサポートされているすべての要求を表示するには、`claims_supported`https://token.actions.githubusercontent.com/.well-known/openid-configurationでエントリを確認します。 ``` OIDC トークンには、次の要求が含まれています。 ### 標準の audience、issuer、subject 要求 | 要求 | 要求の種類 | 説明 | | ----- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `aud` | 対象ユーザー | 既定では、これはリポジトリ所有者 (リポジトリを所有する Organization など) の URL です。 ツールキットのコマンド ([`core.getIDToken(audience)`](https://www.npmjs.com/package/@actions/core/v/1.6.0)) を使ってカスタムの対象ユーザーを設定できます | | `iss` | 発行者 | OIDC トークンの発行者: `https://token.actions.githubusercontent.com` | | `sub` | サブジェクト | クラウド プロバイダーによって検証されるサブジェクト要求を定義します。 常に予測可能な方法でアクセス トークンを割り当てるには、この設定が不可欠です。 | ### 追加の標準 JOSE ヘッダー パラメーターと要求 | ヘッダー パラメーター | パラメーターのタイプ | 説明 | | ----------- | ---------- | --------------------------------------------- | | `alg` | アルゴリズム | OIDC プロバイダーによって使用されるアルゴリズム。 | | `kid` | キー識別子 | OIDC トークンの一意のキー。 | | `typ` | タイプ | トークンの種類について説明します。 これは JSON Web トークン (JWT) です。 | | 要求 | 要求の種類 | 説明 | | ----- | -------------- | --------------------------- | | `exp` | 有効期限 | JWT の有効期限を特定します。 | | `iat` | 発行日時 | JWT が発行された日時。 | | `jti` | JWT トークン識別子 | OIDC トークンの一意識別子。 | | `nbf` | より前には可能ではありません | この時刻より前に JWT を使用することはできません。 | ### ``` GitHub によって提供されるカスタム要求 ``` | 要求 | 説明 | | -------------- | -------------------------------------- | | `actor` | ワークフロー実行を開始した個人アカウント。 | | `actor_id` | ワークフロー実行を開始した個人アカウントの ID。 | | `base_ref` | ワークフロー実行における pull request のターゲット ブランチ。 | | | | | `check_run_id` | 現在のジョブのチェック実行 ID。 | | | | | | | | | | | `environment` | ジョブが使う環境の名前。 | ``` `environment` 要求が含まれている場合 (`include_claim_keys` 経由でも)、環境が必要であり、指定する必要があります。 | ``` \| `event_name`| ワークフローの実行をトリガーしたイベントの名前。 | \| `head_ref`| ワークフロー実行における pull request のソース ブランチ。 | \| `job_workflow_ref`| ジョブで再利用可能なワークフローを使用する場合は、再利用可能なワークフローへの参照パス。 詳しくは、「[再利用可能なワークフローでの OpenID Connect の使用](/ja/actions/deployment/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows)」をご覧ください。 | \| `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。 | \| | \| `repo_property_*`| OIDC トークンにクレームとして含まれる、`repo_property_` プレフィックスを持つ組織レベルまたはエンタープライズレベルで定義されたカスタムプロパティ。 詳細については、「 [OIDC トークンにリポジトリ カスタム プロパティを含める](#including-repository-custom-properties-in-oidc-tokens)」を参照してください。 | \| | \| `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`](/ja/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment) 環境など、ワークフローに関する一部の主要なメタデータを連結したものです。 連結したメタデータからサブジェクト要求を組み立てる方法については、「[サブジェクト要求の例](#example-subject-claims)」を参照してください。 より詳しい信頼条件が必要な場合は、JWT に含まれるsubject (`sub`) の要求をカスタマイズできます。 詳細については、「[トークン クレームのカスタマイズ](#customizing-the-token-claims)」を参照してください。 また、OIDC トークンでサポートされている要求は他にも多数あり、これらの条件設定にも使用できます。 さらに、クラウド プロバイダーがアクセス トークンへのロール割り当てを許可していて、さらに細かいアクセス許可を指定できる場合があります。 > \[!NOTE] > クラウド プロバイダーがアクセス トークンを発行する方法を制御するには、少なくとも 1 つの条件を定義し、信頼できないリポジトリがクラウド リソースにアクセス トークンを要求できないようにする**必要があります**。 ## 件名の主張の例 次の例は、"Subject" を条件として使う方法を示しています。また、連結したメタデータから "Subject" を組み立てる方法について説明します。 [subject](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) は [`job` コンテキスト](/ja/actions/learn-github-actions/contexts#job-context)の情報を使い、特定のブランチ、環境内で動作するワークフローからの要求に対してのみアクセス トークン要求を許可するようにクラウド プロバイダーに指示します。 以下のセクションでは、使用できる一般的な subject について説明します。 ### 特定の環境用にフィルタリングを行う ジョブから環境を参照するときに、subject 要求には環境名が含まれます。 特定の[環境](/ja/actions/deployment/targeting-different-environments/managing-environments-for-deployment)名にフィルター処理する 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` ### メタデータを含む`:`のフィルタリング メタデータ値内のすべての `:` は、サブジェクト要求の `%3A` に置き換えられます。 コロンを含むメタデータを含む件名を構成できます。 この例で、ワークフロー実行は、`Production:V1` 組織が所有する `octo-repo` というリポジトリ内にある `octo-org` という環境を持つジョブから開始されている必要があります。 * 構文: `repo:ORG-NAME/REPO-NAME:environment:ENVIRONMENT-NAME` * 例: `repo:octo-org/octo-repo:environment:Production%3AV1` ## クラウド プロバイダーでの subject の構成 クラウド プロバイダーの信頼関係で subject を構成するには、その信頼の構成に subject 文字列を追加する必要があります。 次の例は、さまざまなクラウド プロバイダーが同じ `repo:octo-org/octo-repo:ref:refs/heads/demo-branch` subject を異なる方法で受け入れる方法を示しています。 | クラウド プロバイダー | 例 | | --------------------- | ------------------------------------------------------------------------------------------------- | | アマゾン ウェブ サービス | `"token.actions.githubusercontent.com:sub": "repo:octo-org/octo-repo:ref:refs/heads/demo-branch"` | | Azure | `repo: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 Vault | `bound_subject="repo:octo-org/octo-repo:ref:refs/heads/demo-branch"` | 特定のクラウド プロバイダーの構成について詳しくは、「[デプロイメントのセキュリティ強化](/ja/actions/how-tos/security-for-github-actions/security-hardening-your-deployments)」に記載されているガイドをご覧ください。 ## トークン クレームのカスタマイズ JWT に含まれる要求をカスタマイズすることで、OIDC 構成のセキュリティを強化できます。 これらのカスタマイズを使用すると、ワークフローがクラウドでホストされているリソースにアクセスできるときに、クラウド ロールに対してより詳しい信頼条件を定義できます。 * `audience`要求の値をカスタマイズできます。 「`audience`[値のカスタマイズ](#customizing-the-audience-value)」を参照してください。 * 特定のリポジトリ、再利用可能なワークフロー、またはその他のソースからの JWT トークンを必要とする subject (`sub`) 要求に条件を設定することで、OIDC 構成の形式をカスタマイズできます。 * `repository_id` や `repository_visibility` などの追加の OIDC トークン要求を使用して、詳しい OIDC ポリシーを定義できます。 「[OpenID Connect](/ja/actions/concepts/security/openid-connect#understanding-the-oidc-token)」を参照してください。 * リポジトリのカスタム プロパティを OIDC トークンに要求として含め、属性ベースのアクセス制御ポリシーを有効にすることができます。 [OIDC トークンへのリポジトリ のカスタム プロパティの組み込み](#including-repository-custom-properties-in-oidc-tokens)を参照してください。 ### ``` `audience` 値のカスタマイズ ``` ワークフローでカスタム アクションを使用する場合、これらのアクションでは GitHub Actions Toolkit を使用して、 `audience` 要求のカスタム値を指定できます。 また、一部のクラウド プロバイダーでは、公式のログイン アクションでこれを使って、`audience` 要求の既定値が適用されます。 たとえば、Azure Login の GitHub Action では、既定の 値 が提供されます。また、ワークフローでカスタム 値を設定できます。 GitHub Actions ツールキットの詳細については、ドキュメントの [OIDC トークン](https://github.com/actions/toolkit/tree/main/packages/core#oidc-token)セクションを参照してください。 アクションによって提供される既定の `aud` 値を使用しない場合は、`audience` 要求のカスタム値を指定できます。 これにより、特定のリポジトリまたは組織内のワークフローのみがクラウド ロールにアクセスできるように条件を設定できます。 使用するアクションでこれがサポートされている場合は、ワークフローで `with` キーワードを使って、カスタムの `aud` 値をアクションに渡すことができます。 詳しくは、「[メタデータ構文リファレンス](/ja/actions/creating-actions/metadata-syntax-for-github-actions#inputs)」をご覧ください。 ### OIDC トークンにリポジトリ カスタム プロパティを含める 組織およびエンタープライズ管理者は、要求として OIDC トークンに含めるリポジトリ カスタム プロパティ GitHub Actions 選択できます。 カスタム プロパティが OIDC 構成に追加されると、そのプロパティの値が設定されている組織内または企業のすべてのリポジトリが、その OIDC トークンに自動的に含められます。 プロパティ名は、プレフィックスとして `repo_property_` が付いたトークンに表示されます。 これにより、リポジトリ メタデータに直接バインドする属性ベースのアクセス制御 (ABAC) ポリシーをクラウド プロバイダーに作成できるため、構成の誤差が軽減され、リポジトリごとに個別のアクセス構成を管理する必要がなくなります。 #### 要求の形式 有効になっている各カスタム プロパティは、OIDC トークンに個別の要求として表示されます。 要求名は、 `repo_property_`でプレフィックスが付いたプロパティ名です。 | カスタム プロパティ名 | OIDC トークンの要求名 | | --------------------- | ----------------------------------- | | `business_unit` | `repo_property_business_unit` | | `workspace_id` | `repo_property_workspace_id` | | `data_classification` | `repo_property_data_classification` | #### サポートされているプロパティの種類 OIDC 要求としてサポートされているカスタム プロパティの種類を次に示します。 トークンの値表現は、プロパティの型によって異なります。 | プロパティの種類 | OIDC トークンの値の例 | メモ | | -------------- | ------------------------------------------------ | ------------------------------------------ | | 糸 | `"repo_property_team": "platform-eng"` | 値はプレーン文字列として表示されます。 | | 単一選択 | `"repo_property_env_tier": "production"` | 選択したオプションはプレーン文字列として表示されます。 | | 複数選択 | `"repo_property_regions": "us-east-1,eu-west-1"` | 複数の選択した値が 1 つのコンマ区切り文字列に結合されます。 | | true または false | `"repo_property_pci_compliant": "true"` | ブール値は、文字列 `"true"` または `"false"`として表示されます。 | #### 複数選択値表現 リポジトリに複数の値が選択された複数選択のカスタム プロパティがある場合、値は OIDC トークン内の 1 つのコンマ区切り文字列に結合されます。 たとえば、リポジトリに`regions`値と`us-east-1`値を持つ`eu-west-1` プロパティがある場合、要求は次のように表示されます。 ```json { "repo_property_regions": "us-east-1,eu-west-1" } ``` クラウド プロバイダーで信頼ポリシーを構成する場合は、文字列の照合を使用するか、複数選択要求を評価するためのチェックが含まれます。 #### カスタム プロパティを含める場合の前提条件 * カスタム プロパティは、組織レベルまたはエンタープライズ レベルで既に定義されている必要があります。 詳しくは、「[Organization 内リポジトリのカスタム プロパティの管理](/ja/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization)」をご覧ください。 * 組織管理者またはエンタープライズ管理者である必要があります。 * OIDC 構成にカスタム プロパティを追加すると、そのプロパティの値が設定されている組織内または企業のすべてのリポジトリが、OIDC トークンに自動的に含められます。 #### OIDC トークン要求へのカスタム プロパティの追加 設定 UI または REST API を使用して、OIDC トークンに含めるカスタム プロパティを管理できます。 * **設定 UI の使用:** 組織または企業の Actions OIDC 設定に移動して、OIDC トークンに含まれるカスタム プロパティを表示および構成します。 * **REST API を使用する場合:** 組織の OIDC トークン要求にカスタム プロパティを追加するには、適切な OIDC カスタム プロパティ包含エンドポイントに `POST` 要求を送信します。 次に例を示します。 * 組織の場合: `POST /orgs/{org}/actions/oidc/customization/properties/repo` * エンタープライズの場合: `POST /enterprises/{enterprise}/actions/oidc/customization/properties/repo` 要求パラメーターと完全な詳細については、OIDC カスタム プロパティを管理するための REST API ドキュメントを参照してください: [GITHUB ACTIONS OIDC の REST API エンドポイント](/ja/rest/actions/oidc)。 #### カスタム プロパティを含むトークンの例 カスタム プロパティが OIDC 構成に追加されると、そのプロパティの値が設定されているリポジトリはトークンに含まれます。 次の例では、2 つのカスタム プロパティ (`business_unit` と `workspace_id`) がトークンに含まれています。 ```json { "sub": "repo:my-org/my-repo:ref:refs/heads/main", "aud": "https://github.com/my-org", "repository": "my-org/my-repo", "repo_property_business_unit": "payments", "repo_property_workspace_id": "ws-abc123" } ``` これらの `repo_property_*` 要求は、クラウド プロバイダーの信頼ポリシーの条件として使用できます。 例については、「 [例: リポジトリのカスタム プロパティに対するフィルター処理](#example-filtering-on-a-repository-custom-property)」を参照してください。 ### 組織またはリポジトリの 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` など) を含める必要があることを要求できます。 `sub`REST API を使って、OIDC subject 要求のカスタマイズ テンプレートを適用できます。たとえば、OIDC トークン内の 要求に、`job_workflow_ref`などの特定のカスタム要求を常に含めるように要求できます。 詳しくは、「[GITHUB ACTIONS OIDC の REST API エンドポイント](/ja/rest/actions/oidc)」をご覧ください。 > \[!NOTE] > organization テンプレートが適用されている場合、リポジトリがカスタム organization テンプレートにオプトインしていない限り、OIDC を既に使用しているワークフローには影響しません。 既存および新規のすべてのリポジトリについて、リポジトリ所有者はリポジトリ レベルの REST API を使用して、`use_default` を `false` に設定することで、この構成を受け取ることをオプトインする必要があります。 または、リポジトリ所有者は REST API を使って、リポジトリに固有の別の構成を適用することもできます。 詳しくは、「[GITHUB ACTIONS OIDC の REST API エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)」をご覧ください。 ``` `sub` 要求のカスタマイズによって、`sub`で説明されているトークンにおける既定の事前定義された[](#example-subject-claims)形式が新しい形式に置き換えられます。 ``` > \[!NOTE] > > ``` > `sub` 要求では、リポジトリを参照する `repo` の代わりに短縮形式 `repo:ORG-NAME/REPO-NAME` (たとえば `repository`) が使用されます。 > ``` コンテキスト値内の `:` は、 `%3A`に置き換えられます。 次のテンプレート例は、subject 要求をカスタマイズするさまざまな方法を示しています。 GitHubでこれらの設定を構成するには、管理者は REST API を使用して、サブジェクト (`sub`) 要求に含める必要がある要求の一覧を指定します。 この構成を適用するには、API エンドポイントに要求を送信し、要求本文に必要な構成を含めます。 Organization については「[GITHUB ACTIONS OIDC の REST API エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization)」を、リポジトリについては「[GITHUB ACTIONS OIDC の REST API エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)」を参照してください。 subject クレームをカスタマイズするには、クラウドプロバイダーの OIDC 構成で最初に一致条件を作成し、その後 REST API を使用して構成をカスタマイズする必要があります。 構成が完了すると、新しいジョブが実行されるたびに、そのジョブの間に生成された OIDC トークンが新しいカスタマイズ テンプレートに従うようになります。 ジョブの実行前にクラウド プロバイダーの OIDC 構成に一致条件が存在しない場合、クラウド条件が同期されない可能性があるため、生成されたトークンがクラウド プロバイダーによって受け入れられない可能性があります。 #### 例: 可視性と所有者に基づいたリポジトリの許可 このテンプレート例では、`sub` 要求に `repository_owner` と `repository_visibility` を使用する新しい形式を指定できます。 ```json { "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 エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization)」を、リポジトリについては「[GITHUB ACTIONS OIDC の REST API エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)」を参照してください。 ```json { "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 エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization)」を、リポジトリについては「[GITHUB ACTIONS OIDC の REST API エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)」を参照してください。 ```json { "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 エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization)」を、リポジトリについては「[GITHUB ACTIONS OIDC の REST API エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)」を参照してください。 この例では、`"context"` を使用して条件を定義する方法も示しています。 これは、既定の `sub` の形式でリポジトリに続く部分です。 たとえば、ジョブが環境を参照する場合、コンテキストには `environment:ENVIRONMENT-NAME` が含まれています。 ```json { "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 エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization)」を、リポジトリについては「[GITHUB ACTIONS OIDC の REST API エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)」を参照してください。 ```json { "include_claim_keys": [ "repo" ] } ``` クラウド プロバイダーの OIDC 構成で、必要な値と一致する `sub` 要求を必要とするように `repo` 条件を構成します。 #### 例: システム生成 GUID の使用 このテンプレート例では、エンティティの名前変更 (リポジトリの名前変更など) 間で変更されないシステム生成 GUID を使用する予測可能な OIDC 要求が有効になります。 この構成を適用するには、API エンドポイントに要求を送信し、要求本文に必要な構成を含めます。 Organization については「[GITHUB ACTIONS OIDC の REST API エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization)」を、リポジトリについては「[GITHUB ACTIONS OIDC の REST API エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)」を参照してください。 ```json { "include_claim_keys": [ "repository_id" ] } ``` クラウド プロバイダーの OIDC 構成で、必要な値と一致する `sub` 要求を必要とするように `repository_id` 条件を構成します。 または ```json { "include_claim_keys": [ "repository_owner_id" ] } ``` クラウド プロバイダーの OIDC 構成で、必要な値と一致する `sub` 要求を必要とするように `repository_owner_id` 条件を構成します。 #### 例: `:` を含むコンテキスト値 この例では、`:` を使ってコンテキスト値を処理する方法を示します。 たとえば、ジョブが `production:eastus` という名前の環境を参照する場合です。 この構成を適用するには、API エンドポイントに要求を送信し、要求本文に必要な構成を含めます。 Organization については「[GITHUB ACTIONS OIDC の REST API エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization)」を、リポジトリについては「[GITHUB ACTIONS OIDC の REST API エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)」を参照してください。 ```json { "include_claim_keys": [ "environment", "repository_owner" ] } ``` クラウド プロバイダーの OIDC 構成で、クレームの `sub` と `environment` に特定の値が含まれることを要求する `repository_owner` 条件を構成します。 たとえば、 `"sub": "environment:production%3Aeastus:repository_owner:octo-org"`と指定します。 #### 例: リポジトリのカスタム プロパティに対するフィルター処理 このテンプレート例では、 `sub` 要求にリポジトリのカスタム プロパティ要求を含めることができます。 OIDC トークンに含まれるカスタム プロパティは、トークンに `repo_property_` が付いたプレフィックスで表示されますが、 `include_claim_keys` 値では、トークンに表示される完全な要求名が使用されます。 この構成を適用するには、API エンドポイントに要求を送信し、要求本文に必要な構成を含めます。 Organization については「[GITHUB ACTIONS OIDC の REST API エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization)」を、リポジトリについては「[GITHUB ACTIONS OIDC の REST API エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)」を参照してください。 ```json { "include_claim_keys": [ "repo_property_workspace_id" ] } ``` クラウド プロバイダーの OIDC 構成で、条件に `sub` の特定の値を含める必要があることを要求する `repo_property_workspace_id` 条件を構成します。 たとえば、 `"sub": "repo_property_workspace_id:ws-abc123"`と指定します。 #### 組織テンプレートのカスタマイズのリセット このテンプレート例では、subject 要求を既定の形式にリセットしています。 このテンプレートは、組織レベルのカスタマイズ ポリシーから実質的にオプトアウトします。 この構成を適用するには、API エンドポイントに要求を送信し、要求本文に必要な構成を含めます。 Organization については「[GITHUB ACTIONS OIDC の REST API エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-an-organization)」を、リポジトリについては「[GITHUB ACTIONS OIDC の REST API エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)」を参照してください。 ```json { "include_claim_keys": [ "repo", "context" ] } ``` クラウド プロバイダーの OIDC 構成で、条件に `sub` と `repo` の特定の値を含める必要があることを要求する `context` 条件を構成します。 #### リポジトリ テンプレートのカスタマイズのリセット 組織内のすべてのリポジトリには、(組織とリポジトリ レベルの) カスタマイズされた `sub` 要求テンプレートをオプトインまたはオプトアウトする機能があります。 リポジトリをオプトアウトし、既定の `sub` 要求形式にリセットするには、リポジトリ管理者が「[GITHUB ACTIONS OIDC の REST API エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)」の REST API エンドポイントを使用する必要があります。 既定の `sub` 要求形式を使うようにリポジトリを構成するには、`PUT /repos/{owner}/{repo}/actions/oidc/customization/sub`REST API エンドポイントを使い、次の要求本文を指定する必要があります。 ```json { "use_default": true } ``` #### 例: 組織のテンプレートを使うようにリポジトリを構成する 組織がテンプレートを作成したら、REST API を使って、組織内のリポジトリにカスタマイズされた `sub` 要求テンプレートをプログラムで適用することができます。 リポジトリ管理者は、自分の組織の管理者によって作成されたテンプレートを使うようにリポジトリを構成できます。 Organization のテンプレートを使うようにリポジトリを構成するには、リポジトリ管理者が `PUT /repos/{owner}/{repo}/actions/oidc/customization/sub`REST API エンドポイントを使い、次の要求本文を指定する必要があります。 詳しくは、「[GITHUB ACTIONS OIDC の REST API エンドポイント](/ja/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository)」をご覧ください。 ```json { "use_default": false } ``` ## OIDC 要求のデバッグ ``` [ `github/actions-oidc-debugger` ](https://github.com/github/actions-oidc-debugger) アクションを使用すると、クラウド プロバイダーと統合する前に、送信される要求を視覚化できます。 このアクションは JWT を要求し、 GitHub Actionsから受信した JWT に含まれる要求を出力します。 ``` ## OIDC トークンを要求するためのワークフローのアクセス許可 ### 必要な権限 * ジョブまたはワークフローは、[`id-token: write`](/ja/actions/reference/workflow-syntax-for-github-actions#permissions)アクセス許可を付与してGitHubの OIDC プロバイダーが JSON Web トークン (JWT) を作成できるようにする必要があります。 ```yaml permissions: id-token: write ``` * `id-token: write` がないと、OIDC JWT ID トークンを要求できません。 この設定では、OIDC トークンのフェッチと設定のみが有効になります。他のリソースへの書き込みアクセスは許可されません。 ### アクセス許可の設定 * ワークフローの OIDC トークンをフェッチするには、ワークフロー レベルでアクセス許可を設定します。 ```yaml permissions: id-token: write # This is required for requesting the JWT contents: read # This is required for actions/checkout ``` * 1 つのジョブの OIDC トークンをフェッチするには、そのジョブ内でアクセス許可を設定します。 ```yaml 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 トークン](https://www.npmjs.com/package/@actions/core/v/1.6.0#oidc-token)」をご覧ください。 * ランナーで設定される以下の環境変数。 | 変数 | 説明 | | ------------------------------ | -- | | `ACTIONS_ID_TOKEN_REQUEST_URL` | | ``` GitHubの OIDC プロバイダーの URL。 | ``` \| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | OIDC プロバイダーに対する要求のベアラー トークン。 | 次に例を示します。 ```shell copy curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api://AzureADTokenExchange" ```