機械翻訳について

OAuth保護パターン

「RESTアダプタ」を使用して、OAuth保護を使用して次の共通パターンを実装できます。

OAuthカスタム2つのレッグ・トークン・ベース認証で保護されたREST APIを使用するように「RESTアダプタ」を構成

この項では、OAuthカスタム2レッグ・フロー・セキュリティ・ポリシーの概要を示します。 このポリシーは、Basic Authenticationセキュリティ・ポリシーで十分でない場合に役立ちます。

ほとんどのHTTPサービスは、通常、OAuth認可フレームワークを使用してリソースを保護します。 OAuth 2.0仕様に従って、OAuth 2.0認可フレームワークを使用すると、サード・パーティ・アプリケーションは、リソース所有者とHTTPサービス間の承認対話をオーケストレーションするか、サード・パーティ・アプリケーションが独自のアクセス権を取得できるようにすることで、リソース所有者のかわりにHTTPサービスへのアクセスを制限できます。

「RESTアダプタ」では、OAuthサービスを含むREST対応のサービスと統合できます。 OAuthエンドポイントと対話するには、Oracle Integrationの接続ページで1回の再利用可能な接続を作成する必要があります。 ベースURIおよびセキュリティ構成で接続を構成します。

次のセキュリティ・ポリシー・オプションは、「RESTアダプタ」の接続ページで使用できます。oic3_oauth2leg.pngの説明は以下のとおりです
「図oic3_oauth2leg.pngの説明」

各オプションは異なるコンテキストで適用でき、有効なアクセス・トークンをネゴシエーションおよび取得するために使用されます。 RESTサービス・プロバイダのドキュメントを読み、該当するポリシーを確認してください。

次のセクションでは、「OAuthカスタム2足歩行」としてコールされるOAuthカスタム2つのレッグ・フローで使用できる柔軟なOAuthセキュリティ・ポリシーについて説明します。

OAuth 2.0仕様では、次のOAuthフローを定義しています:

  • OAuthクライアント資格証明

  • OAuthリソース所有者のパスワード資格証明

  • OAuth認証コード資格証明

  • OAuth暗黙の許可認可

「OAuthクライアントの資格証明」および「OAuthのリソース所有者のパスワード資格証明」オプションは、クライアント・アプリケーションがリソース所有者の操作なしで直接アクセスを取得するため、OAuthカスタムの2つのフローとして分類されます。

HTTPリクエストは、通常、クライアント・アプリケーション資格証明を渡す許可サーバーに送信されます(これらはリソース所有者の資格証明と異なり、許可サーバーにクライアント・アプリケーションを登録することで取得できます)、付与タイプと付与スコープおよびその他の必須プロパティです。 認可サーバーは、アクセス・トークン(オプションでトークン・タイプ、有効期限および場合によってはリフレッシュ・トークン)を送信することで、このリクエストに応答します。

次の例では、Twitter (OAuth2をサポートする一般的なマイクロ・ブログ・サイト)を使用したサンプル・アクセス・トークン・リクエストについて説明します。 Twitter開発者ドキュメントの詳細は、https://dev.twitter.com/oauth/application-onlyを参照してください。 
POST /oauth2/token HTTP/1.1
Host: api.twitter.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic a3NmM1yRnFweAx==

grant_type=client_credentials

Twitter開発者ドキュメントによると、このリクエストは、Twitterからアクセス・トークンを取得するために必要です。 HTTP Basic認証ヘッダーは、クライアントIDおよびクライアント・シークレットを使用して作成されます。

リクエストが正しくフォーマットされている場合、サーバーはJSONエンコードされたペイロードで応答します。 これはかなり単純です。 
{"token_type":"bearer","access_token":"AAAAAAAAAA"}

次のステップでは、このシナリオのコンテキストにおける「OAuthカスタム2足歩行」セキュリティ・ポリシーと各フィールドについて説明します。

ステップ1: アクセス・トークン・リクエストを構成


「セキュリティ・ポリシー」フィールドには、OAuth Custom Two Legged Flowが選択されています。 この下には、テキスト例を含む「アクセス・トークン・リクエスト」フィールドがあります。

「アクセス・トークン・リクエスト」フィールドは、アクセス・トークンのフェッチに使用されるHTTPリクエストのURI構文を使用して形成されます。 URI構文はcURLに似ていますが、より基本的なもので、次のオプションのみをサポートしています。

オプション 値 説明 必須
-X GET | PUT | POST アクセス・トークン・リクエストのHTTP動詞。 はい
-H -H “key: value” 説明に従って、各ヘッダー・キー値ペアを追加します。 複数のヘッダーが存在する場合があります。 いいえ
-d -d ‘data-as-string’ 一重引用符で囲まれた文字列データ。 データ文字列内の引用符をエスケープします。 いいえ
URI Uri(クォート内) - - はい
-dオプションで指定したパラメータは、URLでエンコードする必要があります。 たとえば、client_idが次の値であるとします: 
qwerty&r=123=&q=asdf
URLエンコーダ・ツールを使用して、この値をURLエンコードする必要があります。 パラメータは、-dデータを作成する前にURLでエンコードする必要があります。 これは、client_secret、および-dパラメータ全体に組み込むスコープまたはその他の追加値にも適用されます。 たとえば: 
client_id = "qwerty&r=123=&q=asdf"

client_secret = "zxcvb&q=12345&=7890"
アクセス・トークン・リクエスト: 
-X POST -H 'Content-Type: application/x-www-form-urlencoded' -d 
'client_secret=zxcvb%26q%3D12345%26%3D7890&grant_type=authorization_code&redirect_uri=${redirect_uri}&client_id=qwerty%26r%3D123%3D%26q%3Dasdf' 
https://webhook.site/44ffa856-9459-4bb5-b8db-c0ed0d3b227f
データが問合せパラメータに含まれている必要がある場合:
-X POST -H 'Content-Type: application/x-www-form-urlencoded' 
'https://webhook.site/44ffa856-9459-4bb5-b8db-c0ed0d3b227f?client_secret=zxcvb%26q%3D12345%26%3D7890&grant_type=authorization_code&redirect_uri=${redirect_uri}&client_id=qwerty%26r%3D123%3D%26q%3Dasdf'
OAuthカスタムの2-leggedフロー・セキュリティ・ポリシーの複数の-dオプションを、次のように単一の-dに圧縮できます:
-d "grant_type=client_credentials&client_id=123"

ノート:

  • その他のcurlオプションはサポートされていません。

  • このリクエストを作成する最も簡単な方法は、アクセス・トークンを取得して「コード・スニペット/コードを生成」オプションを使用してcurl構文を取得するために、postmanなどの無料ツールを使用してHTTPリクエストを作成および検証することです。 URI構文を取得するには、先頭からcurlを削除します。 次の例は、URI構文を示しています: 

    -X POST -H "Content-Type: application/x-www-form-urlencoded" -H "Authorization: 
Basic a3NmM0J6czJG==" -d 'grant_type=client_credentials' 
https://api.twitter.com/oauth2/token
URI構文を使用すると、アクセス・トークン・リクエストを制御できます。 次に、一般的なアクセス・トークン・レスポンスを示します。 
{
  "access_token": "1-253912-240049694-f85c1d679211c",
  "expires_in": 21599,
  "token_type": "Bearer",
  "refresh_token": "5707efdf04912f53b61cb5ec5dc7f166"
}

ステップ2: アクセス・トークン・レスポンスからのトークンの解析と抽出

ノート:

アクセス・トークン・レスポンスのプロパティが以前に強調表示されている場合は、このステップをスキップします。

リクエストが正常な場合、認可サーバーは成功ステータスのHTTPレスポンスを返します。 レスポンスにはアクセス・トークンが含まれ、トークンのタイプ、その有効期限、前に説明したリフレッシュ・トークンなど、トークンに関するいくつかの操作詳細が含まれる場合もあります。


oic3_custom_2_leg_flow3.pngの説明は以下のとおりです
「図oic3_custom_2_leg_flow3.pngの説明」

デフォルトでは、$variablesは、関連するトークンを含むプロパティ名に次のようにマップされます:

プロパティ名 名前を持つプロパティへのデフォルト・マッピング プロパティ名の例
$access_token access.[tT]oken access_token
$refresh_token refresh.[tT]oken refresh_token
$expiry expires_in expires_in
$token_type token.?[tT]ype token_type

デフォルト値はサンプル・レスポンスと一致します。 したがって、このステップは必須ではなく、スキップできます。

ただし、アクセス・トークン・レスポンスが標準でない場合は、アクセス・トークン・レスポンスからトークンをフェッチするルールを定義する必要があります。

たとえば、アクセス・トークン・レスポンスが次のようになっているとします:
{   "access_token": "1-253912-240049694-f85c1d679211c", "expiry": 21599, 
"token_type": "Bearer",   "extended_token": "5707efdf04912f53b61cb5ec5dc7f166" }

この場合、認可サーバーはレスポンスを返しますが、有効期限とリフレッシュ・トークンの指定方法が異なります。 このステップは、これらのプロパティを変数にマップするために必要です。

変数名 名前を持つプロパティへのデフォルト・マッピング プロパティ名の例
$refresh_token extended_token extended_token
$expiry Expiry Expiry

変数は、値が割り当てられると、${variable}構文を使用して構成で使用できます。 たとえば、$access_tokenには、アクセス・トークン・リクエストが行われた後に値が割り当てられます。 この変数の値は、access_tokenの使用方法を指定するとき、または後でrefresh_token_requestを指定するときに役立ちます。

ステップ3: アクセス・トークンの使用法(重要)

アクセス・トークンの使用法では、アクセス・トークンを渡してリソースにアクセスする方法について説明します。 この情報は、Oracle Integrationがネゴシエートされたアクセス・トークンをエンドポイントに渡す方法を管理するため、この情報を慎重に入力してください。


oic3_custom_2_leg_flow4_old.pngの説明は以下のとおりです
「図oic3_custom_2_leg_flow4_old.pngの説明」

このフィールドのデフォルト値は次のとおりです:

-H Authorization: ${token_type} ${access_token}

実行時に、${token_type}および${access_token}の値はフェッチ・ルールに基づいて取得され、エンドポイント・リクエストとともに認可ヘッダーとして渡されます。

リテラル値は、次のように使用することもできます: 
-H API-Token: Bearer ${access_token}
アクセス・トークンの使用 説明 例 
-H Authorization: ${token_type} ${access_token}
 アクセス・トークンは、保護されたリソースにアクセスするために実行時にヘッダーとして渡されます。 -H Authorization: Bearer AASDFADADX 
?api_key=${access_token}
 アクセス・トークンは、保護されたリソースにアクセスするために実行時に問合せパラメータとして渡されます。 http://someapi.com/employee?api_key=ASDFADAX

ステップ4: トークン・リクエストのリフレッシュ(オプション)

一部のプロバイダは、特定のアクセス・トークンをリフレッシュするメカニズムを提供します。 この種のメソッドは、一般的に、リソース所有者のパスワード資格証明(ROPC)フローの一部です。 ただし、指定で別途指定されている場合でも、クライアント資格証明でもこれを使用するインスタンスがあります。

リフレッシュ・トークン・リクエストは通常、リフレッシュ・トークンを取得し、新しいアクセス・トークンをレスポンスとして、トークンのタイプ、その有効期限、別のリフレッシュ・トークンなどの操作属性とともに返します。

リフレッシュ・トークン・リクエストは、アクセス・トークン・リクエストに似た構文でも指定し、同じルールに規定する必要があります。

サンプルのリフレッシュ・トークン・リクエストは次のとおりです:

-X POST 'https://sample.com/oauth2/token?refresh_token=${refresh_token}
&client_id=[YOUR_CLEINT_ID]&client_secret=[YOUR_CLIENT_SECRET]&grant_type=refresh_token'

このリクエストには、実行時に現在のリフレッシュ・トークンの実際の値で置換される変数が含まれています。

「接続セキュリティの構成」を参照してください。

OAuthカスタム3つのレッグ・フロー・トークン・ベース認証で保護されたREST APIを使用するように「RESTアダプタ」を構成

この項では、OAuth Custom Three Legged Flowセキュリティ・ポリシーの概要を説明します。

次のステップは、一般的なOAuth認証コードの資格証明フローの一部として実行されます。


icsre_dt_001.pngの説明は以下のとおりです
「図icsre_dt_001.pngの説明」

ステップ 説明
1 ユーザーは、認可リクエストURIを指定します。 ユーザーは、ユーザー・エージェント(ブラウザ)によって認可URIにリダイレクトされます。
2 リソース所有者は、認証のためにログインし、そのリソースにアクセスするためのクライアント・アプリケーションへの同意を提供します。
3 認可サーバーは、クライアント・アプリケーションにコールバック・リクエストを送信し、認可コードを送信します。
4 クライアント・アプリケーションは、リクエストから認証コードを抽出し、それを使用してアクセス・サーバーに別のリクエストを送信してアクセス・トークンを取得します。
5 認可サーバーは、アクセス・トークンをクライアント・アプリケーションに送信することによって、アクセス・トークン・リクエストに応答します。
6 クライアント・アプリケーションは、アクセス・トークンを使用して保護されたリソースをリクエストします。
このフローは、OAuth仕様で定義されます。 ただし、フローの各ステップの実行方法は、OAuthフローを実装する認可サーバーによって決定されます。 このフローにはいくつかのバリエーションがあります。

  • OAuthプロバイダは、ユーザーが認可URIにリダイレクトされたときに、一部の問合せパラメータが渡されることを想定しています。

  • プロバイダが承認コードを別のものと呼びます。

  • アクセス・トークンのコールには、認可コードを含める必要があります。 ただし、一部のプロバイダでは、ヘッダーまたは問合せパラメータとして、またはデータの一部として想定される場合があります。

  • アクセス・トークン・レスポンスも慎重です。 一部のプロバイダは、リフレッシュ・トークンを返す場合があります(たとえば、extended_tokenまたはその他のものをコールします)。 プロバイダは有効期限を返すことが知られていますが、一部のプロバイダはJWTトークンを返し、そこで有効期限はトークン内にクレームとして埋め込まれます。

  • プロバイダは、カスタム・トークン・タイプを宣言することもできます。

  • アクセス・トークンをリフレッシュするコールは、プロバイダごとに異なる場合もあります。

  • アクセス・トークンを使用してリソースにアクセスするコールも異なる場合があります。 プロバイダは、ヘッダーまたは問合せパラメータであると想定できます。 一部のプロバイダは、トークンを認可ヘッダーとして渡すように要求します。 カスタム・ヘッダーを想定するプロバイダはほとんどありません。

「RESTアダプタ」には、「OAuth認証コード資格証明フロー」と呼ばれるセキュリティ・ポリシーが用意されています。 このポリシーは、OAuth仕様に示すように、OAuthの特定の実装を提供します。 その他のすべての場合は、「OAuthカスタム3足歩行」を使用してこれらのカスタマイズに対応できます。

ステップ1: 承認リクエストの構成


oic3_custom_3_leg_flow.pngの説明は以下のとおりです
「図oic3_custom_3_leg_flow.pngの説明」

リソース所有者が認証し、同意を提供する認可URIを「承認リクエスト」フィールドに指定します。 通常、クライアントIDおよびスコープは、認可サーバーがコールバックおよび認証コードを送信する必要があるリダイレクトURIを持つ問合せパラメータとして渡されます。

Oracle Integrationにはこのコールバックを受け取る固定エンドポイントがあるため、URIを直接指定するか、プラットフォームによって自動的に解決される参照${refresh_token}を渡すことができます。 たとえば: 
https://AUTH_URI?response_type=code&client_id=YOUR_CLIENT_ID &redirect_uri=${redirect_uri}&scope=app_scope

ステップ2: アクセス・トークン・リクエストを構成

リソース所有者が同意すると、認可サーバーはクライアント・アプリケーションに、認可コードとともにコールバックを送信します。 次のステップは、クライアント・アプリケーションがこの認可コードを使用してアクセス・トークンのリクエストを送信することです。

認可サーバーがコード以外の名前のプロパティで認可コードを返す場合は、$auth_codeを使用してプロパティ名をマップする必要があります。

アクセス・トークン・リクエストは、アクセス・トークンの呼出しに使用されます。 フローが実行されるまで解決されない認証コードを送信すると想定されます。 したがって、認可コードは、リクエストで${auth_code}として参照によって渡されます。

アクセス・トークン・リクエストを作成するためのルールは、「OAuthカスタム2足歩行」オプションから変更されません。

「アクセス・トークン・リクエスト」値は、アクセス・トークンのフェッチに使用されるHTTPリクエストのURI構文を使用して形成されます。 URI構文はcURLに似ていますが、より基本的なもので、次のオプションのみをサポートしています。

オプション 値 説明 必須
-X GET | PUT | POST アクセス・トークン・リクエストのHTTP動詞。 はい
-H -H “key: value” 説明に従って、各ヘッダー・キー値ペアを追加します。 複数のヘッダーが存在する場合があります。 いいえ
-d -d ‘data-as-string’ 一重引用符で囲まれた文字列データ。 データ文字列内の引用符をエスケープします。 いいえ
URI Uri(クォート内) - - はい
-dオプションで指定したパラメータは、URLでエンコードする必要があります。 たとえば、client_idが次の値であるとします: 
qwerty&r=123=&q=asdf
URLエンコーダ・ツールを使用して、この値をURLエンコードする必要があります。 パラメータは、-dデータを作成する前にURLでエンコードする必要があります。 これは、client_secret、および-dパラメータ全体に組み込むスコープまたはその他の追加値にも適用されます。 たとえば: 
client_id = "qwerty&r=123=&q=asdf"

client_secret = "zxcvb&q=12345&=7890"
アクセス・トークン・リクエスト: 
-X POST -H 'Content-Type: application/x-www-form-urlencoded' -d 
'client_secret=zxcvb%26q%3D12345%26%3D7890&grant_type=authorization_code&redirect_uri=${redirect_uri}&client_id=qwerty%26r%3D123%3D%26q%3Dasdf' 
https://webhook.site/44ffa856-9459-4bb5-b8db-c0ed0d3b227f
データが問合せパラメータに含まれている必要がある場合:
-X POST -H 'Content-Type: application/x-www-form-urlencoded' 
'https://webhook.site/44ffa856-9459-4bb5-b8db-c0ed0d3b227f?client_secret=zxcvb%26q%3D12345%26%3D7890&grant_type=authorization_code&redirect_uri=${redirect_uri}&client_id=qwerty%26r%3D123%3D%26q%3Dasdf'
OAuth Custom Three Legged Flowセキュリティ・ポリシー内の複数の-dオプションは、次のように単一の-dに圧縮できます:
-d "grant_type=client_credentials&client_id=123"

ノート:

  • その他のcurlオプションはサポートされていません。

  • このリクエストを作成する最も簡単な方法は、POSTMANなどの無料ツールを使用してHTTPリクエストを構築および検証してアクセス・トークンを取得し、「コード・スニペット/コードを生成」オプションを使用してcURL構文を取得することです。 URI構文を取得するには、先頭からcurlを削除します。 次の例は、URI構文を示しています: 

    -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'false' 'https://access_token_URI?code=${auth_code}&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&redirect_uri=${redirect_uri}&grant_type=authorization_code'

ステップ3: オプションで、リフレッシュ・トークン・リクエストを構成

アクセス・トークン・リクエストと同様に、認可サーバーがリフレッシュをサポートしている場合は、URI構文でリフレッシュ・トークン・リクエストを指定します。

ステップ4: 中間トークンのフェッチ規則を定義

デフォルトでは、$variablesは、関連するトークンを含むプロパティ名に次のようにマップされます:

プロパティ名 名前を持つプロパティへのデフォルト・マッピング プロパティ名の例
$auth_code code code
$access_token access.[tT]oken access_token
$refresh_token refresh.[tT]oken refresh_token
$token_type token.?[tT]ype token_type
$expiry expires_in expires_in

このステップは必須ではなく、スキップできます。

ただし、アクセス・トークン・レスポンスが標準でない場合は、アクセス・トークン・レスポンスからトークンをフェッチするルールを定義する必要があります。

ステップ5: アクセス・トークンの使用法を定義する(重要)

アクセス・トークンの使用法では、アクセス・トークンを渡してリソースにアクセスする方法について説明します。 この情報は、Oracle Integrationがネゴシエートされたアクセス・トークンをエンドポイントに渡す方法を管理するため、この情報を慎重に入力してください。

「接続セキュリティの構成」を参照してください。

OAuth 1.0 One-Legged認証で保護されているREST APIを使用するようにRESTアダプタを構成

この項では、接続ページのOAuth 1.0 One-Legged認証セキュリティ・ポリシーの概要について説明します。 このプロトコルにより、Webサイトやアプリケーション(コンシューマ)は、サービス・プロバイダの資格証明をコンシューマに開示することなく、APIを通じてWebサービス(サービス・プロバイダ)から保護されたリソースにアクセスできます。

ノート:

このポリシーでは、カスタマイズは必要ありません。 これは、カスタム2足およびカスタム3足OAuthポリシーとは異なり、標準のOAuthポリシーです。
このセキュリティ・ポリシーは、次のようなサービス・プロバイダで使用できます:

  • Oracle NetSuiteは、OAuth 1.0 One-Legged Authenticationで保護されているREST APIとしてリストア・レットを公開できます。 たとえば: 

    https://rest.netsuite.com/app/site/hosting/restlet.nl?script=474&deploy=1

    このレセレットにアクセスするには、Oracle NetSuiteのメンバーである必要があります。

    このレシートはHTMLで挨拶を返します。

  • Twitterアカウントは、OAuth 1.0 One-Legged認証で保護できます。

接続ページの資格証明ダイアログで、次のフィールドを構成します。 これらの資格証明は、サービス・プロバイダ(Oracle NetSuiteまたはTwitter)によって提供されます。


oic3_one_legged_auth2.pngの説明は以下のとおりです
「図oic3_one_legged_auth2.pngの説明」

  • 「コンシューマ・キー」 - リクエストを行うクライアントを識別するキーを指定します。

  • 「コンシューマ・シークレット」 - リクエストを行うクライアントを認証するコンシューマ・シークレットを指定します。

  • 「トークン」 - 保護されたリソースにアクセスするトークンを指定します。

  • 「トークン・シークレット」 - リクエストのシグネチャを生成するトークン・シークレットを指定します。

  • 「レルム」 - アカウントを識別するレルムを指定します。

「接続セキュリティの構成」を参照してください。

クライアント・アプリケーションでOAuthで保護されたREST APIとして公開された統合を使用できるようにします

トリガーとして「RESTアダプタ」を使用して構成されたOracle Integrationの統合は、OAuthで保護されたRESTリソースとして自動的に公開されます。 これらの統合/リソースは、OAuthアクセス・トークンを使用して消費することができます。 OAuthトークンを使用してOracle Integrationエンドポイントにアクセスするには、まずトークンを取得する必要があります。

「Oracle Integrationフローを起動するための認証リクエスト」を参照してください。