OpenID Connect

OpenID Connect (OIDC) の概要

          GitHub Actions ワークフローは、多くの場合、ソフトウェアをデプロイしたり、クラウドのサービスを使用したりするために、クラウド プロバイダー (AWS、Azure、GCP、HashiCorp Vault など) にアクセスするように設計されています。 ワークフローは、このようなリソースにアクセスできるように、パスワードやトークンなどの資格情報をクラウド プロバイダーに事前に提供します。 通常、これらの資格情報はシークレットとして GitHubに格納され、ワークフローは実行されるたびにこのシークレットをクラウド プロバイダーに提示します。

ただし、ハードコーディングされたシークレットを使用するには、クラウドプロバイダーで資格情報を作成し、シークレットとして GitHub で複製する必要があります。

OIDC をサポートするクラウドプロバイダーとの信頼できる接続を確立した後に、有効期間の短いアクセストークンをクラウドプロバイダーに直接要求するようワークフローを構成できます。

OIDC を使う利点

OIDC トークンを使うようにワークフローを更新することで、次のような優れたセキュリティプラクティスを採用できます。

        **クラウド シークレットなし:** 有効期間が長い GitHub シークレットであれば、クラウド資格情報を複製する必要はありません。 代わりに、クラウド プロバイダー上で OIDC 信頼を構成し、OIDC を介して有効期間が短いアクセス トークンをクラウド プロバイダーに要求するようにワークフローを更新することができます。

        **認証と認可の管理:** クラウド プロバイダーの認証 (authN) および認可 (authZ) ツールを使ってクラウド リソースへのアクセスを制御することで、ワークフローから資格情報を使用する方法をより細かく制御できます。

        **資格情報のローテーション:** OIDC を使う場合、1 つのジョブに対してのみ有効であり、自動的に失効する有効期間が短いアクセス トークンがクラウド プロバイダーから発行されます。

OIDC と統合する方法 GitHub Actions

次の図は、 GitHubの OIDC プロバイダーがワークフローおよびクラウドプロバイダーと統合する方法の概要を示しています。

クラウドプロバイダーがアクセストークンと JSON Web トークンクラウドロール ID を介して GitHub Actions と統合する方法の図。

クラウドプロバイダーで OIDC の信頼関係を確立し、定義されたクラウドロールに代わって特定の GitHub ワークフローがクラウドアクセストークンを要求できるようにします。
ジョブが実行されるたびに、 GitHubの OIDC プロバイダーによって OIDC トークンが自動生成されます。このトークンには、認証対象の特定のワークフローに関する、セキュリティが強化された検証可能な ID を確立するための複数の要求が含まれています。
ワークフロージョブのステップまたはアクションは、 GitHubの OIDC プロバイダーにトークンを要求できます。これにより、ワークフローの ID の証明としてクラウドプロバイダーに提示できます。
クラウドプロバイダーは、トークンで提示した要求の検証を完了した後に、ジョブの期間中にのみ使用できる有効期間の短いクラウドアクセストークンを提供します。

各ジョブは、 GitHubの OIDC プロバイダーから OIDC トークンを要求します。これは、生成されるワークフロージョブごとに一意の自動的に生成された JSON Web トークン (JWT) で応答します。このジョブを実行すると、OIDC トークンがクラウドプロバイダーに提示されます。クラウドプロバイダーは、トークンを検証するために、OIDC トークンの subject とその他の要求がクラウドロールの OIDC 信頼定義に事前に構成されている条件と一致するかどうかを確認します。

次の OIDC トークン例では、sub リポジトリ内の prod というジョブ環境を参照する subject (octo-org/octo-repo) を使っています。

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "example-thumbprint",
  "kid": "example-key-id"
}
{
  "jti": "example-id",
  "sub": "repo:octo-org/octo-repo:environment:prod",
  "environment": "prod",
  "aud": "https://github.com/octo-org",
  "ref": "refs/heads/main",
  "sha": "example-sha",
  "repository": "octo-org/octo-repo",
  "repository_owner": "octo-org",
  "actor_id": "12",
  "repository_visibility": "private",
  "repository_id": "74",
  "repository_owner_id": "65",
  "run_id": "example-run-id",
  "run_number": "10",
  "run_attempt": "2",
  "runner_environment": "github-hosted",
  "actor": "octocat",
  "workflow": "example-workflow",
  "head_ref": "",
  "base_ref": "",
  "event_name": "workflow_dispatch",
  "enterprise": "avocado-corp",
  "enterprise_id": "2",
  "repo_property_workspace_id": "ws-abc123",
  "ref_type": "branch",
  "job_workflow_ref": "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main",
  "iss": "https://token.actions.githubusercontent.com",
  "nbf": 1632492967,
  "exp": 1632493867,
  "iat": 1632493567
}

クラウドプロバイダーに対する OIDC の信頼の確立

ワークフローで OIDC を使用するには、 GitHub とクラウドプロバイダーの間に信頼関係を確立する必要があります。この信頼関係により、承認されたワークフローのみがクラウドリソースにアクセストークンを要求できるようになります。

クラウドプロバイダーは、アクセストークンを付与する前に、信頼設定で条件を設定するために使われた subject と他のすべての要求が、要求の JSON Web トークン (JWT) 内のものと一致していることを確認します。信頼の構成が一致すると、クラウドプロバイダーはワークフローに一時的アクセストークンを発行します。

OIDC の信頼を構成してクラウドプロバイダーの条件を設定するステップと構文については、「OpenID Connect リファレンス」を参照してください。

OIDC の構成 GHE.com

          データ所在地付き GitHub Enterprise Cloudを使用する企業の一員で、GHE.comで OIDC を設定する場合は、OIDC の構成時に**特定の値を置き換える**必要があります。

詳しくは、「OpenID Connect リファレンス」をご覧ください。

OIDC を使用するカスタムアクションの認証

カスタムアクションは、Actions ツールキットの getIDToken() メソッド、または curl コマンドを使用して、OIDC を使用した認証を行います。

詳しくは、「OpenID Connect リファレンス」をご覧ください。

OIDC 向けのワークフローの更新

          GitHub Actions ワークフローでは、シークレットの代わりに OIDC トークンを使用して、クラウド プロバイダーに対する認証を行うことができます。 多くの一般的なクラウド プロバイダーは、ワークフローで OIDC を使用するプロセスを簡略化する公式ログイン アクションを提供しています。 特定のクラウド プロバイダーに関してワークフローを更新する方法の詳細については、「[AUTOTITLE](/actions/how-tos/security-for-github-actions/security-hardening-your-deployments)」を参照してください。

OIDC 要求としてのリポジトリカスタムプロパティの使用

組織およびエンタープライズ管理者は、OIDC トークンの要求としてリポジトリのカスタムプロパティを含めることができます。これにより、ハードコーディングされた許可リストではなく、リポジトリメタデータによって駆動されるクラウドプロバイダー、成果物レジストリ、またはシークレットマネージャーの属性ベースのアクセス制御 (ABAC) ポリシーが有効になります。

カスタムプロパティ要求の仕組み

OIDC 要求としてカスタムプロパティを使用するためのエンドツーエンドフローは次のとおりです。

       **カスタム プロパティを定義します。** 組織またはエンタープライズ管理者は、カスタム プロパティ ( `business_unit`、 `data_classification`、 `environment_tier`など) を作成し、リポジトリに値を割り当てます。 詳細については、「[AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization)」および「[AUTOTITLE](/actions/reference/security/oidc#including-repository-custom-properties-in-oidc-tokens)」を参照してください。

       **OIDC トークンのプロパティを有効にします。** 組織またはエンタープライズ管理者は、設定 UI または REST API を使用して、OIDC トークンに含めるカスタム プロパティを選択します。

       **要求は自動的に表示されます。** 有効なプロパティの値が設定されているリポジトリで実行されるすべてのワークフローには、その値が OIDC トークンに含まれます。先頭に `repo_property_`が付きます。 ワークフロー レベルの構成の変更は必要ありません。

       **クラウド信頼ポリシーを更新します。** クラウド プロバイダーの信頼条件を更新して、新しい `repo_property_*` 要求を評価し、属性ベースの詳細なアクセス決定を可能にします。

これは GitHubの既存の OIDC の有効期間の短い資格情報モデルに基づくため、有効期間の長いシークレットは必要なく、すべてのトークンのスコープが設定され、監査可能で、ワークフローの実行ごとに自動的にローテーションされます。

前提条件

カスタムプロパティは、組織レベルまたはエンタープライズレベルで既に定義されている必要があります。詳しくは、「Organization 内リポジトリのカスタムプロパティの管理」をご覧ください。
組織管理者またはエンタープライズ管理者である必要があります。

OIDC トークン要求へのカスタムプロパティの追加

OIDC トークンにカスタムプロパティを含めるには、組織または企業の REST API または設定 UI を使用します。

        **設定 UI の使用:** 組織または企業の [アクション OIDC] 設定ページに移動して、OIDC トークンに含まれるカスタム プロパティを表示および管理します。

        **REST API の使用:**`POST` エンドポイントに`/orgs/{org}/actions/oidc/customization/properties/repo`要求を送信して、組織の OIDC トークン要求にカスタム プロパティを追加します。 要求パラメーターと完全な詳細については、OIDC カスタム プロパティ [の](/rest/actions/oidc)管理に関する REST API ドキュメントを参照してください。

カスタムプロパティを使用した OIDC トークンの例

次の例は、単一選択プロパティ business_unit と文字列プロパティ workspace_idの 2 つのカスタムプロパティを含む OIDC トークンを示しています。各カスタムプロパティは、 repo_property_ プレフィックスを持つトークンに表示されます。

{
  "sub": "repo:my-org/my-repo:ref:refs/heads/main",
  "aud": "https://github.com/my-org",
  "repository": "my-org/my-repo",
  "repository_owner": "my-org",
  "ref": "refs/heads/main",
  "repo_property_business_unit": "payments",
  "repo_property_workspace_id": "ws-abc123"
}

クラウドプロバイダーの信頼条件で repo_property_* 要求を使用して、柔軟な属性ベースのアクセス制御ポリシーを作成できます。要求の形式、サポートされているプロパティの種類、および制限の詳細については、「 OpenID Connect リファレンス」を参照してください。

          Dependabot に対する OIDC のサポート

          Dependabot OIDC を使用してプライベート レジストリで認証できるため、有効期間の長い資格情報をリポジトリ シークレットとして格納する必要がなくなります。 OIDC ベースの認証では、 Dependabot 更新ジョブは、クラウド ID プロバイダーから有効期間の短い資格情報を動的に取得できます。

          Dependabot は、AWS CodeArtifact、Azure DevOps Artifacts、または JFrog Artifactory でレジストリがホストされている場合に、 `username` および `password` 認証を使用する任意のレジストリの種類に対する OIDC 認証をサポートします。

          Dependabotの OIDC 認証の利点は次のとおりです。

* セキュリティ強化: リポジトリから、有効期間の長い静的な資格情報を削除します。 * 管理が簡単: プライベートレジストリへのセキュリティで保護されたポリシー準拠のアクセスを有効にします。 * レート制限を回避する: 動的な資格情報は、静的トークンに関連付けられているレート制限に達しないようにするのに役立ちます。

詳しくは、「Dependabot のプライベートレジストリへのアクセスの構成」をご覧ください。

次のステップ

OIDC の構成について詳しくは、「デプロイメントのセキュリティ強化」を参照してください。

OIDC のリファレンス情報については、「OpenID Connect リファレンス」を参照してください。

この記事で