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デプロイメントの更新を参照してください。
「認証」ページで、認証オプションを指定します。

認証オプションの詳細は、APIデプロイメントへの認証と認可の追加を参照してください。
「ルート」ページで、新しいルートを作成し、次を指定します:
- パス: リストされたメソッドを使用したバックエンド・サービスへのAPIコールのパス。指定するルート・パスで次の点に注意してください:
  - デプロイメント・パス接頭辞に対して相対的です(APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイを参照)
  - 先頭にスラッシュ(/)を付ける必要があります。単一のスラッシュのみも可能です
  - スラッシュは複数使用でき(連続していない場合)、スラッシュで終了できます
  - 英数字の大文字と小文字を使用できます
  - 特殊文字$ - _ . + ! * ' ( ) , % ; : @ & = を使用できます
  - パラメータおよびワイルドカードを使用できます(ルート・パスへのパス・パラメータおよびワイルドカードの追加を参照)
- メソッド: バックエンド・サービスが受け入れた1つ以上のメソッド。ログアウト・バック・エンドの場合、GETのみが受け入れられます。
- バックエンド・タイプ:バックエンド・サービスのタイプ(Logout)。
- 許可されるログアウト後のURI: (オプション)ログアウト・リクエストをリダイレクトしてトークンを取り消すことができる1つ以上の許可されたURLのリスト。リスト内のURLは絶対パスまたは相対パスにでき、URLにはコンテキスト変数を含めることができます。たとえば、["https://${request.header[tenant-id].page.html}", "https://fixed-path.page.html", "/logout_html"]です。
  次に注意してください:
  - ログアウト後URLは、postLogoutUrlという名前の問合せパラメータの値として、ログアウト・バック・エンドへのリクエストに含めることができます。
  - 相対パス(つまり、APIデプロイメント内の別のルート)を指定する場合、APIデプロイメントとルートの両方で匿名アクセスを許可する必要があります。
  - リストに1つ以上のURLを明示的に含めない場合は、ログアウト後のURLを使用できます。
- ログアウト後の状態: (オプション)ログアウト・リクエストが終了セッション・エンドポイントまたはログアウト後のURL(あるいはその両方)にリダイレクトされたときに渡されるデータ。データにはコンテキスト変数のみを含めることができます(静的値ではありません)。例: request.query[region]
  データは、state問合せパラメータの値として渡されます。
(オプション)「別のルート」をクリックして、追加ルートの詳細を入力します。
「次」をクリックして、APIデプロイメント用に入力した詳細を確認します。
APIデプロイメントを作成または更新するには、「作成」または「変更の保存」をクリックします。
(オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。

JSONファイルの編集によるAPIデプロイメント仕様へのログアウト・バック・エンドの追加

JSONファイルのAPIデプロイメント仕様にログアウト・バック・エンドを追加するには:

任意のJSONエディタを使用して、ログアウト・バック・エンドを追加する既存のAPIデプロイメント仕様を編集するか、新しいAPIデプロイメント仕様を作成します(APIデプロイメント仕様の作成を参照)。

たとえば、次の基本的な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>"]では、オプションで、トークンを取り消すためにログアウト・リクエストをリダイレクトできる1つ以上の許可されたURLのリストを指定します。リスト内のURLは絶対パスまたは相対パスにすることができ、URLにはコンテキスト変数を含めることができます。たとえば、["https://${request.header[tenant-id].page.html}", "https://fixed-path.page.html", "/logout_html"]です。
  
  次に注意してください:
  - ログアウト後URLは、postLogoutUrlという名前の問合せパラメータの値として、ログアウト・バック・エンドへのリクエストに含めることができます。
  - 相対パス(つまり、APIデプロイメント内の別のルート)を指定する場合、APIデプロイメントとルートの両方で匿名アクセスを許可する必要があります。
  - リストに1つ以上のURLを明示的に含めない場合は、ログアウト後のURLを使用できます。
- "postLogoutState": "<logout-data>"は、オプションで、ログアウト・リクエストが終了セッション・エンドポイントまたはログアウト後のURL(あるいはその両方)にリダイレクトされたときに渡すデータを指定します。データに含めることができるのはコンテキスト変数のみです(静的値ではありません)。例: request.query[region]
  
  データは、state問合せパラメータの値として渡されます。
この例では、/logoutバックエンドへのリクエストに、postLogoutUrl問合せパラメータの値としてallowedPostLogoutUrisに指定されたURLのいずれかを含めることができます。ログアウト後のURLがコールされると、request.query[region]コンテキスト変数の値が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のコールを参照)。

Oracle Cloud Infrastructureドキュメント

APIゲートウェイ・バック・エンドとしてのログアウトの追加

コンソールを使用したAPIデプロイメント仕様へのログアウト・バック・エンドの追加

JSONファイルの編集によるAPIデプロイメント仕様へのログアウト・バック・エンドの追加