トークンの検証によるAPIデプロイメントへの認証および認可の追加

トークン認証では何が行われますか。

APIゲートウェイがAPIクライアントからリクエストを受信し、トークン認証ポリシーを指定した場合、APIゲートウェイはトークン(トークン・ヘッダーなど)を検出し、そのトークンを使用します。

APIゲートウェイが取得したトークンの検証方法を指定するには、トークン認証ポリシーの検証ポリシーを次のタイプのいずれかとして定義します。

• OAuth 2.0イントロスペクション・エンドポイント: APIゲートウェイでアイデンティティ・プロバイダのイントロスペクション・エンドポイントを使用してJWTまたはJWT以外のトークンを検証する場合は、このタイプの検証ポリシーを指定します。イントロスペクション・エンドポイントを取得するアイデンティティ・プロバイダの検出URLを指定する必要があります。この場合、APIゲートウェイは、クライアント資格証明(Vaultサービスから取得されたクライアント・シークレットとともにクライアントID)をアイデンティティ・プロバイダに渡して、トークンを検証します。トークンは、公開キーを使用せずに検証されます。将来の検証を高速化するために、APIゲートウェイでイントロスペクション・エンドポイントからのレスポンスを1時間(デフォルト)から24時間キャッシュするように指定できます。JSONファイルでAPIデプロイメント仕様を定義しており、この動作が必要な場合は、REMOTE_DISCOVERYタイプの検証ポリシーを含めます。
• リモートJWKS: APIゲートウェイで、実行時にアイデンティティ・プロバイダから取得された公開検証キーを使用してJWTを検証する場合は、このタイプの検証ポリシーを指定します。この場合、APIゲートウェイはアイデンティティ・プロバイダに連絡してJWTを検証します。アイデンティティ・プロバイダは認可サーバーとして機能します。JSONファイルでAPIデプロイメント仕様を定義しており、この動作が必要な場合は、REMOTE_JWKSタイプの検証ポリシーを含めます。
• 静的キー:アイデンティティ・プロバイダ(静的キー)によってすでに発行されている公開検証キーをAPIゲートウェイで使用してJWTを検証する場合は、このタイプの検証ポリシーを指定します。この場合、APIゲートウェイは、アイデンティティ・プロバイダに連絡しなくても実行時にJWTをローカルで検証できます。その結果、トークン検証が高速になります。JSONファイルでAPIデプロイメント仕様を定義し、この動作が必要な場合は、タイプSTATIC_KEYSの検証ポリシーを含めます

検証が成功すると、APIゲートウェイはリクエストを適切なAPIエンドポイントにルーティングします。

元のリクエストのトークンが無効または欠落しているために検証が失敗した場合、トークン認証ポリシーの検証失敗ポリシーを次のいずれかのタイプとして定義して、APIゲートウェイの動作を指定します:

• デフォルト(HTTP 401 Unauthorized): APIゲートウェイがAPIクライアントにHTTP-401レスポンスを返す場合は、このタイプの検証失敗ポリシーを指定します。これがデフォルトのレスポンスです。JSONファイルでAPIデプロイメント仕様を定義し、この動作が必要な場合は、検証失敗ポリシーを含めないでください。
• カスタム・レスポンス: APIゲートウェイがHTTP-401レスポンスではなく代替レスポンス(変更されたレスポンス)をAPIクライアントに返す場合は、このタイプの検証失敗ポリシーを指定します。JSONファイルでAPIデプロイメント仕様を定義し、この動作が必要な場合は、タイプMODIFY_RESPONSEの検証失敗ポリシーを含めます。
• OAuth 2.0: APIゲートウェイがGETリクエストのアイデンティティ・プロバイダから新しい有効なJWTトークンを取得する場合(最初に元のリクエスト問合せパラメータを安全に格納する場合)、このタイプの検証失敗ポリシーを指定します。PUTリクエストおよびPOSTリクエストの場合、APIクライアントのリダイレクト先となる現在のAPIデプロイメントの相対パスを指定できます。このタイプの検証失敗ポリシーを使用すると、ログアウト・バック・エンドを定義して、関連付けられたセッションCookieを削除したり、アイデンティティ・プロバイダのエンド・セッション・エンドポイントをコールしてトークンを取り消したり、許可されたログアウト後のURLにリダイレクトすることもできます。JSONファイルでAPIデプロイメント仕様を定義し、この動作が必要な場合は、タイプOAUTH2の検証失敗ポリシーを含めます。

  OAuth 2.0タイプの検証失敗ポリシーでは、現在、OpenID Connect認可フローのみがサポートされ、JWTトークン生成のみがサポートされています(OAuth 2.0およびOpenID Connectに関するノートを参照)。OpenID Connect認可フローの場合、id_token (常にJWTエンコード)およびaccess_token (JWTエンコード可能)という名前の2つのトークンが返されます。APIゲートウェイは、request.auth[id_token]およびrequest.auth[access_token]コンテキスト変数にトークン値を保存し、request.auth[id_token_claims][<claim-name>]およびrequest.auth[access_token_claims][<claim-name>]コンテキスト変数にカスタム・クレームをそれぞれ保存します(ポリシーおよびHTTPバックエンド定義へのコンテキスト変数の追加を参照)。新しいid_token JWTトークンの受信時に、APIゲートウェイはリクエスト詳細を取得し、トークンを使用してリクエスト処理を再開します。

APIゲートウェイがトークンを取得する場所は、検証ポリシーのタイプ(OAuth 2.0イントロスペクション・エンドポイント、リモートJWKSまたは静的キーのいずれか)と検証失敗ポリシーのタイプ(デフォルト(HTTP 401未認可)、カスタム・レスポンスまたはOAuth 2.0のいずれか)によって次のように異なります:

• タイプOAuth 2.0イントロスペクション・エンドポイントの検証ポリシーとタイプOAuth 2.0の検証失敗ポリシーの両方を指定した場合、APIゲートウェイは最初、次のいずれかまたは別のものからトークンの取得を試みます。
  • 検証失敗ポリシーでセッションCookieから「セッションにCookieを使用」オプションを選択した場合。
  • それ以外の場合は、リクエストのX-APIGW-TOKENヘッダーから。

  APIゲートウェイが最初の場所からトークンを取得できない場合、APIゲートウェイは、トークン認証ポリシーで指定したリクエスト・ヘッダーまたは問合せパラメータからトークンを取得します。

  その後、トークン検証が成功し、「セッションにCookieを使用」オプションを選択した場合、APIゲートウェイは、生成されたトークンを人間が読めない文字列としてセッションCookieに格納します。APIクライアントが後続のリクエストを行う場合、トークンはセッションCookieから取得されます。CSRF攻撃を防ぐために、生成されたトークンがセッションCookieに格納されると、APIゲートウェイはX-CSRF-TOKENレスポンス・ヘッダーにCSRFトークンも返します(クロスサイト・リクエスト・フォージェリ(CSRF)保護に関するノートを参照)。

• OAuth 2.0イントロスペクション・エンドポイントタイプの検証ポリシーとOAuth 2.0タイプの検証失敗ポリシーの両方を指定しない場合、APIゲートウェイはトークン認証ポリシーで指定したリクエスト・ヘッダーまたは問合せパラメータからトークンを取得します。

JSON Web Token (JWT)に関するノート

APIへのアクセスを制御するために使用するトークンは、通常、JSON Webトークン(JWT)です。JWTは、APIクライアントからリソースへのHTTPリクエストで送信されるJSONベースのアクセス・トークンです。JWTはアイデンティティ・プロバイダによって発行されます。APIゲートウェイでは、アイデンティティ・ドメインを使用するOCI IAM、Oracle Identity Cloud Service (IDCS)、Auth0、Oktaなど、OAuth2準拠のアイデンティティ・プロバイダの使用がサポートされています。リソースへのアクセスにJWTが必要な場合、リソースは、認可サーバー上の検証エンドポイントを呼び出すか、認可サーバーによって提供されるローカル検証キーを使用するかして、対応する公開検証キーを使用して認可サーバーでJWTを検証します。

JWTは次のもので構成されます:

• トークンのタイプと署名の生成に使用する暗号アルゴリズムを識別するヘッダー。
• エンド・ユーザーのアイデンティティに関するクレームおよびJWT自体のプロパティを含むペイロード。クレームはキーと値のペアで、キーはクレームの名前です。ペイロードには、有効期限(exp)、オーディエンス(aud)、発行者(iss)、有効開始日(nbf)など、特定の名前を持つ特定の予約済クレームを含めることをお薦めします(ただし必須ではありません)。ペイロードには、ユーザー定義名を持つカスタム・クレームを含めることもできます。
• JWTの真正性を検証する署名(base64エンコーディングのヘッダーおよびペイロードによって導出)。

JWTを使用してAPIへのアクセスを制御する場合、APIゲートウェイでJWTが有効とみなされる前に、JWTのペイロードの予約済クレームに特定の値が必要であることを指定できます。デフォルトでは、APIゲートウェイは有効期限(exp)、オーディエンス(aud)および発行者(iss)のクレームと、有効開始日(nbf)のクレーム(存在する場合)を使用してJWTを検証します。カスタム・クレームの許容値を指定することもできます。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。

JWTが検証されると、APIゲートウェイでは、JWTのペイロードからクレームをキー値ペアとして抽出し、APIデプロイメントで使用するためのrequest.authコンテキスト表にレコードとして保存します。たとえば、HTTPバックエンド定義で使用するためのコンテキスト変数として(ポリシーおよびHTTPバックエンド定義へのコンテキスト変数のの追加を参照)。JWTのペイロードにscopeクレームが含まれている場合、個々のルートの認可リクエスト・ポリシーでクレームの値を使用して、エンド・ユーザーが実行できる操作を指定できます。

OAuth 2.0およびOpenID Connectに関するノート

OAuth 2.0プロトコルを使用すると、クライアント資格証明を保護しながらセキュアなリソースを安全に取得できます。OAuth 2.0は、Webサーバーとブラウザ間のデータをプライベートのままにするためにSSL (Secure Sockets Layer)に依存する柔軟でセキュアなプロトコルです。OAuth 2.0はJWTと異なり、様々な目的に使用されますが、OAuth 2.0およびJWTには互換性があります。OAuth2プロトコルはトークンの形式を指定しないため、JWTをOAuth2の使用に組み込むことができます。OAuth 2.0の詳細は、OAuth 2.0のドキュメントを参照してください。

OpenID Connectは、OAuth 2.0プロトコルの上にある単純なアイデンティティ・レイヤーです。OpenID Connectを使用すると、APIゲートウェイは、認可サーバーによって実行される認証に基づいてAPIクライアントのアイデンティティを検証できます。また、OpenID Connectでは、APIゲートウェイがAPIクライアントに関する基本的なプロファイル情報を取得できます。OpenID Connectの詳細は、OpenID Connectのドキュメントを参照してください。

Cross-Site Request Forgery (CSRF) Protectionに関する注意事項

攻撃者は、ブラウザCookieの存在を利用して、ユーザーが意図しないコマンドをAPIゲートウェイなどのWebアプリケーションに送信することで、CSRF攻撃をマウントできます。ブラウザCookieが存在するため、ユーザーがすでに正常に認証されているとアプリケーションが判断した場合、アプリケーションはコマンドを実行し、結果に悪影響を及ぼす可能性があります。

タイプOAuth 2.0イントロスペクション・エンドポイントの検証ポリシーとタイプOAuth 2.0の検証失敗ポリシーを定義する場合、APIゲートウェイが取得した新しいJWTトークンをOpenID Connect認可フローを使用してどのように格納するかを指定します:

• 新しいJWTトークンをセッションCookieに格納する場合は、「セッションにCookieを使用」オプションを選択します。CSRF攻撃の可能性を防ぐため、APIゲートウェイがトークンをセッションCookieに格納すると、X-CSRF-TOKENレスポンス・ヘッダーにCSRFトークンも返されます。APIゲートウェイへの後続の突然変異リクエスト(POST、PUT、DELETEリクエストなど、GETリクエストは含まない)では、自動的に含まれるセッションCookieのJWTトークンに加えて、X-CSRF-TOKENリクエスト・ヘッダーにCSRFトークンを含める必要があります。

  APIゲートウェイでは、CSRFトークンもrequest.auth[apigw_csrf_token]コンテキスト変数に格納されることに注意してください。APIクライアントがなんらかの理由で初期X-CSRF-TOKENレスポンス・ヘッダーを読み取れない場合は、ヘッダー変換レスポンス・ポリシーにrequest.auth[apigw_csrf_token]コンテキスト変数を含めて、CSRFトークンを含むレスポンス・ヘッダーをAPIクライアントに返されるすべてのレスポンスに追加できます。このアプローチにより、APIクライアントはレスポンス・ヘッダーからCSRFトークンを正常に抽出して、APIゲートウェイに送信する後続のX-CSRF-TOKEN突然変異リクエスト・ヘッダーに含めることができます。適切なヘッダー変換レスポンス・ポリシーの例を次に示します:

  "responsePolicies": {
          "headerTransformations": {
            "setHeaders": {
              "items": [
                {
                  "name": "MY-CSRF-TOKEN",
                  "values": ["${request.auth[apigw_csrf_token]}"],
                  "ifExists": "OVERWRITE"              }
              ]
            }
          }
        }

  ヘッダー変換レスポンス・ポリシーの詳細は、「ヘッダー変換レスポンス・ポリシーの追加」を参照してください。

• 新しいJWTトークンをセッションCookieに格納しない場合は、「セッションにCookieを使用」オプションを選択しないでください。かわりに、APIゲートウェイは、X-APIGW-TOKENレスポンス・ヘッダーで人間が読めないトークンを返します。APIゲートウェイへの後続のリクエストでは、X-APIGW-TOKENリクエスト・ヘッダーに同じトークンが含まれている必要があります。

CSRFの詳細は、オンラインで検索してください。

JWT_AUTHENTICATIONリクエスト・ポリシーの使用に関するノート

以前のリリースでは、認証にJWTを使用するために、JWT_AUTHENTICATIONタイプの認証リクエスト・ポリシーが作成されている可能性があります。

JWTを使用するための新しい認証リクエスト・ポリシーを作成する場合は、かわりにタイプTOKEN_AUTHENTICATIONの認証リクエスト・ポリシーを作成することをお薦めします(コンソールを使用したトークン認証および認可リクエスト・ポリシーの追加およびトークン認証および認可リクエスト・ポリシーを追加するためのJSONファイルの編集を参照)。また、既存のJWT_AUTHENTICATIONリクエスト・ポリシーをTOKEN_AUTHENTICATIONポリシーに移行することをお薦めします。

既存のJWT_AUTHENTICATIONリクエスト・ポリシーは、現在もサポートされています。また、新しいJWT_AUTHENTICATIONリクエスト・ポリシー(「JWT_AUTHENTICATION認証リクエスト・ポリシーの使用(非推奨)」の元の手順を参照)を作成することはできますが、かわりに、タイプTOKEN_AUTHENTICATIONの認証リクエスト・ポリシーを作成することをお薦めします。