APIゲートウェイ・バック・エンドとしてのログアウトの追加
APIゲートウェイを使用してログアウト・バック・エンドを定義する方法を確認します。
一般的な要件は、APIクライアントがアクセス・トークンを取り消してクリーンにログアウトする機能を提供し、他のURLをコールして追加のログアウト後のタスクを実行できる可能性があることです。APIゲートウェイでは、APIデプロイメントにOAuth 2.0トークン認証ポリシーを使用するときに、ログアウト・バック・エンドを定義してそのような機能を提供できます。ログアウト・バック・エンドへのリクエストには、オプションで、postLogoutUrl
という名前の問合せパラメータの値としてログアウト後のURLを含めることができます。
OAuth 2.0トークン認証ポリシーを定義する場合、オプションで、ログアウト・バック・エンド(ログアウト・パス)へのパスを指定して、認証が失敗した場合にアクセス・トークンを取り消すことができます。「トークンの検証によるAPIデプロイメントへの認証および認可の追加」を参照してください。
ログアウト・バック・エンド定義には、オプションで次のものが含まれます。
- アクセス・トークンを取り消すためにリクエストをリダイレクトできる、許可されたログアウト後のURLのリスト。
postLogoutUrl
問合せパラメータがリクエストに含まれている場合、その値はこれらのURLのいずれかである必要があります。リスト内のURLは絶対パスまたは相対パスにすることができ、URLにはコンテキスト変数を含めることができます。相対パス(つまり、APIデプロイメント内の別のルート)を指定する場合、APIデプロイメントとルートの両方で匿名アクセスを許可する必要があります。また、リストに1つ以上のURLを明示的に含めない場合は、ログアウト後のURLが許可されます。 - リクエストがリダイレクトされたときにログアウトURLに渡すデータを、
state
問合せパラメータの値として指定します。データに含めることができるのはコンテキスト変数のみです(静的値ではありません)。
APIクライアントからログアウト・パスへのリクエストを受信すると、APIゲートウェイは、ログアウト・バック・エンドをコールするためにAPIクライアントが認証されていることを確認し、リクエストに含まれるログアウト後のURLが許可されていることを確認し、APIクライアントのセッションに関する格納された情報(Cookieなど)を削除します。ログアウト後のURLが許可されている場合、次に何が行われるかは、APIクライアントが認証されているかどうか、およびOAuth 2.0トークン認証ポリシーで指定された検出URLから以前にキャッシュされたレスポンスがエンド・セッション・エンドポイントを提供したかどうかによって異なります。
- APIクライアントが認証されていない場合、APIゲートウェイはログアウト後のURLにログアウト・リクエストをリダイレクトします。
- APIクライアントが認証されているが、OAuth 2.0トークン認証ポリシーで終了セッション・エンドポイントが指定されていない場合、APIゲートウェイはログアウト後のURLにログアウト・リクエストをリダイレクトし、ログアウト・バック・エンド定義で指定された状態情報を渡します。
- APIクライアントが認証され、OAuth 2.0トークン認証ポリシーによって終了セッション・エンドポイントが提供された場合、APIゲートウェイはログアウト・リクエストをその終了セッション・エンドポイントにリダイレクトし、ログアウト後のURLおよびログアウト後のバックエンド定義で指定された状態情報を渡します。この場合、リクエストをログアウト後のURLにリダイレクトするのはアイデンティティ・プロバイダの責任です。
APIデプロイメント仕様にログアウト・バック・エンドを追加するには:
- コンソールの使用
- JSONファイルの編集
コンソールを使用したAPIデプロイメント仕様へのログアウト・バック・エンドの追加
コンソールを使用してAPIデプロイメント仕様にログアウト・バック・エンドを追加するには:
-
コンソールを使用してAPIデプロイメントを作成または更新し、「最初から」オプションを選択して、「基本情報」ページで詳細を入力します。
詳細は、APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイおよびAPIゲートウェイまたはAPIデプロイメントの更新を参照してください。
-
「認証」ページで、認証オプションを指定します。
For more information about authentication options, see Adding Authentication and Authorization to API Deployments.
-
「ルート」ページで、新しいルートを作成し、次を指定します:
-
パス: リストされたメソッドを使用したバックエンド・サービスへのAPIコールのパス。指定するルート・パスで次の点に注意してください:
- デプロイメント・パス接頭辞に対して相対的です(APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイを参照)
- 先頭にスラッシュ(/)を付ける必要があります。単一のスラッシュのみも可能です
- スラッシュは複数使用でき(連続していない場合)、スラッシュで終了できます
- 英数字の大文字と小文字を使用できます
- 特殊文字
$ - _ . + ! * ' ( ) , % ; : @ & =
を使用できます - パラメータおよびワイルドカードを使用できます(ルート・パスへのパス・パラメータおよびワイルドカードの追加を参照)
- メソッド: バックエンド・サービスが受け入れた1つ以上のメソッド。ログアウト・バック・エンドの場合、
GET
のみが受け入れられます。 - バックエンド・タイプ:バックエンド・サービスのタイプ(
Logout
)。 - Allowed post logout URIs: (optional) A list of one or more allowed URLs to which a logout request can be redirected to revoke tokens.リスト内のURLは絶対パスまたは相対パスにすることができ、URLにはコンテキスト変数を含めることができます。たとえば、
["https://${request.header[tenant-id].page.html}", "https://fixed-path.page.html",
です。"/logout_html"
]次に注意してください:
- A post-logout URL can be included in a request to the logout back end as the value of a query parameter named
postLogoutUrl
. - If you specify a relative path (that is, to another route in the API deployment), then both the API deployment and the route must allow anonymous access.
- If you don't explicitly include one or more URLs in the list, any post-logout URL is allowed.
- A post-logout URL can be included in a request to the logout back end as the value of a query parameter named
- Post logout state: (optional) Data to pass when a logout request is redirected to an end session endpoint and/or a post-logout URL.データに含めることができるのはコンテキスト変数のみです(静的値ではありません)。例:
request.query[region]
データは、
state
問合せパラメータの値として渡されます。
-
- (オプション)「別のルート」をクリックして、追加ルートの詳細を入力します。
- 「次」をクリックして、APIデプロイメント用に入力した詳細を確認します。
- APIデプロイメントを作成または更新するには、「作成」または「変更の保存」をクリックします。
- (オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。
Editing a JSON File to Add Logout Back Ends to an API Deployment Specification
To add logout back ends to an API deployment specification in a JSON file:
-
Using your preferred JSON editor, edit the existing API deployment specification to which you want to add a logout back end, or create a new API deployment specification (see Creating an API Deployment Specification).
たとえば、次の基本的なAPIデプロイメント仕様では、Oracle Functionsの単純なHello Worldサーバーレス・ファンクションを単一のバック・エンドとして定義しています:
{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
-
routes
セクションで、ログアウト・バック・エンドの新しいセクションを含めます:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } }, { "path": "<logout-route-path>", "methods": ["<method-list>"], "backend": { "type": "OAUTH2_LOGOUT", "allowedPostLogoutUris": ["<url>", "<url"], "postLogoutState": "<logout-data>" } } ] }
ここでは:
-
<logout-route-path>
は、リストされたメソッドを使用してログアウト・バック・エンドへのコールのパスを指定します。指定するルート・パスで次の点に注意してください:- デプロイメント・パス接頭辞に対して相対的です(APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイを参照)
- 先頭にスラッシュ(/)を付ける必要があります。単一のスラッシュのみも可能です
- スラッシュは複数使用でき(連続していない場合)、スラッシュで終了できます
- 英数字の大文字と小文字を使用できます
- 特殊文字
$ - _ . + ! * ' ( ) , % ; : @ & =
を使用できます -
パラメータおよびワイルドカードを使用できます(ルート・パスへのパス・パラメータおよびワイルドカードの追加を参照)
<method-list>
は、ログアウト・バック・エンドによって受け入れられる1つ以上のメソッドをカンマで指定します。ログアウト・バック・エンドの場合、GET
のみが受け入れられます。"type": "OAUTH2_LOGOUT"
は、バック・エンドがログアウト・バック・エンドであることを指定します。-
"allowedPostLogoutUris": ["<url>", "<url>"]
optionally specifies a list of one or more allowed URLs to which a logout request can be redirected to revoke tokens.リスト内のURLは絶対パスまたは相対パスにすることができ、URLにはコンテキスト変数を含めることができます。たとえば、["https://${request.header[tenant-id].page.html}", "https://fixed-path.page.html",
です。"/logout_html"
]次に注意してください:
- A post-logout URL can be included in a request to the logout back end as the value of a query parameter named
postLogoutUrl
. - If you specify a relative path (that is, to another route in the API deployment), then both the API deployment and the route must allow anonymous access.
- If you don't explicitly include one or more URLs in the list, any post-logout URL is allowed.
- A post-logout URL can be included in a request to the logout back end as the value of a query parameter named
-
"postLogoutState": "<logout-data>"
optionally specifies data to pass when a logout request is redirected to an end session endpoint and/or a post-logout URL.データに含めることができるのはコンテキスト変数のみです(静的値ではありません)。例:request.query[region]
データは、
state
問合せパラメータの値として渡されます。
In this example, a request to the
/logout
back end can include one of the URLs specified forallowedPostLogoutUris
as the value of thepostLogoutUrl
query parameter.When the post-logout URL is called, the value of therequest.query[region]
context variable is passed to the URL.この例では、allowedPostLogoutUris
値("/logout_html"
)の1つが、同じAPIデプロイメントの/logout_html
標準レスポンス・バック・エンドへの相対パスであることに注意してください。同じAPIデプロイメント内の別のルートへの相対パスであるため、/logout_html
バックエンドには、次に示すように、ANONYMOUS
タイプの認可ポリシーを含める必要があります。{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } }, { "path": "/logout", "methods": ["GET"], "backend": { "type": "OAUTH2_LOGOUT", "allowedPostLogoutUris": ["https://${request.header[tenant-id].page.html}", "/logout_html"], "postLogoutState": "request.query[region]" } }, { "path": "/logout_html", "methods": ["GET"], "backend": { "type": "STOCK_RESPONSE_BACKEND", "body": "Token could not be revoked." }, "requestPolicies": { "authorization": { "type": "ANONYMOUS" } } } ] }
-
- APIデプロイメント仕様を含むJSONファイルを保存します。
-
APIデプロイメント仕様は、次の方法でAPIデプロイメントを作成または更新するときに使用します:
- 「既存のAPIのアップロード」オプションを選択して、コンソールでJSONファイルを指定します
- APIゲートウェイREST APIへのリクエストでJSONファイルを指定します
詳細は、APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイおよびAPIゲートウェイまたはAPIデプロイメントの更新を参照してください。
- (オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。