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 トークンをアクセス トークンと交換する方法の概要を次に示します。
最初の要求
- ユーザーは、Copilot Extension にメッセージを送信します。
- GitHub により、ユーザー ID 情報を含む OIDC トークンが生成されます。
- GitHub により、OIDC トークンを使ってトークン交換エンドポイントが呼び出されます。
- サービスによってトークンが検証され、アクセス トークンが返されます。
- GitHub により、拡張機能への要求にアクセス トークンが追加されます。
# HTTP header
Authorization: Bearer <your-service-token>
X-GitHub-Token: <github-token>
後続の要求
- GitHub により、アクセス トークンは最長 10 分間キャッシュされます。
- キャッシュされたトークンは後続の要求で再利用されます。
- トークンの有効期限が切れるか無効になった場合、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 つの手順があります。
トークン交換エンドポイントを構成する
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 を有効にします。
-
GitHub の任意のページの右上隅にある、自分のプロファイル写真をクリックします。
-
アカウント設定にアクセスしてください。
- 個人用アカウントが所有するアプリの場合は、[設定] をクリックします。
- 組織が所有するアプリの場合:
- [自分の組織] をクリックします。
- 組織の右側にある [設定] をクリックします。
- Enterprise が所有するアプリの場合:
- Enterprise Managed Users を使用する場合は、[Enterprise] をクリックして Enterprise アカウントの設定に移動します。
- 個人用アカウントを使用する場合は、[Enterprise] をクリックしてから、Enterprise の右側にある [設定] をクリックします。
-
GitHub App 設定にアクセスしてください。
- 個人用アカウントまたは組織が所有するアプリの場合:
- 左側のサイドバーで、 [開発者向け設定] をクリックし、 [GitHub Apps] をクリックします。
- Enterprise が所有するアプリの場合:
- 左側のサイドバーで、 [設定] から GitHub Apps をクリックします。
- 個人用アカウントまたは組織が所有するアプリの場合:
-
Copilot Extension の場合、構成する GitHub App の右側にある [編集] をクリックします。
-
左側のサイドバーで、[Copilot] をクリックします。
-
[OpenID Connect Token Exchange] で、[Enabled] をオンにします。
-
[Token exchange endpoint] フィールドに、トークン交換 URL を入力します。
-
[Request header key] フィールドに、サービスのトークンのヘッダー キーを入力します。 既定値は、
Authorization
です。 -
[Request header value] フィールドに、ヘッダー値の形式を入力します。 既定値は、
Bearer ${token}
です。
OIDC トークンを検証する
トークン交換エンドポイントは、以下の手順に従って、GitHub OIDC トークンを検証する必要があります。
- https://github.com/login/oauth/.well-known/openid-configuration から JSON Web キー セット (JWKS) をフェッチします。
- トークンのシグネチャを確認します。
- 必要な要求を検証します。
aud
: 対象ユーザー。 Copilot Extension のクライアント ID。sub
: 件名。 要求を行う GitHub ユーザー ID。 応答は、ユーザーがアクセス許可を持っているデータに限定されます。 ユーザーにアクセス許可がない場合は、400 Bad Request
が表示されます。iat
: 発行時刻。 トークンが発行されたときのタイムスタンプ。 通常、これは過去のタイムスタンプですが、トークンが作成された正確な瞬間を表します。nbf
: 期間の開始時刻。 このタイムスタンプより前には、トークンが無効です。 これは過去のタイムスタンプである必要があります。exp
: 有効期限。 トークンの有効期限が切れたときのタイムスタンプ。 これは将来のタイムスタンプである必要があります。act
: アクター。 委任されたアクセスの実行エンティティ。 これは定数文字列である必要があります。
トラブルシューティング
次のセクションでは、Copilot Extension 用に OIDC を実装する際の一般的な問題とベスト プラクティスについて概要を説明します。
トークン検証エラー
- 正しい JWKS エンドポイントを使っていることを確認します。
- 必要な要求がすべて存在し、有効であることを確認します。
- タイムスタンプ (
iat
、nbf
、exp
) が有効な範囲内にあることをチェックします。
トークン交換エラー
- 無効なトークンの場合は
HTTP 400
を返します。 - 必要なアクセス許可がユーザーにない場合は、
HTTP 403
を返します。 - GitHub が 403 応答を受信した場合、新しいトークンを使って要求を再試行します。
パフォーマンスの問題
- 効率的なトークン検証を実装して待機時間を最小限に抑えます。
- 適切なトークンの有効期限を使います (推奨: 10 分以下)。
- 高トラフィックの拡張機能の場合は、キャッシュの影響を考慮します。
ベスト プラクティス
- トークンのスコープを必要最小限のアクセス許可に限定します。
- 適切なエラー処理とログを実装します。
- セキュリティ上の異常がないか、トークン交換パターンを監視します。
- セキュリティ リスクを最小限に抑えるために、トークンの有効期間を短くします。
- アクセス トークンを発行する前に、すべての要求を検証します。
- トークン交換エンドポイントにレート制限を実装することを検討してください。
- すべてのトークン交換通信には HTTPS を使います。