Foundry 用 OAuth2 クライアントの作成

このドキュメントは、Foundry に接続するための OAuth2 クライアントを作成したい Foundry ユーザーまたは管理者向けです。このページでは OAuth 2.0 Authorization Framework ↗ の説明と、Foundry の OAuth2 の実装についての詳細を提供します。さらに、Foundry Third-Party Application & API Agreement は Foundry プラットフォーム上でのサードパーティアプリケーションの使用を規定しており、サードパーティアプリケーションの作成者や管理者によって理解されるべきです。

OAuth2 概要

OAuth2 認可フレームワークは、サードパーティアプリケーションがサービスへの制御されたアクセスを取得することを可能にします。OAuth2 は、ユーザーの資格情報や静的なベアラートークンの代わりに、特別に発行されたアクセストークンと再読み込みトークンを使用してアクセスを要求するクライアント（サードパーティアプリケーションなど）を可能にするレイヤーを提供することにより、従来のクライアントサーバー認証モデルを改善します。OAuth2 は、アクセストークンを取得するための方法であるグラントを使用してこのアクセスを管理します。

OAuth2 統合のサポート

以下のセクションでは、サードパーティアプリケーションで OAuth2 をサポートする方法について説明します。ドキュメント全体で、クライアント はサードパーティアプリケーション、認可サーバー は Foundry の認可サーバー、ユーザー はサードパーティアプリケーションのエンドユーザーを指します。

Foundry と OAuth2 を使用するには、サードパーティアプリケーションの登録手順に従ってアプリケーションを登録し、次のサブセクションのいずれかの認可オプションを選択する必要があります。

認可コードグラント

認可コードグラントにより、クライアントは既存の Foundry ユーザーに代わって操作を行うことができます。アプリケーションはアクセスする必要がある Foundry 権限のセットを要求し、次に Foundry ユーザーがそのアカウントでクライアントにその権限へのアクセスを明示的に許可する必要があります。Foundry は、クライアントが限られたリソースセットに制限されるか、ユーザーがアクセスできるすべてのリソースに制限されることを許可します。

認可コードグラントは次のように機能します：

1. クライアントは code_verifier と code_challenge を作成します。これは 機密クライアント ↗（クライアントシークレットを安全に保存できるサーバーベースのアプリケーションなど）には推奨されますが、必須ではありません。これは パブリッククライアント ↗（クライアントシークレットを安全に保存できないネイティブアプリなど）には必須です。
   • code_verifier は A-Z、a-z、0-9、-（ハイフン）、.（ピリオド）、_（アンダースコア）、および ~（チルダ）を含む暗号的にランダムな文字列で、43 から 128 文字の長さです。
   • code_challenge は code_verifier に SHA256 を実行し、それを Base64-URL エンコードされた値に変換し、パディングなしで作成されます。
2. クライアントアプリケーションはブラウザを開き、ユーザーを次のクエリパラメーターを追加して 認可エンドポイント URL に送信する必要があります：
   • response_type: これは code に設定する必要があります。
   • client_id: これはサードパーティアプリケーションが Foundry に登録されたときに生成された ID に設定する必要があります。
   • redirect_uri: これは、ユーザーがリクエストを承認した後に認可サーバーがユーザーをリダイレクトする場所を示します。指定されていない場合、Foundry のサードパーティアプリケーション設定の最初のリダイレクト URI 値にデフォルト設定されます。
   • scope: これは要求される権限を定義します。公開 API のスコープは API ドキュメント にあります。再読み込みトークンを取得するために offline_access スコープを追加します。複数のスコープを使用する場合、スペースを区切り文字として使用してスコープを連結します。
   • state: これはアプリケーションによって生成されるランダムな文字列で、そのままアプリケーションに返されます。アプリケーションは、CSRF 攻撃を防ぐために、返された値が元の文字列と一致することを確認する必要があります。
   • code_challenge: クライアントが code_challenge を作成した場合、このパラメーターを入力する必要があります。認可サーバーは内部的に code_challenge パラメーターを生成した認可コードと関連付けます。
   • code_challenge_method: これは S256 に設定する必要があります。
3. ユーザーが URL にアクセスすると、認可サーバーはユーザーに次のようなプロンプトを表示し、ユーザーはアプリのリクエストを承認することを選択できます。

4. リクエストが成功すると、認可サーバーは指定されたリダイレクト URI にユーザーをリダイレクトし、次のクエリパラメーターを追加します：
   • code: これは認可サーバーが生成する認可コードです。
   • state: これは認可リクエストでクライアントが渡したのと同じパラメーターです。クライアントは、リクエストで送信された元の state パラメーターと一致することを確認する必要があります。
5. クライアントは次に トークンエンドポイント を呼び出して認可コードをアクセストークンに交換する必要があります。次のパラメーターをリクエストボディで application/x-www-form-urlencoded 形式で送信する必要があります：
   • grant_type: これは authorization_code に設定する必要があります。
   • code: 認可サーバーから受け取ったコード。
   • redirect_uri: ユーザーエージェントがリダイレクトされる絶対 URI。
   • client_id: これはサードパーティアプリケーションが Foundry に登録されたときに生成された ID に設定する必要があります。
   • code_verifier: クライアントが code_verifier を生成した場合、このリクエストで送信する必要があります。認可サーバーは code_verifier が前のリクエストで送信された code_challenge と一致することを確認します。
6. 認可サーバーは次に、クライアントが要求されたリソース（REST API など）にアクセスするために使用できるアクセストークンで応答します。応答には次のパラメーターが含まれます：
   • access_token: クライアントが要求されたリソースにアクセスするために使用できるトークン。
   • token_type: 発行されたトークンの種類。
   • expires_in: アクセストークンの有効期限（秒）。
   • refresh_token: これは要求されたスコープに offline_access が含まれている場合にのみ返されます。ユーザーがリクエストを承認するために存在しなくてもクライアントがアクセストークンを更新したい場合、これを使用する必要があります。詳細は アクセストークンの再読み込み を参照してください。

クライアント資格情報グラント

クライアント資格情報グラントは、クライアントが通常の Foundry ユーザーに関連付けられない操作を行う、非対話型のサービスユーザー形式のワークフロー向けに設計されています。クライアントは通常の Foundry ユーザーに代わって操作を行いません。

代わりに、このグラントタイプはクライアントに関連付けられた Foundry サービスユーザーを自動的に作成し、その後、Foundry リソースへのアクセス権限を付与できます。このグラントによって取得されたトークンは、作成されたサービスユーザーに代わってリソースにアクセスするために使用できます。サービスユーザーアカウントのユーザー名は、アプリケーションのクライアント ID と同じです。

クライアント資格情報グラントは次のように機能します：

1. クライアントは トークンエンドポイント を呼び出します。次のパラメーターをリクエストボディで application/x-www-form-urlencoded 形式で送信する必要があります：
   • grant_type: これは client_credentials に設定する必要があります。
   • client_id: これはサードパーティアプリケーションが Foundry に登録されたときに生成された ID に設定する必要があります。
   • client_secret: これはサードパーティアプリケーションが Foundry に登録されたときに生成されたクライアントシークレットに設定する必要があります。
2. 認可サーバーは次のように応答します：
   • access_token: クライアントが要求されたリソースにアクセスするために使用できるトークン。
   • token_type: 発行されたトークンの種類。
   • expires_in: アクセストークンの有効期限（秒）。
3. クライアントは次にアクセストークンを使用して要求されたリソースにアクセスできます。

アクセストークンの再読み込み

アクセストークンは一定時間後に期限切れとなり、再取得する必要があります。ユーザーが存在しないときに Foundry API にアクセスする必要があるクライアントは、トークンを再読み込みする必要があります。

これは次の手順に従うことで行えます：

1. クライアントは 認可コードグラント の手順に従い、要求される scope パラメーターの一部として offline_access を指定する必要があります。
2. クライアントは 認可コードグラント の最終手順で返された refresh_token を保存する必要があります。
3. アクセストークンが期限切れになると、クライアントは次のパラメーターを使用して トークンエンドポイント エンドポイントを呼び出してトークンを再読み込みできます：
   • grant_type: これは refresh_token に設定する必要があります。
   • refresh_token: 以前に取得したユーザーの再読み込みトークン。
   • client_id: これはサードパーティアプリケーションが Foundry に登録されたときに生成された ID に設定する必要があります。
   • client_secret: これはサードパーティアプリケーションが Foundry に登録されたときに生成されたクライアントシークレットに設定する必要があります。
4. 認可サーバーは次のように応答します：
   • access_token: クライアントが要求されたリソースにアクセスするために使用できるトークン。
   • token_type: 発行されたトークンの種類。
   • expires_in: アクセストークンの有効期限（秒）。
   • refresh_token: アクセストークンを再読み込みするために使用できる再読み込みトークン。Foundry は以前に発行された再読み込みトークンが使用されるたびに再読み込みトークンをローテーションします。access_token と refresh_token の両方を保存することを確認してください。

再読み込みトークンのローテーション

再読み込みトークンは新しいアクセストークンを取得するために使用できます。Foundry は、以前に発行された再読み込みトークンが使用されるたびに再読み込みトークンをローテーションすることによって、再読み込みトークンに関連するリスクを低減します。 再利用検出保護メカニズムにより、再読み込みトークンが初めて使用されてから1分後に再利用された場合、このグラントから作成されたすべてのアクセストークンが無効化され、新しい認可フローが必要になります。 ネットワーク障害などの一時的なエラーを考慮して、再利用のために1分間の間隔が許可されます。さらに、30日以上非アクティブな再読み込みトークンは自動的に無効化されます。これらの保護策により、潜在的に侵害されたトークンによるリスクが低減され、長期間有効な再読み込みトークンが存在しないようにします。

OAuth2 API リファレンス

次のエンドポイントを使用して OAuth2 トークンを取得できます。

認可エンドポイント

GET /multipass/api/oauth2/authorize

クライアントが認可コードを取得するために使用する認可エンドポイント。

クエリパラメーター

リダイレクトクエリパラメーター

リクエストが成功すると、ユーザーのブラウザはサードパーティアプリケーション設定で指定されたリダイレクト URI またはリクエストで渡されたリダイレクト URI にリダイレクトされます。リダイレクトリクエスト URI には次のクエリパラメーターが含まれます：

トークンエンドポイント

POST /multipass/api/oauth2/token

トークンエンドポイントは、クライアントが認可グラントまたは再読み込みトークンを提示してアクセストークンを取得するために