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

{
  "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",
  "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 リファレンス」をご覧ください。

この記事の内容

OpenID Connect (OIDC) の概要

OIDC を使う利点

OIDC と GitHub Actions の統合方法

OIDC トークンの概要

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

GHE.com

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

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

次のステップ