注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。
OAuth 2.0 認可コードグラントを使用してアウトバウンドアプリケーションを設定する
アウトバウンドアプリケーションを使用すると、管理者は Foundry で構築したワークフローから外部システムへの OAuth 2.0 接続を管理できます。アウトバウンドアプリケーションは、Control Panel で組織レベルで管理します。
アウトバウンドアプリケーションは、Foundry が OAuth 2.0 のクライアントとして動作するために必要な設定をまとめたものです。このアプリケーションは、OAuth 2.0 のサーバーとして動作できる別のシステムにリクエストを送信します。
Foundry のアウトバウンドアプリケーションは、OAuth 2.0 認可コードグラント ↗ の種類のみをサポートします。 OAuth 2.0 クライアント資格情報グラントを設定するには、こちらのリソースに従い、Webhook 内でハンドシェイクプロセスを手動で確立してください。
アウトバウンドアプリケーションは、Agent プロキシエグレスポリシーを使用した、プライベートネットワーク上の OAuth 2.0 サーバーへの接続をサポートします。これにより、Foundry はネットワークにインストールされた Data Connection Agent を経由してトラフィックをルーティングできます。詳細は、エグレスポリシーの設定オプションのドキュメントを参照してください。
エグレスポリシーが制御するのは、Foundry が OAuth 2.0 サーバーに接続する方法のみです。認可コードグラントフローを完了する際、認可ページはお使いのコンピューターのブラウザーで開くため、認可を開始するコンピューターにも OAuth 2.0 サーバーへのネットワークアクセスが必要です。
アウトバウンドアプリケーションを作成する
アウトバウンドアプリケーションを作成するには、まず Control Panel の組織の設定にあるアウトバウンドのアプリケーションに移動します。複数の組織にアクセスできる場合は、アウトバウンドアプリケーションを作成する組織を必ず選択してください。この組織のユーザーのうち、Data Connection でソースを設定する権限を持つすべてのユーザーは、接続の認可の仕組みとして任意のアウトバウンドアプリケーションを選択できます。
アウトバウンドのアプリケーションページを表示するには、「アウトバウンドアプリケーションの管理」ワークフローへのアクセス権が必要です。このアクセス権は、Control Panel の組織管理者ロールにデフォルトで付与されています。
ロールの設定については、詳しくはこちらをご覧ください。
新しいアプリケーションを追加を選択し、必要な入力を指定してアウトバウンドアプリケーションを設定します。設定オプションの詳細は以下のとおりです。
設定オプション
アウトバウンドアプリケーションを作成する際は、以下の設定オプションを利用できます。
| オプション | 必須 | 説明 |
|---|---|---|
| 認可ページの URL | はい | OAuth 2.0 プロバイダーの認可エンドポイント ↗です。通常、この URL は https://oauth2-server.com/authorize のような形式で、ほとんどの SaaS サービスでは公開ドキュメントに記載されています。 |
| トークンエンドポイントの URL | はい | OAuth 2.0 プロバイダーのトークンエンドポイント ↗です。通常、この URL は https://oauth2-server.com/token のような形式で、ほとんどの SaaS サービスでは公開ドキュメントに記載されています。 |
| エグレスポリシー | はい | OAuth 2.0 サーバーに接続するには、トークンエンドポイントの URL への接続を許可するエグレスポリシーを作成し、アタッチする必要があります。Foundry のネットワークからアクセスできるサーバーには直接接続エグレスポリシーを、プライベートネットワーク上のサーバーには Agent プロキシエグレスポリシーを使用します。エグレスはエンロールメントごとに管理されます。 |
| アプリケーション名 | はい | このアウトバウンドアプリケーションのユーザー向けの名前です。ソースの認証を設定する際、Data Connection でアウトバウンドアプリケーションを選択するときに表示されます。 |
| 説明 | いいえ | アウトバウンドアプリケーションの説明です。 |
| 承認プロンプト | はい | 認可グラントフローを使用する際、外部 OAuth 2.0 プロバイダーのログインプロンプトを表示するポップアップウィンドウが開く前に、このテキストが表示されます。 |
| クライアントID | はい | OAuth 2.0 プロバイダーのクライアント識別子 ↗です。外部システムによっては、クライアントIDを別の用語で呼ぶ場合があります。 |
| クライアントシークレット | はい | OAuth 2.0 プロバイダーのクライアントシークレット ↗です。外部システムによっては、クライアントシークレットを別の用語で呼ぶ場合があります。 |
| スコープ | はい | 指定したクライアントIDに対応する、OAuth 2.0 サーバーで設定されたスコープのリストです。ここで入力するリストは、外部システムの管理インターフェースに記載されたものと一致する必要があります。OAuth 2.0 サーバーでの認可時に空のスコープリストを指定する場合は、スコープを空白のままにできます。 |
| アクセストークンの有効期限 | いいえ | 任意のアクセストークンの有効期限です。通常、この値は認可グラントフローの一環として OAuth 2.0 サーバーから返されます。サーバーがアクセストークンの有効期限を返す場合、ここで入力した値は無視されます。 |
| PKCE を有効化 | いいえ | 任意の切り替え設定です。有効にすると、アウトバウンドアプリケーションは proof key for code exchange ↗（PKCE）を使用します。PKCE は認可コードグラントの拡張機能であり、追加のセキュリティハンドシェイクによって CSRF および認可コードインジェクション攻撃から保護します。この設定はパブリッククライアントに強く推奨されており、一部の OAuth 2.0 サーバーでは必須です。 |
アウトバウンドアプリケーションを設定する際、Foundry から OAuth 2.0 サーバーに直接到達できる場合は、直接接続の使用を推奨します。クラウドでホストされる Foundry インスタンスの場合、これはインターネットへの直接接続を通じて到達できるサーバーを意味します。
OAuth 2.0 サーバーがプライベートネットワーク上にある場合は、Agent プロキシエグレスポリシーを使用し、ネットワークにインストールされた Data Connection Agent を経由してトラフィックをルーティングできます。これにより、Foundry は OAuth 2.0 サーバーに直接到達できる場合と同じように接続できます。
（レガシー）カスタム Webhook ベースの OAuth 2.0 ハンドシェイク
カスタム Webhook ベースの OAuth 2.0 設定は、開発のレガシー段階にあり、追加の開発は予定されていません。引き続きフルサポートが利用可能です。この設定は、お使いのエンロールメントでは利用できない場合があります。OAuth 2.0 サーバーが標準の認可コード付与フローを実装している場合は、代わりに標準の設定オプションを直接接続または Agent プロキシのエグレスポリシーとともに使用してください。
OAuth 2.0 サーバーが非標準のトークンハンドシェイクを必要とする場合は、カスタム Webhook を使用して OAuth 2.0 フローを手動で実装できます。この方法では、Agent ワーカーを使用してサーバーに接続する REST API ソース経由で、ハンドシェイクリクエストをルーティングします。
| オプション | 必須？ | 説明 |
|---|---|---|
| ソース接続 | はい | Agent ワーカーを使用してネットワーク内の OAuth 2.0 サーバーに接続するように設定された REST API ソースを選択します。 |
| トークンを取得する Webhook | はい | OAuth 2.0 サーバーのトークンエンドポイント ↗を呼び出して、トークンを取得する Webhook です。詳細は以下のセクションを参照してください。 |
| リフレッシュトークンを取得する Webhook | いいえ | OAuth 2.0 サーバーのトークンエンドポイント ↗を呼び出して、トークンを更新する Webhook です。詳細は以下のセクションを参照してください。 |
| 認可ページの URL | はい | OAuth 2.0 プロバイダーの認可エンドポイント ↗です。通常、この URL は https://oauth2-server.com/authorize のような形式です。 |
カスタム Webhook ベースのハンドシェイクを設定するには、次の手順を実行します。
- OAuth 2.0 サーバーに接続できる REST API ソースを作成します。たとえば、サーバーのドメインとクライアントシークレットを使用してソースを設定できます。
- その REST API ソース上に、OAuth 2.0 サーバーの
/tokenエンドポイントを呼び出す Webhook を作成します。必要に応じて、更新フロー用に2個目の Webhook を作成できます。
以降のセクションの手順に従って、トークン用およびリフレッシュトークン用の Webhook を作成します。
トークン用 Webhook
関数として公開された Webhook は、レガシーのカスタム Webhook ベースの OAuth 2.0 アウトバウンドアプリケーションでは使用できません。トークン用および更新用の Webhook を作成する際は、関数の公開が無効になっていることを確認してください。
トークン用 Webhook は、指定された client_id、redirect_uri、authorization_code を使用して有効なトークンを取得するために、OAuth 2.0 サーバーの /token エンドポイントへのリクエストを実装する必要があります。トークン用 Webhook には、以下の入力および出力パラメーターが必要です。Webhook のパラメーターについて詳しくはこちら。
以下は、標準的な OAuth 2.0 サーバーへのトークンリクエストを示すリクエスト設定の例です。
| 入力パラメーター | 必須？ | データ型 |
|---|---|---|
client_id | はい | 文字列 |
redirect_uri | はい | 文字列 |
authorization_code | はい | 文字列 |
code_verifier | いいえ | 文字列 |
また、Webhook のフォーム本文の項目の1つとして grant_type=authorization_code を設定する必要があります。アウトバウンドアプリケーションで PKCE を有効化がオンになっている場合、code_verifier が必要です。その他の必須設定については、OAuth 2.0 サーバーのドキュメントを確認してください。
| 出力パラメーター | 必須？ | データ型 | コメント |
|---|---|---|---|
access_token | はい | 文字列 | |
scope | はい | 文字列 | |
refresh_token | いいえ | 文字列 | すべての OAuth 2.0 サーバーやアプリケーションが、トークンの自動更新を許可するように設定されているわけではありません。リフレッシュトークンが返されない場合、元のトークンの有効期限が切れるたびに、アプリケーションの再認可を求める画面がユーザーに表示されます。 |
expires_in | いいえ | 文字列 | すべての OAuth 2.0 サーバーがこのパラメーターを返すわけではありません。このパラメーターが存在しない場合、または値が返されない場合は、代わりにアウトバウンドアプリケーションで設定されたアクセストークンの有効期限が使用されます。 |
リフレッシュトークン用 Webhook
関数として公開された Webhook は、レガシーのカスタム Webhook ベースの OAuth 2.0 アウトバウンドアプリケーションでは使用できません。トークン用 Webhook とリフレッシュ用 Webhook を作成する際は、関数としての公開が無効になっていることを確認してください。
トークン用 Webhook を作成したら、以下に示す入力パラメーターと出力パラメーターを使用して、リフレッシュトークンフロー用の2つ目の Webhook を作成する必要があります。この Webhook では、refresh_token と client_id を指定して新しいトークンを取得するために、/token エンドポイントへのリクエストを実装する必要があります。
以下は、標準的な OAuth 2.0 サーバーへのリフレッシュリクエストの設定例です。
| 入力パラメーター | 必須かどうか | データ型 |
|---|---|---|
client_id | はい | 文字列 |
refresh_token | はい | 文字列 |
また、Webhook のフォーム本文のエントリーの1つとして grant_type=refresh_token を設定する必要があります。追加で必要な設定については、お使いの OAuth 2.0 サーバーのドキュメントを確認してください。
利用可能な出力パラメーターは、トークン用 Webhook のパラメーターと同じです。
| 出力パラメーター | 必須かどうか | データ型 | コメント |
|---|---|---|---|
access_token | はい | 文字列 | |
scope | はい | 文字列 | |
refresh_token | いいえ | 文字列 | すべての OAuth サーバーやアプリケーションが、トークンの自動更新を許可するように設定されているわけではありません。リフレッシュトークンが返されない場合、元のトークンの有効期限が切れるたびに、アプリケーションの再認可を求めるプロンプトがユーザーに表示されます。 |
expires_in | いいえ | 文字列 | すべての OAuth 2.0 サーバーがこのパラメーターを返すわけではありません。このパラメーターが存在しない場合、または値が返されない場合は、代わりにアウトバウンドアプリケーションのアクセストークンの有効期限が使用されます。 |
認可をテストする
アウトバウンドアプリケーションを保存して有効にすると、自分の認可セクションに、認可済みか認可されていませんかが表示されます。認可されていない場合は、認可を設定を選択すると、アプリケーションをソースにアタッチせずに OAuth 2.0 認可フローをテストできます。このフローを完了すると、アプリケーションを使用するワークフローのために認可が保存されます。
アウトバウンドアプリケーションを管理する
アウトバウンドアプリケーションを作成すると、その組織のすべてのユーザーが、Data Connection の REST API ソースの認可方法として使用できるようになります。アウトバウンドアプリケーションを管理する権限を持つ管理者は、以下のオプションを利用できます。
アウトバウンドアプリケーションを削除する
アウトバウンドアプリケーションを削除すると、そのアプリケーションを認可したすべてのユーザーについて、保存済みのトークンとリフレッシュトークンが完全に削除されます。クライアントシークレットを含むアプリケーションの設定も完全に削除されます。この操作は元に戻せません。
アウトバウンドアプリケーションをリセットする
アウトバウンドアプリケーションをリセットすると、そのアプリケーションを認可したすべてのユーザーについて、保存済みのトークンとリフレッシュトークンが完全に削除されます。これにより、アプリケーションは実質的に、まだ誰も対話型の認可フローを完了していない初期セットアップ直後の状態に戻ります。次回、このアウトバウンドアプリケーションのトークンが必要なワークフローをユーザーが実行しようとすると、認可フローを再度完了するよう求めるプロンプトが表示されます。
アウトバウンドアプリケーションを有効にする
アウトバウンドアプリケーションを有効にすると、ユーザーはこの外部システムに対する対話型の認可フローを実行できます。アプリケーションを無効にすると、以前に保存されたトークンとリフレッシュトークンは使用できなくなります。ただし、これらのトークンは削除されず、アプリケーションを再度有効にすると再び使用できます。
アウトバウンドアプリケーションが無効になっている間は、そのアプリケーションを以前に認可したことのない新しいユーザーは、対話型の認可フローを実行できません。
新しく作成されたアプリケーションはデフォルトで有効になり、作成後にのみ無効にできます。
Data Connection でアウトバウンドアプリケーションを使用する
Functions、Actions、Workshop、AIP Chatbot でアウトバウンドアプリケーションを使用する方法の詳細については、以下のサポートされているワークフローを参照してください。
アウトバウンドアプリケーションは、複数の組織のユーザーによる使用をサポートしていません。複数の組織のユーザーが同じ OAuth 2.0 サーバーに対して認可を行う必要がある場合は、組織ごとのユーザー向けに、異なる REST API ソースを使用する個別のアウトバウンドアプリケーションを作成する必要があります。
アウトバウンドアプリケーションを作成して有効にすると、REST API ソースのドメインの認証方法として使用できます。ドメインを設定する際に、OAuth 2.0 を選択し、ドロップダウンから目的のアウトバウンドアプリケーションを選択します。
OAuth 2.0 が設定されたドメインを使用する Webhook を各ユーザーが初めて実行しようとすると、対話型のプロンプトが表示されます。Webhook は、Workshop から Actions を通じて呼び出されることが最も一般的です。この場合、Workshop でアクションを実行すると、OAuth 2.0 サーバーの認証ページを表示するポップアップウィンドウが開き、ユーザーに代わってこのシステムとやり取りすることを Foundry に許可するよう求められます。
トークンのリフレッシュワークフローが設定されている場合、外部システムで認可が取り消されるか、アウトバウンドアプリケーションがリセットされない限り、このプロンプトがユーザーに再度表示されることはほとんどありません。リフレッシュワークフローが設定されていない場合、発行されたトークンの有効期限が切れるたびに、エンドユーザーに認証ポップアップが表示されます。トークンは数分から数時間で有効期限が切れることが多いため、ユーザー体験を向上させるためにリフレッシュフローの使用を推奨します。
関数ベースのアクションで OAuth 2.0 を使用する Webhook を呼び出すには、アクションのルール設定ページに移動し、最初のルールとして Webhook を直接呼び出し、その後に関数で Webhook のレスポンスを処理します。また、Webhook の呼び出しが関数からの入力を受け取るように設定することもできます。
ユーザーが有効なトークンを持っている限り、アウトバウンドアプリケーションは Automate やスケジュールされた Functions などの自動化されたワークフローでも機能します。ユーザーは、最初に Workshop、AIP Studio、Control Panel などの対話型 UI コンテキストで認可フローを完了する必要があります。自動化されたワークフローが実行される前にリフレッシュトークンの有効期限が切れた場合、ユーザーは対話型 UI コンテキストで再認可する必要があります。
サポートされるワークフロー
REST API ソースにアウトバウンドアプリケーションを設定すると、次の Foundry 機能で OAuth トークンを利用できます。
- 関数：Python および TypeScript v2 関数でソースの OAuth トークンを使用して、コードから直接外部システムに対して認証できます。TypeScript v1 関数では、代わりに Webhook を使用する必要があります。
- 関数ベースのアクション：アクションの基盤となる関数が OAuth 設定済みのソースを呼び出す場合、トークンが自動的に渡されます。
- Webhook の副次的効果：OAuth 設定済みの REST API ソースの Webhook は、送信リクエストにトークンを含めます。
- Workshop：Workshop で適用される、OAuth トークンを必要とするアクションは、有効なトークンが存在しない場合は認可プロンプトを表示し、ユーザーがすでに認可している場合は自動的に動作します。Workshop から直接呼び出される関数（たとえば、関数ベースの変数として、またはウィジェットのコンテンツを設定するために呼び出される関数）は、認可プロンプトを表示できません。Workshop で OAuth を使用するソースを利用するには、関数を関数ベースのアクションでラップします。
- AIP Chatbot：OAuth を使用するアクションツールを呼び出すエージェントは、ほかのワークフローと同じトークンライフサイクルを使用します。