# CI 連携と OIDC 認証 {#oidc}

GitHub Actions から Takumi Guard を組織に紐づけて利用する場合、**GitHub OIDC プロバイダ**を用いてワークフローの出自を特定し、事前に許可された GitHub 組織からのリクエストであることを検証します。検証に成功するとアクセストークンが発行され、そのトークンを伴う `npm install` のダウンロードログが組織に紐づけて記録されます。CI 環境に長期有効なシークレットを保存する必要はありません。

## 認証の流れ {#auth-flow}

GitHub Actions はワークフロー実行時に OIDC トークンを発行できます。このトークンには、ワークフローを実行した GitHub 組織やリポジトリの情報が含まれています。Shisho Cloud の STS（Security Token Service）がこのトークンの署名と出自を検証し、事前に許可リストに追加された GitHub 組織からのリクエストであれば、Takumi Guard 用の短命なアクセストークンを発行します。

```mermaid
sequenceDiagram
    participant GH as GitHub Actions
    participant STS as Shisho Cloud STS
    participant GHOIDC as GitHub OIDC Provider
    participant Guard as Takumi Guard

    GH->>GH: OIDC トークンを取得
    GH->>STS: OIDC トークン + Bot ID を送信
    STS->>GHOIDC: JWKS エンドポイントから公開鍵を取得
    GHOIDC-->>STS: 公開鍵セット（JWKS）
    STS->>STS: 署名を検証し、許可された GitHub 組織か確認
    STS-->>GH: 短命なアクセストークンを発行
    GH->>Guard: アクセストークン付きで npm install
    Guard->>Guard: トークンを検証し、ダウンロードを組織に記録
```

## アクセストークン {#access-token}

検証に成功すると、STS は短命なアクセストークンを発行します。このトークンには、ダウンロードの帰属先となる Shisho Cloud 組織や、ジョブが実行された GitHub リポジトリ・ワークフローの情報が含まれます。

Takumi Guard はこのトークンを検証し、`npm install` で発生したダウンロードを組織に紐づけて記録します。ジョブ完了後にトークンは自動的に期限切れとなるため、漏洩リスクが最小限に抑えられます。アクセストークンのデフォルト有効期限は 30 分です（最大 24 時間まで設定可能）。

## Bot ID について {#bot-id}

Bot ID はシークレットではなく、許可リストを検索するための**公開参照キー**です。ワークフローファイルに直接コミットできます。実際の認証は GitHub OIDC プロバイダによるトークンの署名検証と許可リストの照合によって行われるため、Bot ID 単体ではアクセストークンを取得できません。