要約

  • id-token: write は GitHub Actions のジョブまたはワークフローが OIDC JSON Web Token を要求できるようにする設定であり、GitHub は外部リソースへの書き込み権限をそれ自体で与えるものではないと説明している。
  • クラウドプロバイダーは別途、設定された信頼条件を評価し、JWT と引き換えに短期アクセストークンを発行し得る。その後のリソース側の判断はさらに別の統制面である。
  • 根拠のあるクラウド認可の説明には、ワークフローのリビジョンと限定されたクレーム、信頼ポリシーの版、交換・セッションの記録、有効権限の文脈、リソース判断、時点を分けた対象観測を接続する必要がある。

「このパイプラインは OIDC でクラウドにアクセスする」という表現は、実装を短く説明するには便利である。ただし、それを認可の判定にしてしまうと、別々の主体が管理する複数の決定が一つに潰れる。GitHub Actions は、トークンを要求することを許されたジョブに OpenID Connect のアイデンティティトークンを発行できる。クラウドプロバイダーは GitHub の発行者を信頼し、選んだクレームを確認するよう構成できる。交換が成功すれば、ジョブは短期のクラウド資格情報を得るかもしれない。その後、クラウドサービスはロール、リソースポリシー、権限境界、セッションポリシー、組織統制、リクエスト文脈、実際の操作を見て判断する。それぞれに異なる時刻、責任者、証跡がある。

GitHub は最初の境界を明確にしている。id-token: write はワークフローが OIDC JWT を要求して利用することを許すだけで、他のリソースを変更する許可ではない。リリース審査でこの設定を見つけても、最終的な権限の説明へ書き換えてはいけない。分かるのは、そのジョブが GitHub のアイデンティティトークンを要求する資格を持っていたという限定的な事実だけである。要求が実行されたか、どの audience を求めたか、どのクレームが返ったか、クラウドがそれを信頼したか、リソースが後続操作を受け入れたかは、そこからは分からない。

クラウドとの信頼関係は、別の構成であり別の判断である。GitHub のクラウドプロバイダー向け説明では、プロバイダーがトークンのクレームを検証し、成功時にそのジョブで使えるアクセストークンを提供する。subject、audience、リポジトリーの識別子、再利用可能ワークフローの参照、その他の利用可能なクレームを受入条件にするのは、プロバイダー側のポリシーである。トークンが整形式でも信頼条件に拒まれることがある。条件が広すぎたり、期待したクレームが欠けたり形式が変わったりすることもある。クラウドトークンが発行されても、リリース担当者が想定したより狭い権限しか持たないことがある。逆に、連携交換に成功していても、後段のリソースポリシーが操作を拒否し得る。

AWS の例は、この分離を具体化する。GitHub の AWS 向け指針は AWS の信頼関係を構成し、ロール信頼ポリシーで OIDC の sub 条件キーを評価することを勧めている。GitHub の sub クレームがあることは、AWS のロールセッションが存在した記録ではない。ロールセッションが存在しても、特定の文脈で行使できた全権限の記録ではない。ロールポリシー、権限境界、セッションポリシー、組織レベルの制限、リソースポリシー、明示的拒否は、個別の判断を形作り得る。ここで AWS アカウントを監査するのではない。「OIDC がデプロイを認可した」という一般論が、どれほど多くの確認事項を省いているかを示している。

再利用可能ワークフローでは、実際の結合を残す必要がいっそう明白になる。GitHub は、その中で実行されるジョブのトークンが通常のジョブ情報を含み、job_workflow_ref も含め得ると説明する。カスタムクレームへの対応はクラウドプロバイダーによって異なる。リポジトリーにワークフロー名があるからといって、依存するプロバイダーがその値を検査したとは限らない。GitHub が呼び出し元を把握していても、それがクラウドの信頼条件で評価できるクレームに現れるとは限らない。subject クレームを後から調整すれば、プロバイダーが期待する形式も変わり得る。これらは「フェデレーション」という安心感のある語で埋めず、構成上の事実として保存すべきである。

そこで、クラウド認可には七つの部分から成る受領記録が必要になる。正確なワークフローリビジョン、起動 ref、ジョブ識別子、id-token: write の文脈を残す。要求した audience と得られたクレームは、利用可能なトークンを露出せず限定して残す。当時有効だったクラウドのアイデンティティプロバイダーと信頼ポリシーの版を残す。交換結果、ロールまたはセッションの識別子と失効時刻を残す。意図した操作に関係する有効権限の文脈を残す。リソースの判断とリクエスト記録を残す。最後に、別時点の対象観測を残す。アカウント名、リソース識別子、値は保護できる。必要なのは資格情報を公開することではなく、各決定の結び目を失わないことである。

出典

  1. GitHub Docs — クラウドプロバイダーでの OpenID Connect の構成
  2. GitHub Docs — OpenID Connect リファレンス
  3. GitHub Docs — Amazon Web Services での OpenID Connect の構成
  4. GitHub Docs — 再利用可能なワークフローでの OpenID Connect の利用