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

このドキュメントは、Foundry に接続する OAuth2 クライアントを作成したい Foundry ユーザーまたは管理者を対象としています。このページでは、OAuth 2.0 認可フレームワーク ↗ の説明と、Foundry における OAuth2 の実装の詳細を紹介します。また、Foundry サードパーティアプリケーションおよび API 契約は、Foundry プラットフォーム上でのサードパーティアプリケーションの使用を規定するものであり、サードパーティアプリケーションの作成者と管理者はその内容を理解しておく必要があります。

OAuth2 の概要

OAuth2 認可フレームワークにより、サードパーティアプリケーションはサービスへの制御されたアクセス権を取得できます。OAuth2 は、ユーザーの資格情報や固定の Bearer トークンではなく、専用に発行されたアクセストークンとリフレッシュトークンを使用して、クライアント（サードパーティアプリケーションなど）がアクセス権をリクエストできるレイヤーを提供することで、従来のクライアントサーバー型の認可モデルを改善します。OAuth2 は、アクセストークンを取得する方法であるグラントを使用して、このアクセスを管理します。

OAuth2 統合をサポートする

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

Foundry で OAuth2 を使用するには、サードパーティアプリケーションを登録するの手順に従ってアプリケーションを登録し、以降のサブセクションに記載されている認可の選択肢から1つを選ぶ必要があります。

認可コードグラント

認可コードグラントを使用すると、クライアントは既存の 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

トークンエンドポイントは、クライアントが認可グラントまたはリフレッシュトークンを提示してアクセストークンを取得するために使用します。

ヘッダーパラメーター

リクエスト本文のパラメーター

レスポンス本文

レスポンス JSON には、以下のフィールドが含まれます。

エンドポイントのエラー

エラーレスポンス本文

リクエストに失敗した場合、アクセスリクエストが拒否されたときに限り、ユーザーのブラウザーがリダイレクトされます。それ以外の場合は、以下のフィールドを含む HTML エラーページが返されます。

エラーコード