外部アプリケーションの設定

外部アプリケーションは、Foundry で構築されたワークフローから外部システムへの OAuth 2.0 接続を管理するための手段を管理者に提供します。外部アプリケーションはコントロールパネルの組織レベルで管理されます。

外部アプリケーションは、Foundry が OAuth 2.0 クライアント として動作するために必要な設定のバンドルを表します。アプリケーションは、OAuth 2.0 サーバー として動作できる別のシステムへのリクエストを行います。

Foundry の外部アプリケーションは、OAuth 2.0 承認コードグラント (外部) タイプのみをサポートします。
OAuth 2.0 クライアント資格情報グラントを設定するには、Webhook 内で手動でハンドシェイクプロセスを確立するためのこれらのリソースに従ってください。

外部アプリケーションの作成

外部アプリケーションを作成するには、まずコントロールパネルの 組織設定 の下にある 外部アプリケーション に移動します。複数の組織にアクセスできる場合は、外部アプリケーションを作成したい組織を選択してください。データ接続でソースを設定する権限を持つこの組織のすべてのユーザーは、その接続の認証メカニズムとして任意の外部アプリケーションを選択することができます。

外部アプリケーション ページを表示するには、コントロールパネルの 組織管理者 ロールにデフォルトで付与されている "外部アプリケーションの管理" ワークフローへのアクセスが必要です。

役割の設定について詳しく学ぶ。

新規アプリケーション を選択し、必要な入力を提供して外部アプリケーションを設定します。詳細な設定オプションは以下に記載されています。

設定オプション

以下の設定オプションは、クラウドベースとオンプレミスの OAuth 2.0 サーバーの両方に適用されます。

直接クラウド接続の設定オプション

OAuth 2.0 サーバーがインターネット経由で到達可能な場合は、外部接続の設定時に直接接続を使用することを推奨します。

オンプレミスの OAuth サーバーの設定オプション

オンプレミスの設定は、OAuth サーバーがプライベートネットワーク内にあり、直接のインターネット接続を介して到達できない場合にのみ使用するべきです。

プライベートネットワーク内の OAuth 2.0 サーバーに接続する

一部の OAuth 2.0 サーバーは公開インターネットに露出していないため、OAuth 2.0 ハンドシェイクリクエストは、サーバーに接続するための エージェントランタイム を使用したカスタム REST API ソースを経由してルーティングする必要があります。この方法は、OAuth 2.0 ハンドシェイクを実行するために使用される独自のリクエストを書く必要があります。

最初のステップは、OAuth2 サーバーに接続できる REST API ソースを作成することです。例えば、ドメインとクライアントシークレットでソースを設定するかもしれません：

次に、OAuth 2.0 サーバーの /token エンドポイントを呼び出すことができるその REST API ソース上に Webhook を作成する必要があります。オプションで、トークンを再読み込みできる 2つ目の Webhook を作成することもできます。

以下の例は、cURL を使用した仮想の OAuth 2.0 サーバーへの OAuth 2.0 ハンドシェイクリクエストの例を示しています：

curl -XPOST 'https://<oauth-server>/token'
    -H 'Content-Type: application/json'
    # クライアントID、クライアントシークレット、コードを指定してJSON形式でPOSTリクエストを送信
    -d '{"client_id":"8b3df622e71449519cd9b0160b9e39f7", \
         "client_secret":"04011f337b984df0ad8c58a50f9e91f5", \
         "code":"a8ec5e83728e480fa6bfda4eb8e122a3"}'

以下のようなレスポンスが表示される可能性があります：

{
  "access_token":"1846149cf5774c3d8eaeb18b75f7178d", // アクセストークン
  "refresh_token": "1846149cf5774c3d8eaeb18b75f7178d", // 再読み込みトークン
  "token_type":"bearer", // トークンタイプ
  "scope":"<comma-delimited-set-of-scopes>", // スコープ（カンマで区切られたセット）
  "expires_in": "3600" // 有効期限（秒）
}

もう一つの例として、典型的な更新リクエストは次のようになります：

curl -XPOST 'https://<oauth-server>/refresh_token'
    -H 'Content-Type: application/json'
    # クライアントID、クライアントシークレット、再読み込みトークンを指定してJSONデータを送信
    -d '{"client_id":"8b3df622e71449519cd9b0160b9e39f7", \
         "client_secret":"04011f337b984df0ad8c58a50f9e91f5", \
         "refresh_token":"a8ec5e83728e480fa6bfda4eb8e122a3"}'

応答は上記のハンドシェイク応答と同じになります。

Copied!
1
2
3
4
5
6
7
{ 
  "access_token":"1846149cf5774c3d8eaeb18b75f7178d", // アクセストークン
  "refresh_token": "1846149cf5774c3d8eaeb18b75f7178d", // 再読み込みトークン
  "token_type":"bearer", // トークンタイプ
  "scope":"session", // スコープ
  "expires_in": "3600" // トークンの有効期限（秒）
}

Foundry で OAuth 2.0 ハンドシェイクを実装するために必要なトークンと再読み込みトークンの Webhook を作成する方法については、次のセクションの手順を参照してください。

トークン Webhook

トークン Webhook は、client_id、redirect_uri、および authorization_code が与えられた場合に、OAuth 2.0 サーバーの /token エンドポイントへのリクエストを実装し、有効なトークンを取得する必要があります。トークン Webhook には、以下に示す入力パラメーターと出力パラメーターが必要です。Webhook パラメーターについての詳細を学ぶ。

以下は、標準的な OAuth 2.0 サーバートークンリクエストを示すリクエスト設定の例です。

また、Webhook フォームの本文に grant_type=authorization_code を含める必要があります。OAuth 2.0 サーバーのドキュメントを確認して、追加の必須設定を確認してください。

再読み込みトークン Webhook

トークン Webhook を作成した後、以下に示す入力パラメーターと出力パラメーターを使用して、再読み込みトークンフローのための2つ目の Webhook を作成する必要があります。Webhook は、refresh_token および client_id が与えられた場合に、新しいトークンを取得するための /token エンドポイントへのリクエストを実装する必要があります。

以下は、標準的な OAuth 2.0 サーバー再読み込みリクエストを示すリクエスト設定の例です。

また、Webhook フォームの本文に grant_type=refresh_token を含める必要があります。OAuth 2.0 サーバーのドキュメントを確認して、追加の必須設定を確認してください。

利用可能な出力パラメーターは、トークン Webhook のパラメーターと同じです。

アウトバウンドアプリケーションの管理

アウトバウンドアプリケーションを作成すると、その組織内のすべてのユーザーが、Data Connection の REST API ソース の認証方法として使用できるようになります。アウトバウンドアプリケーションを管理する権限を持つ管理者には、以下のオプションが利用可能です。

アウトバウンドアプリケーションの削除

アウトバウンドアプリケーションを削除すると、アプリケーションを認証したすべてのユーザーの保存されたトークンと再読み込みトークンが完全に削除されます。また、クライアントシークレットを含むアプリケーション設定も完全に削除されます。この操作は元に戻すことができません。

アウトバウンドアプリケーションのリセット

アウトバウンドアプリケーションをリセットすると、アプリケーションを認証したすべてのユーザーの保存されたトークンと再読み込みトークンが完全に削除されます。これにより、アプリケーションは、まだインタラクティブな認証フローを完了していない状態に戻ります。次回、ユーザーがこのアウトバウンドアプリケーションからトークンが必要なワークフローを実行しようとすると、再度認証フローを完了するよう求められます。

アウトバウンドアプリケーションの有効化

アウトバウンドアプリケーションを有効にすると、ユーザーはこの外部システムに対してインタラクティブな認証フローを実行できるようになります。アプリケーションを無効にすると、以前に保存されたトークンと再読み込みトークンが使用できなくなります。ただし、これらのトークンは削除されず、アプリケーションが再度有効にされた後に再び使用できるようになります。

以前にアプリケーションを認証していない新規ユーザーは、アウトバウンドアプリケーションが無効になっている間はインタラクティブな認証フローを実行できません。

新規作成されたアプリケーションはデフォルトで有効になっており、作成後に無効にすることができます。

Data Connection でのアウトバウンドアプリケーションの使用

アウトバウンドアプリケーションが作成され、有効化されると、REST API ソースのドメインの認証方法として使用できます。ドメインの設定時に、OAuth 2.0 を選択し、ドロップダウンから目的のアウトバウンドアプリケーションを選択します。

OAuth 2.0 が設定されたドメインを使用する Webhook は、それを初めて実行しようとするユーザーごとにインタラクティブなプロンプトが表示されます。Webhook は、ほとんどの場合、Workshop からの アクション を介して呼び出されます。この場合、Workshop でアクションを実行すると、ユーザーは OAuth 2.0 サーバーの認証ページを表示するポップアップウィンドウを見ることになり、Foundry がこのシステムと代わりにやりとりできるように認証するよう求められます。

トークン再読み込みワークフローが設定されている場合、外部システムで認証が取り消された場合やアウトバウンドアプリケーションがリセットされた場合を除いて、ユーザーはこのプロンプトを再度表示することはほとんどありません。再読み込みワークフローが設定されていない場合、エンドユーザーは結果として得られるトークンが期限切れになるたびに認証ポップアップを表示することになります。トークンは通常、数分から数時間で期限切れになるため、再読み込みフローを使用してユーザーエクスペリエンスを向上させることをお勧めします。