Skip to main content

GitHub Copilot Extensions で OIDC を使う

Copilot Extension で OpenID Connect (OIDC) を使ってセキュリティを強化する方法について説明します。

Copilot Extensions 用 OpenID Connect (OIDC) について

Copilot Extensions で OpenID Connect (OIDC) を使うと、有効期間の長い GitHub 資格情報を格納するのではなく、クラウド プロバイダーから有効期間の短いトークンを直接交換できます。 この機能により、Copilot エージェントとスキルセットの両方がより安全にユーザーを認証し、クラウド リソースにアクセスできるようになります。

OIDC の概要

多くの場合、Copilot Extensions は、ユーザーに代わってサード パーティのリソースまたは API にアクセスする必要があります。 これまでは、GitHub トークンをシークレットとして格納し、追加の API 呼び出しを行ってこれらのトークンをシステム内のユーザー ID にマップする必要がありました。 OIDC を使うと、拡張機能は、GitHub の ID 情報を交換することで、認証サービスから有効期間の短いアクセス トークンを直接要求できます。

有効にすると、GitHub の OIDC プロバイダーにより、ユーザーと要求コンテキストに関する要求を含むトークンが自動的に生成されます。 認証サービスにより、これらの要求が検証され、自分のサービス専用のスコープのアクセス トークンと交換されます。

GitHub 固有のエンドポイントを個別に維持することなく、既存の API エンドポイントを利用できるため、OIDC の使用は Copilot スキルセットの開発に特に役立ちます。 GitHub トークンを受け入れるためにエンドポイントを複製するのではなく、OIDC を使って GitHub ID をサービスのネイティブ認証トークンに変換できます。

OIDC を使う利点

Copilot Extension に OIDC トークン交換を実装すると、次のことが可能になります。

  • 有効期間の長い GitHub トークンを格納しないようにするか、GitHub とサービスの ID の間のマッピングを維持する。
  • 自動的に期限切れになり、サービスのニーズに合わせてスコープを指定できる有効期間の短いトークンを使う。
  • トークンの検証やユーザー情報のフェッチのために、GitHub の API を追加で呼び出すことを避ける。
  • GitHub 用に別のエンドポイントを維持することなく、Copilot スキルと既存の API の直接統合を有効にする。
  • GitHub の認証をサービスのネイティブ トークンに変換することで、既存の API エンドポイントを再利用する。

トークン交換フロー

拡張機能への要求を認証するために、Copilot Extensibility Platform が OIDC トークンをアクセス トークンと交換する方法の概要を次に示します。

最初の要求

  1. ユーザーは、Copilot Extension にメッセージを送信します。
  2. GitHub により、ユーザー ID 情報を含む OIDC トークンが生成されます。
  3. GitHub により、OIDC トークンを使ってトークン交換エンドポイントが呼び出されます。
  4. サービスによってトークンが検証され、アクセス トークンが返されます。
  5. GitHub により、拡張機能への要求にアクセス トークンが追加されます。
# HTTP header
Authorization: Bearer <your-service-token>
X-GitHub-Token: <github-token>

後続の要求

  1. GitHub により、アクセス トークンは最長 10 分間キャッシュされます。
  2. キャッシュされたトークンは後続の要求で再利用されます。
  3. トークンの有効期限が切れるか無効になった場合、GitHub から新しいトークンが要求されます。

OIDC トークンの概要

GitHub の OIDC トークンは、ユーザーと要求コンテキストに関する要求を含む JWT です。

{
  "jti": "<unique-token-id>",
  "sub": "<github-user-id>",
  "aud": "<your-client-id>",
  "iss": "https://github.com/login/oauth",
  "nbf": 1632492967,
  "exp": 1632493867,
  "iat": 1632493567,
  "act": {
    "sub": "api.copilotchat.com"
  }
}

拡張機能に合わせて OIDC を設定する

拡張機能に合わせて OIDC を設定するには、3 つの手順があります。

  1. トークン交換エンドポイントを構成する
  2. Copilot 拡張機能の設定で OIDC を有効にする
  3. OIDC トークンを検証する

トークン交換エンドポイントを構成する

RFC 8693 OAuth 2.0 Token Exchange に準拠するエンドポイントをサービス内に作成します。 このエンドポイントは次のことを行う必要があります。

  • 次のフォーム エンコード パラメーターを含む POST 要求を受け入れます。

    grant_type=urn:ietf:params:oauth:grant-type:token-exchange
    &resource=<https://your-service.com/resource>
    &subject_token=<github-jwt-token>
    &subject_token_type=urn:ietf:params:oauth:token-type:id_token
    
  • サービスのアクセス トークンを含む JSON 応答を返します。

    {
      "access_token": <"your-service-token">,
      "Issued_token_type":"urn:ietf:params:oauth:token-type:access_token",
      "token_type": "Bearer",
      "expires_in": 3600
    }
    
  • 検証が失敗した場合は、エラー応答を返します。

    {
      "error": "invalid_request"
    }
    

Copilot Extension の設定で OIDC を有効にする

Copilot Extension の構成で、OIDC を有効にします。

  1. GitHub の任意のページの右上隅にある、自分のプロファイル写真をクリックします。
  2. アカウント設定にアクセスしてください。
    • 個人用アカウントが所有するアプリの場合は、[設定] をクリックします。
    • 組織が所有するアプリの場合:
      1. [自分の組織] をクリックします。
      2. 組織の右側にある [設定] をクリックします。
  3. 左側のサイドバーで [ 開発者設定] をクリックします。
  4. 左側のサイドバーで、 [GitHub Apps] をクリックします。
  5. Copilot Extension の場合、構成する GitHub App の右側にある [編集] をクリックします。
  6. 左側のサイドバーで、[Copilot] をクリックします。
  7. [OpenID Connect Token Exchange] で、[Enabled] をオンにします。
  8. [Token exchange endpoint] フィールドに、トークン交換 URL を入力します。
  9. [Request header key] フィールドに、サービスのトークンのヘッダー キーを入力します。 既定値は、Authorization です。
  10. [Request header value] フィールドに、ヘッダー値の形式を入力します。 既定値は、Bearer ${token} です。

OIDC トークンを検証する

トークン交換エンドポイントは、以下の手順に従って、GitHub OIDC トークンを検証する必要があります。

  1. https://github.com/login/oauth/.well-known/openid-configuration から JSON Web キー セット (JWKS) をフェッチします。
  2. トークンのシグネチャを確認します。
  3. 必要な要求を検証します。
    • aud: 対象ユーザー。 Copilot Extension のクライアント ID。
    • sub: 件名。 要求を行う GitHub ユーザー ID。 応答は、ユーザーがアクセス許可を持っているデータに限定されます。 ユーザーにアクセス許可がない場合は、400 Bad Request が表示されます。
    • iat: 発行時刻。 トークンが発行されたときのタイムスタンプ。 通常、これは過去のタイムスタンプですが、トークンが作成された正確な瞬間を表します。
    • nbf: 期間の開始時刻。 このタイムスタンプより前には、トークンが無効です。 これは過去のタイムスタンプである必要があります。
    • exp: 有効期限。 トークンの有効期限が切れたときのタイムスタンプ。 これは将来のタイムスタンプである必要があります。
    • act: アクター。 委任されたアクセスの実行エンティティ。 これは定数文字列である必要があります。

トラブルシューティング

次のセクションでは、Copilot Extension 用に OIDC を実装する際の一般的な問題とベスト プラクティスについて概要を説明します。

トークン検証エラー

  • 正しい JWKS エンドポイントを使っていることを確認します。
  • 必要な要求がすべて存在し、有効であることを確認します。
  • タイムスタンプ (iatnbfexp) が有効な範囲内にあることをチェックします。

トークン交換エラー

  • 無効なトークンの場合は HTTP 400 を返します。
  • 必要なアクセス許可がユーザーにない場合は、HTTP 403 を返します。
  • GitHub が 403 応答を受信した場合、新しいトークンを使って要求を再試行します。

パフォーマンスの問題

  • 効率的なトークン検証を実装して待機時間を最小限に抑えます。
  • 適切なトークンの有効期限を使います (推奨: 10 分以下)。
  • 高トラフィックの拡張機能の場合は、キャッシュの影響を考慮します。

ベスト プラクティス

  • トークンのスコープを必要最小限のアクセス許可に限定します。
  • 適切なエラー処理とログを実装します。
  • セキュリティ上の異常がないか、トークン交換パターンを監視します。
  • セキュリティ リスクを最小限に抑えるために、トークンの有効期間を短くします。
  • アクセス トークンを発行する前に、すべての要求を検証します。
  • トークン交換エンドポイントにレート制限を実装することを検討してください。
  • すべてのトークン交換通信には HTTPS を使います。