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

このドキュメンテーションは、Foundry に接続するための OAuth2 クライアントを作成したい Foundry ユーザーまたは管理者向けに作成されました。このページでは、OAuth 2.0 認証フレームワーク の説明と、Foundry の OAuth2 の実装について詳しく説明しています。また、Foundry 第三者アプリケーション & API 利用規約 は、Foundry プラットフォーム上の第三者アプリケーションの利用を規定しており、第三者アプリケーションの作成者や管理者が理解するべき内容です。

OAuth2 の概要

OAuth2 認証フレームワークを利用すると、第三者アプリケーションがサービスへの制御されたアクセスを得ることができます。OAuth2 は、特別に発行されたアクセストークンとリフレッシュトークンを利用してクライアント（例えば、第三者アプリケーション）がアクセスをリクエストできるレイヤーを提供し、ユーザーの資格情報や静的な bearer トークンの代わりにすることで、従来のクライアント - サーバー認証モデルを改善します。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. クライアントはtoken endpointを呼び出します。次のパラメーターはリクエストボディ内の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. クライアントはAuthorization Code Grantに記載されている手順に従い、リクエストされたscopeパラメータの一部としてoffline_accessを指定します。
2. クライアントは、Authorization Code Grantの最終手順で返されたrefresh_tokenを保存する必要があります。
3. アクセストークンが期限切れになった場合、クライアントは次のパラメーターを使用してtoken endpointエンドポイントを呼び出すことでトークンを更新することができます：
   • 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エラーページが返されます。

エラーコード