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 の証明としてクラウドプロバイダーに提示できます。
クラウドプロバイダーは、トークンで提示した要求の検証を完了した後に、ジョブの期間中にのみ使用できる有効期間の短いクラウドアクセストークンを提供します。

OIDC トークンの概要

各ジョブは 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 リファレンス」を参照してください。

GHE.com

での OIDC の構成

データ所在地付き GitHub Enterprise Cloud を使用する Enterprise のメンバーであり、GHE.com に OIDC を設定している場合は、OIDC を構成する際に特定の値を置き換える必要があります。

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

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

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

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

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

GitHub Actions ワークフローは、クラウドプロバイダーで認証するためにシークレットの代わりに OIDC トークンを使用できます。多くの一般的なクラウドプロバイダーは、ワークフローで OIDC を使用するプロセスを簡略化する公式ログインアクションを提供しています。特定のクラウドプロバイダーに関してワークフローを更新する方法の詳細については、「デプロイメントのセキュリティ強化」を参照してください。

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

メモ

この機能は現在パブリックプレビュー段階であり、変更される可能性があります。

組織およびエンタープライズ管理者は、OIDC トークンの要求としてリポジトリのカスタムプロパティを含めることができます。追加すると、そのカスタムプロパティの値が設定されている組織内または企業内のすべてのリポジトリは、OIDC トークンに自動的に含められます。先頭に repo_property_ が付きます。

これにより、リポジトリのメタデータに直接バインドする詳細なアクセスポリシーを作成でき、構成の誤差を減らし、複数のシステム間でガバナンス情報を複製する必要がなくなります。

前提条件

カスタムプロパティは、組織レベルまたはエンタープライズレベルで既に定義されている必要があります。
組織管理者またはエンタープライズ管理者である必要があります。

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

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

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

組織または企業の OIDC 設定のスクリーンショット。

        **REST API の使用:** 組織の OIDC トークン要求にカスタム プロパティを追加する `POST` 要求を送信します。

カスタムプロパティを持つ OIDC トークンの例

次の例は、 workspace_id カスタムプロパティを含む OIDC トークンを示しています。

{
  "sub": "repo:my-org/my-repo:ref:refs/heads/main",
  "aud": "https://github.com/my-org",
  "repository": "my-org/my-repo",
  "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 リファレンス」を参照してください。

この記事で