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

APIゲートウェイ自体がリクエストに含まれるトークンを検証することで、認証および認可機能をAPIゲートウェイに追加できます(このトピックを参照)。または、APIゲートウェイで、リクエストに含まれる複数引数または単一引数のアクセス・トークンをOCIファンクションにデプロイされた認可者ファンクションに検証のために渡すことができます(認証および認可をAPIデプロイメントに追加するためのトークンの認可者ファンクションへの渡しを参照)。

APIゲートウェイ自体がリクエストに含まれるトークンを検証するには、TOKEN_AUTHENTICATIONタイプの認証リクエスト・ポリシーを作成します。APIへのアクセスを制御するために使用するトークンは、多くの場合、JSON Webトークン(JWT)です。

TOKEN_AUTHENTICATIONポリシーを使用する場合、APIデプロイメントは、APIデプロイメント仕様に2つの異なる種類のリクエスト・ポリシーを含めることによって、認証および認可にトークンを使用できるようにします:

トークンの検証方法、認証されていないエンド・ユーザーがAPIデプロイメントのルートにアクセスできるかどうかなど、トークンの使用を指定するAPIデプロイメント全体の認証リクエスト・ポリシー。
オプションでJWTのscopeクレームに指定された値に基づいて、エンド・ユーザーが実行できる操作を指定する各ルートの認可リクエスト・ポリシー。

次を実行して、認証および認可リクエスト・ポリシーをAPIデプロイメント仕様に追加できます:

コンソールの使用。
JSONファイルの編集。

ノート

以前のリリースでは、認証にJWTを使用するJWT_AUTHENTICATIONタイプの認証リクエスト・ポリシーを作成しました。既存のJWT_AUTHENTICATION認証リクエスト・ポリシーは引き続きサポートされています(JWT_AUTHENTICATIONリクエスト・ポリシーの使用に関するノートを参照)。ただし、JWTを認証する新しい認証リクエスト・ポリシーを作成する場合は、TOKEN_AUTHENTICATIONポリシーとして認証リクエスト・ポリシーを作成することをお薦めします。TOKEN_AUTHENTICATIONポリシーを使用すると、次のことができます。

JWTトークンと非JWTトークンの両方を検証します。
アイデンティティ・プロバイダを使用してトークンを検証し、イントロスペクション・エンドポイントを取得します。
元のリクエストでJWTトークンが無効または欠落している場合の新規JWTトークンの生成を含む、検証失敗ポリシーを指定します。

トークン認証中に何が起こりますか。

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

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

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

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

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

デフォルト(HTTP 401未認可): APIゲートウェイがAPIクライアントにHTTP-401レスポンスを返す場合は、このタイプの検証失敗ポリシーを指定します。これはデフォルトのレスポンスです。APIデプロイメント仕様をJSONファイルに定義していて、この動作が必要な場合は、単に検証失敗ポリシーを含めないでください。
カスタム・レスポンス: 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トークン(JWT)に関するノート

APIへのアクセスを制御するために使用するトークンは、通常、JSON Webトークン(JWT)です。JWTは、APIクライアントからリソースへのHTTPリクエストで送信されるJSONベースのアクセス・トークンです。JWTはアイデンティティ・プロバイダによって発行されます。APIゲートウェイでは、アイデンティティ・ドメインでのOCI IAM、Oracle Identity Cloud Service (IDCS)、Auth0およびOktaなどのOAuth2-compliantアイデンティティ・プロバイダの使用をサポートしています。リソースへのアクセスに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のドキュメントを参照してください。

クロスサイト・リクエスト・フォージェリ(CSRF)の保護に関するノート

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

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

新しい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タイプの認証リクエスト・ポリシーを作成することをお薦めします。

トークン認証の前提条件

JWTを使用してAPIデプロイメントの認証および認可を有効化する前に:

OAuth2-compliantアイデンティティ・プロバイダ(たとえば、アイデンティティ・ドメインのあるOCI IAM、Oracle Identity Cloud Service (IDCS)、Auth0)は、APIデプロイメントへのアクセスを許可されたユーザーに対してJWTを発行するようにすでに設定されている必要があります。
認可ポリシーでカスタム・クレームを使用する場合は、発行するJWTにカスタム・クレームを追加するようにアイデンティティ・プロバイダを設定する必要があります。

詳細は、アイデンティティ・プロバイダ・ドキュメント(たとえば、OCI IAMとアイデンティティ・ドメイン・ドキュメント、Oracle Identity Cloud Service (IDCS)ドキュメント、Auth0ドキュメント)を参照してください。

発行アイデンティティ・プロバイダが提供する対応する公開検証キーを使用してJWTを検証するには:

JWTの署名の生成に使用される署名アルゴリズムは、RS256、RS384またはRS512のいずれかである必要があります
公開検証キーの最小長は2048ビットで、4096ビットを超えることはできません

認可サーバーのイントロスペクション・エンドポイントを使用してトークンを検証するには:

クライアント資格証明(クライアントIDおよびクライアント・シークレット)を取得するには、すでにクライアント・アプリケーションを作成して認可サーバーに登録している必要があります。詳細は、認可サーバーのドキュメント(たとえば、アイデンティティ・ドメインを含むOCI IAMドキュメント、Oracle Identity Cloud Service (IDCS)ドキュメント、Auth0ドキュメント)を参照してください。
認可サーバーから取得したクライアント・シークレットをシークレットとしてVaultサービスのボールトにすでに格納し(Vaultでのシークレットの作成を参照)、シークレットのOCIDおよびバージョン番号を把握している必要があります。
クライアント・シークレットを含むボールト・シークレットにアクセスする権限を動的グループ内のAPIゲートウェイに付与するポリシーがすでに設定されている必要があります(Vaultサービスのシークレットとして格納された資格証明へのAPIゲートウェイ・アクセス権を付与するポリシーの作成を参照)。

コンソールを使用したトークン認証および認可リクエスト・ポリシーの追加

コンソールを使用してAPIデプロイメント仕様に認証および認可リクエスト・ポリシーを追加するには:

コンソールを使用してAPIデプロイメントを作成または更新し、「最初から」オプションを選択して、「基本情報」ページで詳細を入力します。

詳細は、APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイおよびAPIゲートウェイまたはAPIデプロイメントの更新を参照してください。
「次へ」をクリックして認証ページを表示します。
すべてのリクエストに単一の認証サーバーを使用することを指定するには、「単一認証」を選択します。

これらの手順では、単一の認証サーバーを使用することを想定しています。または、複数の認証サーバーを使用する場合は、「複数認証」を選択し、コンソールを使用した同じAPIデプロイメントへの複数の認証サーバーの追加の手順に従います。
「匿名アクセスの有効化: 」チェック・ボックスを選択または選択解除して、未認証(つまり、匿名)のエンド・ユーザーがAPIデプロイメント内のルートにアクセスできるかどうかを指定します。

デフォルトでは、このオプションは選択されていません。匿名のユーザーがルートにアクセスできないようにする場合は、このオプションを選択しないでください。このオプションを選択した場合は、各ルートの認可ポリシーで「匿名」を「認可タイプ」として選択することで、匿名アクセスを許可する各ルートを明示的に指定する必要もあります。
「認証タイプ」オプション・リストからOAuth 2.0 / OpenID Connectを選択し、次を指定します:
- トークンの場所:トークンがリクエスト・ヘッダーに含まれるか問合せパラメータに含まれるか。
- 認証トークンの詳細:トークンがリクエスト・ヘッダーに含まれるか問合せパラメータに含まれるかに応じて、次を指定します:
  - トークン・ヘッダー名:および認証スキーム:トークンがリクエスト・ヘッダーに含まれている場合は、ヘッダーの名前(たとえば、Authorization)およびHTTP認証スキーム(Bearerのみが現在サポートされています)を入力します。
  - トークン・パラメータ名:トークンが問合せパラメータに含まれる場合は、問合せパラメータの名前を入力します。
APIゲートウェイでトークンを検証する方法を指定します:
1. APIゲートウェイで、クライアント資格証明(Vaultサービスのボールトから取得されたクライアント・シークレットを含む)を使用して、JWTトークンと非JWTトークンの両方をOAuth 2.0認可サーバーのイントロスペクション・エンドポイントで検証する場合は、「タイプ」リストからOAuth 2.0イントロスペクション・エンドポイントを選択し、次を指定します:
  - クライアントID:イントロスペクション・エンドポイントに送信するクライアントID。クライアントIDを取得するには、クライアント・アプリケーションを作成して認可サーバーに登録します。たとえば、5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1です。トークン認証の前提条件を参照してください。
  - <compartment-name>のVault:イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むVaultサービスのボールトの名前。クライアント・シークレットを取得するには、クライアント・アプリケーションを作成して認可サーバーに登録します。トークン認証の前提条件を参照してください。
  - <コンパートメント名>のVaultシークレット:イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むボールト・シークレットの名前。
  - Vaultシークレット・バージョン番号:イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むボールト・シークレットのバージョン。
  - 検出URL: APIゲートウェイが認可メタデータ・エンドポイントを取得する認可サーバーの既知のURL。たとえば、https://my-idp/oauth2/default/.well-known/openid-configurationです。
    APIがデプロイされているAPIゲートウェイを含むサブネットからURLをルーティングできる必要があることに注意してください。
  - 最大キャッシュ期間(時間): APIゲートウェイがイントロスペクション・エンドポイントからレスポンスをキャッシュする時間数(1から24)。
  - 最大クロック・スキュー(秒): (オプション)トークンを発行した認可サーバーのシステム・クロックとAPIゲートウェイ間の最大時間差。ここに入力した値は、APIゲートウェイがJWTの有効開始日(nbf)クレーム(存在する場合)および有効期限(exp)クレームを使用して、JWTを検証して有効かどうかを判断するときに考慮されます。最小値(およびデフォルト)は0、最大値は120です。
  - SSL検証の無効化:認可サーバーと通信するときにSSL検証を無効化するかどうか。デフォルトでは、このオプションは選択されていません。Oracleでは、トークン検証が損なわれる可能性があるため、このオプションを選択しないでください。APIゲートウェイは、アイデンティティ・ドメイン、Oracle Identity Cloud Service (IDCS)、Auth0およびOktaでOCI IAMに対して発行された複数の認証局からの証明書を信頼します。
2. APIゲートウェイで実行時にアイデンティティ・プロバイダから公開検証キーを取得してJWTを検証する場合は、「タイプ」リストから「リモートJWKS」を選択し、次を指定します:
  - JWKS URI: JWTの署名の検証に使用するJSON Web Key Set (JWKS)の取得元のURI。たとえば、https://www.somejwksprovider.com/oauth2/v3/certsです。指定するURIの詳細は、issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
    
    次に注意してください:
    - URIは、APIがデプロイされているAPIゲートウェイを含むサブネットからルーティングできる必要があります。
    - APIゲートウェイがJWKSの取得に失敗した場合、APIデプロイメントへのすべてのリクエストはHTTP 500レスポンス・コードを返します。エラーの詳細は、APIゲートウェイの実行ログを参照してください(APIデプロイメントへのロギングの追加を参照)。
    - JWTの署名を検証するには、JWKSに特定のキー・パラメータが存在する必要があります(JWT署名の検証に必要なキー・パラメータを参照)。
    - JWKSには最大10個のキーを含めることができます。
  - 最大キャッシュ期間(時間): APIゲートウェイがJWKSを取得後にキャッシュする時間数(1から24)。
  - SSL検証の無効化:アイデンティティ・プロバイダと通信するときにSSL検証を無効化するかどうか。デフォルトでは、このオプションは選択されていません。JWT検証が損なわれる可能性があるため、Oracleではこのオプションを選択しないことをお薦めします。APIゲートウェイは、アイデンティティ・ドメイン、Oracle Identity Cloud Service (IDCS)、Auth0およびOktaでOCI IAMに対して発行された複数の認証局からの証明書を信頼します。
3. APIゲートウェイで、アイデンティティ・プロバイダによってすでに発行されている公開検証キーを使用してJWTを検証する場合(アイデンティティ・プロバイダに接続せずにAPIゲートウェイでJWTをローカル検証できるようにする場合)は、「タイプ」リストから「静的キー」を選択し、最大10個の静的キーを指定します:
  - キーID: JWTの署名に使用される静的キーの識別子。値はJWTヘッダーのkidクレームと一致する必要があります。たとえば、master_keyです。
  - キー形式: JSON WebキーまたはPEMエンコードされた公開キーとしての静的キーの形式。
    - JSON Webキー: 静的キーがJSON Webキーの場合は、このフィールドにキーをペーストします。
      
      例:
```
{
  "kty": "RSA",
  "n": "0vx7agoebGc...KnqDKgw",
  "e": "AQAB",
  "alg": "RS256",
  "use": "sig"
}
```
      JWTの署名を検証するには、静的キーに特定のキー・パラメータが存在する必要があります(JWT署名の検証に必要なキー・パラメータを参照)。また、現在サポートされているキー・タイプ(kty)はRSAのみであることにも注意してください。
    - PEMでエンコードされたパブリック・キー: 静的キーがPEMでエンコードされたパブリック・キーの場合は、このフィールドにキーをペーストします。例:
```
-----BEGIN PUBLIC KEY-----
XsEiCeYgglwW/KAhSSNRVdD60QlXYMWHOhXzSFDZCLf1WXxKMZCiMvVrsBIzmFEXnFmcsO2mxwlL5/8qQudomoP+yycJ2gWPIgqsZcQRheJWxVC5ep0MeEHlvLnEvCi9utpAnjrsZCQ7plfZVPX7XORvezwqQhBfYzwA27M2FgOOs8DOIYfqQ1Ki3DMqEppFnjLcjgQtknbTlT7YgG6tzobwig8M2KIrPjJ0BmbJAFH
-----END PUBLIC KEY-----
```
      -----BEGIN PUBLIC KEY-----および-----END PUBLIC KEY-----マーカーが必要です。
  - 別のキー:キーを追加する場合にクリックします(最大10個)。
(オプション) JWTトークン検証の追加詳細を指定します:
1. 「発行者」セクションで、APIデプロイメントへのアクセスに使用されるJWTの発行者(iss)クレームで許可される値を指定します:
  - 許可される発行者: APIデプロイメントへのアクセスに使用されるJWTの発行者(iss)クレームで許可されるアイデンティティ・プロバイダのURL (またはテキスト文字列)を指定します。たとえば、アイデンティティ・ドメインを使用してOCI IAMによって発行されたJWTをAPIデプロイメントへのアクセスに使用できるようにするには、https://identity.oraclecloud.com/と入力します。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
  - 別の発行者: アイデンティティ・プロバイダを追加する場合にクリックします(最大5人)。
2. 「オーディエンス」セクションで、APIデプロイメントへのアクセスに使用されるJWTのオーディエンス(aud)クレームで許可される値を指定します:
  - 許可されるオーディエンス: JWTのオーディエンス(aud)クレームで許可される値を指定して、トークンの目的の受信者を識別します。たとえば、オーディエンスはAPIゲートウェイのホスト名である場合がありますが、必ずしもそうである必要はありません。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
  - 別のオーディエンス: オーディエンスを追加する場合にクリックします(最大5人)。
3. クレーム検証: (オプション)指定済のオーディエンスaudおよび発行者issクレームの値に加えて、JWTで検証する1つ以上の追加クレームの名前と値を指定できます。入力するキーの名前と値は単純に文字列として扱われ、JWTの名前および値と完全に一致する必要があります。パターン一致およびその他のデータ型はサポートされていません。
  - クレームが必要です: 「クレーム・キー」フィールドのクレームをJWTに含める必要があるかどうかを指定します。
  - クレーム・キー: (オプション) JWTに含めることができるクレーム、またはJWTに含める必要があるクレームの名前を指定します。JWTにクレームを含める必要がある場合は、「必須」を選択します。指定するクレーム名には、サブジェクト(sub)クレームなどの予約済クレーム名、または特定のアイデンティティ・プロバイダによって発行されたカスタム・クレーム名を指定できます。
  - クレーム値: (オプション)クレームの許容値を「クレーム・キー」フィールドに指定します。プラス記号(+)をクリックして、別の許容値を入力します。クレームに1つ以上の許容値を指定すると、APIゲートウェイは指定した値のいずれかがクレームにあることを検証します。
  JWTでは、値を指定せずに要求を指定できます。これを行うには、「要求キー」フィールドに要求の名前を入力し、「要求値」フィールドを空白のままにして、必要に応じて「要求が必須」を設定します。
検証失敗ポリシーを設定して、APIゲートウェイで失敗した認証レスポンスを処理する方法(欠落または無効なトークンを検証しようとして失敗した後に返されます)を指定します:
1. APIゲートウェイでHTTP 401ステータス・コードおよびレスポンスのWWW-Authenticateヘッダー(欠落または無効なトークンに対するデフォルトのレスポンス)を送信する場合は、「デフォルト(HTTP 401未認可)」を選択します。
2. APIゲートウェイでOpenID Connect認可フローを使用して新しいJWTアクセス・トークンを取得する場合は、OAuth 2.0を選択します。このオプションは、以前に「検証タイプ」リストからOAuth 2.0イントロスペクション・エンドポイントを選択した場合にのみ使用できます。次を指定します:
  - スコープ:認可サーバーに送信されるscopeクレームに含める1つ以上のアクセス・スコープ。OpenID Connect認可フローを使用するには、スコープの1つとしてopenidを含める必要があります。たとえば、openid、email:read、profileです。
  - レスポンス・タイプ:認可フローから必要なレスポンスのタイプ。レスポンス・タイプとしてcodeと入力します。
  - フォールバック・リダイレクト・パス: (オプション)元のリクエストがPUTリクエストまたはPOSTリクエストだった場合にAPIクライアントのリダイレクト先となる、現在のAPIデプロイメントの相対パス。例: /home
    元のリクエストがGETリクエストであった場合、リクエスト処理は新しいJWTアクセス・トークンで再開されるため、フォールバック・パスは使用されません。
  - ログアウト・パス: (オプション)現在のAPIデプロイメントのログアウト・バック・エンドへの相対パス。指定するパスは、ログアウト・バック・エンドに定義されているルート・パスと一致する必要があります。例: /revoke
    APIクライアントは、ログアウト・バック・エンドをコールしてトークンを取り消すことができます。ログアウト・バック・エンドへのコールには、postLogoutUrlという名前の問合せパラメータとしてログアウト後のURLを含めることができます。APIゲートウェイ・バックエンドとしてのログアウトの追加を参照してください。
  - レスポンスの有効期限(秒): (オプション)認可フローによって生成されたJWTトークンをキャッシュする時間の長さ。デフォルトは3600秒です。
  - OAuth2イントロスペクション・エンドポイント・クライアント資格証明の使用: OAuth 2.0イントロスペクション・エンドポイントで以前に指定したものと同じクライアント詳細を使用して、新しいJWTアクセス・トークンを取得するかどうかを指定します(通常は該当します)。以前に指定した詳細を使用しない場合は、次のように、認可サーバーから新しいJWTアクセス・トークンを取得するために使用する別のクライアント詳細を入力します:
    - クライアントID:イントロスペクション・エンドポイントに送信するクライアントID。例: 5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1
    - <compartment-name>のVault:イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むVaultサービスのボールトの名前。
    - <コンパートメント名>のVaultシークレット:イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むボールト・シークレットの名前。
    - Vaultシークレット・バージョン番号:イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むボールト・シークレットのバージョン。
  オプションで、「拡張オプションの表示」を選択して次を選択することで、OpenID認可フロー中に取得したトークンおよび値をCookieに格納することを選択できます:
  - セッションにCookieを使用: (オプション) OpenID Connect認可フローの最後に、新しく生成されたJWTトークンを非人間が読める文字列として格納する方法を指定します:
    - 新しいJWTトークンをセッションCookieに格納する場合は、このオプションを選択します。潜在的なCSRF攻撃を防ぐために、APIゲートウェイがトークンをセッションCookieに格納すると、X-CSRF-TOKENレスポンス・ヘッダーにCSRFトークンも返されます。APIゲートウェイへの後続のリクエスト(GETリクエストを除く)では、自動的に含まれるセッションCookieのJWTトークンに加えて、X-CSRF-TOKENリクエスト・ヘッダーにCSRFトークンを含める必要があります。
    - セッションCookieに新しいJWTトークンを格納しない場合は、このオプションを選択しないでください。かわりに、APIゲートウェイは、X-APIGW-TOKENレスポンス・ヘッダーで非人間が読めるトークンを返します。APIゲートウェイへの後続のリクエストでは、X-APIGW-TOKENリクエスト・ヘッダーに同じトークンを含める必要があります。
    Cross-Site Request Forgery (CSRF)の保護に関するノートを参照してください
  - 中間ステップにCookieを使用: (オプション)認可フローの中間ステップ値の格納方法(リクエスト・パラメータなど)を指定します。このオプションを選択すると、値はブラウザCookieに格納されます。APIゲートウェイとともに値を格納するには、このオプションの選択を解除します。
  - PKCEの使用: (オプション)追加のセキュリティのためにPKCE (コード交換のプルーフ・キー)を使用するかどうかを指定します。PKCEは、CSRF (クロスサイト・リクエスト・フォージェリ)および認可コード・インジェクション攻撃を防ぐためのOAuth 2.0セキュリティ拡張です。PKCEはクライアントシークレットの代わりにはなりません。クライアントシークレットが使用されている場合でもPKCEをお勧めします。PKCEの詳細については、OAuth 2.0のドキュメントを参照してください。
3. 欠落または無効なトークンを検証しようとして失敗した試行へのレスポンスをカスタマイズする場合は、「カスタム・レスポンス」を選択し、APIクライアントに戻るステータス・コード(およびオプションのメッセージ本文)を指定します:
  - HTTPステータス・コード:代替HTTPステータス・コードを入力します。たとえば、500です。
  - メッセージ本文:メッセージ本文を入力します。たとえば、Unfortunately, authentication failed.メッセージ本文には、(request.bodyを除く)任意のコンテキスト変数を含めることができます。
  - オプションで、ヘッダー変換レスポンス・ポリシーを指定して、APIゲートウェイがAPIクライアントに返すレスポンスのヘッダーを変更します。ヘッダー変換ポリシーの詳細は、ヘッダー変換レスポンス・ポリシーの追加を参照してください。
「次」をクリックして、「ルート」ページのAPIデプロイメント内の個々のルートの詳細を入力します。
「ルート1」セクションで、1つのパスと1つ以上のメソッドをバックエンド・サービスにマップするAPIデプロイメントの最初のルートを指定します:
- パス: リストされたメソッドを使用したバックエンド・サービスへのAPIコールのパス。指定するルート・パスで次の点に注意してください:
  - デプロイメント・パス接頭辞に対して相対的です
  - 先頭にスラッシュ(/)を付ける必要があります。単一のスラッシュのみも可能です
  - スラッシュは複数使用でき(連続していない場合)、スラッシュで終了できます
  - 英数字の大文字と小文字を使用できます
  - 特殊文字$ - _ . + ! * ' ( ) , % ; : @ & = を使用できます
  - パラメータおよびワイルドカードを使用できます(ルート・パスへのパス・パラメータおよびワイルドカードの追加を参照)
- メソッド: バックエンド・サービスが受け入れる1つ以上のメソッド(カンマ区切り)。たとえば、GET, PUTです。
- 単一のバックエンドの追加または複数のバックエンドの追加: すべてのリクエストを同じバックエンドにルーティングするか、入力したコンテキスト変数およびルールに従ってリクエストを異なるバックエンドにルーティングするか。
  
  これらの手順では、単一のバックエンドを使用することを想定しているため、「単一のバックエンドの追加」を選択します。別のバックエンドを使用する場合は、「複数のバックエンドの追加」を選択し、コンソールを使用したAPIデプロイメント仕様への動的バックエンド選択の追加の手順に従います。
- バックエンド・タイプ: バックエンド・サービスのタイプ。次のいずれかです:
  - HTTP: HTTPバック・エンドの場合、URL、タイムアウト詳細、およびSSL検証を無効にするかどうかを指定する必要もあります(APIゲートウェイ・バック・エンドとしてのHTTPまたはHTTPS URLの追加を参照)。
  - Oracle Functions: OCIファンクション・バックエンドの場合、アプリケーションとファンクションを指定する必要もあります(APIゲートウェイ・バックエンドとしてのOCIファンクションへのファンクションの追加を参照)。
  - 標準レスポンス: 標準レスポンス・バック・エンドの場合、HTTPステータス・コード、レスポンス本文のコンテンツ、および1つ以上のHTTPヘッダー・フィールドを指定する必要もあります(APIゲートウェイ・バック・エンドとしての標準レスポンスの追加を参照)。
  - ログアウト: ログアウト・バック・エンドの場合、トークンを取り消すためにリクエストをリダイレクトできる許可URLのリスト、およびオプションでログアウトURLに渡すデータも指定する必要があります(APIゲートウェイ・バック・エンドとしてのログアウトの追加を参照)。
個々のルートに適用する認可ポリシーを指定するには、「リクエスト・ポリシーのルーティングを表示」をクリックし、「認可」の横にある「追加」ボタンをクリックして、次を指定します:
- 認可タイプ: ルートへのアクセス権を付与する方法。次を指定します:
  - 任意: JWTで「許可されるスコープ」フィールドに指定したアクセス・スコープの少なくとも1つを含むscopeクレームがある場合にのみ、正常に認証されたエンド・ユーザーにアクセス権を付与します。この場合、認証ポリシーの「匿名アクセスの有効化」オプションは無効です。
  - 匿名: JWTを使用して正常に認証されていない場合でも、すべてのエンド・ユーザーにアクセス権を付与します。この場合、認証ポリシーの「匿名アクセスの有効化」オプションを選択しておく必要があります。
  - 認証のみ: JWTを使用して正常に認証されたエンド・ユーザーにのみアクセス権を付与します。この場合、認証ポリシーの「匿名アクセスの有効化」オプションは無効です。
- 許可されるスコープ: 「認可タイプ」として「任意」を選択した場合は、JWTのアクセス・スコープに対応する1つ以上の文字列のカンマ区切りリストを入力します。アクセス権は、指定したアクセス・スコープのいずれかを含むscopeクレームがJWTにある場合に、正常に認証されたエンド・ユーザーにのみ付与されます。たとえば、read:helloです
ノート

特定のルートの認可ポリシーを含めない場合、そのようなポリシーが存在するかのようにアクセスが付与され、「認可タイプ」が「認証のみ」に設定されます。つまり、認証ポリシーの「匿名アクセスの有効化」オプションの設定に関係なく、次のようになります:
- ルートにアクセスできるのは、認証されたエンド・ユーザーのみです
- JWTのscopeクレームのアクセス・スコープに関係なく、すべての認証済エンド・ユーザーがルートにアクセスできます
- 匿名のエンド・ユーザーはルートにアクセスできません
「変更の適用」をクリックし、「次」をクリックしてAPIデプロイメントに入力した詳細を確認します。
APIデプロイメントを作成または更新するには、「作成」または「変更の保存」をクリックします。
(オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。

JSONファイルを編集してトークン認証および認可リクエスト・ポリシーを追加

JSONファイルのAPIデプロイメント仕様に認証および認可リクエスト・ポリシーを追加するには:

任意のJSONエディタを使用して、認証および認可機能を追加する既存のAPIデプロイメント仕様を編集するか、新しいAPIデプロイメント仕様を作成します(APIデプロイメント仕様の作成を参照)。

APIデプロイメント仕様には、少なくとも次の内容を含むroutesセクションが含まれます:
- パス。たとえば、/helloです
- 1つ以上のメソッド。たとえば、GETです
- バック・エンドの定義。たとえば、URLまたはOCIファンクション内のファンクションのOCIDです。
たとえば、次の基本的なAPIデプロイメント仕様では、OCIファンクションの単純なHello Worldサーバーレス・ファンクションを単一のバックエンドとして定義しています:
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```

routesセクションの前にrequestPoliciesセクションを挿入して(まだ存在しない場合)、APIデプロイメント仕様のすべてのルートに適用されるauthenticationリクエスト・ポリシーを作成します。例:


{
  "requestPolicies": {},
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
         "type": "ORACLE_FUNCTIONS_BACKEND",
         "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}

次のようにauthenticationリクエスト・ポリシーを追加します
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">,
      "tokenAuthScheme": "<authentication-scheme>",
      "isAnonymousAccessAllowed": <true|false>,
      "maxClockSkewInSeconds": <seconds-difference>,
      "validationPolicy": {<validation-policy-config>},
    }
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
         "type": "ORACLE_FUNCTIONS_BACKEND",
         "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
ここでは:
- "authentication": {"type": "TOKEN_AUTHENTICATION"...は、認証にトークンを使用することを指定します。
- <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">は、トークンを含むリクエスト・ヘッダーであるか(そうであれば、ヘッダーの名前)またはトークンを含む問合せパラメータであるか(そうであれば、問合せパラメータの名前)を示します。"tokenHeader": "<token-header-name>"または"tokenQueryParam": "<token-query-param-name>">のいずれかを指定できますが、両方を指定することはできません。例: "tokenHeader": "Authorization"
- <tokenAuthScheme>は、トークンがリクエスト・ヘッダーに含まれる場合に使用する認証スキームの名前です。たとえば、"Bearer"です。
- "isAnonymousAccessAllowed": <true|false>は、オプションで、未証(つまり、匿名)のエンド・ユーザーがAPIデプロイメント仕様のルートにアクセスできるかどうかを示します。匿名のエンド・ユーザーがルートにアクセスできないようにする場合は、このプロパティをfalseに設定します。このプロパティをauthenticationポリシーに含めない場合、デフォルトのfalseが使用されます。このプロパティを使用してtrueに設定する場合は、各ルートのauthorizationポリシーでtypeプロパティを"ANONYMOUS"に設定することで、匿名アクセスが許可されているすべてのルートを明示的に指定する必要もあります。
- maxClockSkewInSeconds: <seconds-difference>では、JWTを発行したアイデンティティ・プロバイダのシステム・クロックとAPIゲートウェイの間の最大時間差をオプションで指定します。指定した値は、APIゲートウェイがJWTの有効開始日(nbf)クレーム(存在する場合)および有効期限(exp)クレームを使用して、JWTを検証して有効かどうかを判断するときに考慮されます。最小値(およびデフォルト)は0、最大値は120です。
- "validationPolicy": {<validation-policy-config>}では、次のステップで説明するように、トークンを検証する検証ポリシーを指定します。
APIゲートウェイで、クライアント資格証明(Vaultサービスのボールトから取得されたクライアント・シークレットを含む)を使用して、JWTトークンと非JWTトークンの両方をOAuth 2.0認可サーバーのイントロスペクション・エンドポイントで検証する場合は、次の検証ポリシーを空のvalidationPolicyセクションに追加します:
```
      "validationPolicy": {
        "type": "REMOTE_DISCOVERY",          
        "clientDetails": {
          "type": "CUSTOM",
          "clientId": "<client-id>",
          "clientSecretId": "<secret-ocid>",
          "clientSecretVersionNumber": <secret-version-number>
        },          
        "sourceUriDetails": {
          "type": "DISCOVERY_URI",
          "uri": "<well-known-uri>"
        },
        "isSslVerifyDisabled": <true|false>,
        "maxCacheDurationInHours": <cache-time>,
        "additionalValidationPolicy": {
          "issuers": ["<issuer-url>", "<issuer-url>"],
          "audiences": ["<intended-audience>"],
          "verifyClaims": [{
            "key": "<claim-name>",
            "values": ["<acceptable-value>", "<acceptable-value>"],
            "isRequired": <true|false>
          }]
        }
      }
```
ここでは:
- "validationPolicy": {"type": "REMOTE_DISCOVERY"...}は、クライアント資格証明(Vaultサービスのボールトから取得されたクライアント・シークレットを含む)を使用して、OAuth 2.0認可サーバーのイントロスペクション・エンドポイントでトークンを検証することを指定します。
- clientDetails": {"type": "CUSTOM"...}では、Vaultサービスのボールトから取得するクライアント・シークレットの詳細を指定します:
  - "clientId": "<client-ID>"は、イントロスペクション・エンドポイントに送信するクライアントIDを指定します。クライアントIDを取得するには、クライアント・アプリケーションを作成して認可サーバーに登録します。たとえば、5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1です。トークン認証の前提条件を参照してください。
  - "clientSecretId": "<secret-OCID>"は、イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むボールト・シークレットのOCIDを指定します。例: ocid1.vaultsecret.oc1.iad.amaaaaaa______cggit3q
  - "clientSecretVersionNumber": <secret-version-number>は、イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むボールト・シークレットのバージョンを指定します。例: 1
- "uri": "<well-known-uri>"は、APIゲートウェイが認可メタデータ・エンドポイントを取得する認可サーバーの既知のURLを指定します。たとえば、https://my-idp/oauth2/default/.well-known/openid-configurationです。APIがデプロイされているAPIゲートウェイを含むサブネットからURLをルーティングできる必要があることに注意してください。
- "isSslVerifyDisabled": <true|false>は、認可サーバーと通信するときにSSL検証を無効にするかどうかを示します。JWT検証が損なわれる可能性があるため、Oracleではこのオプションをtrue に設定しないことをお薦めします。APIゲートウェイは、アイデンティティ・ドメイン、Oracle Identity Cloud Service (IDCS)、Auth0およびOktaでOCI IAMに対して発行された複数の認証局からの証明書を信頼します。
- "maxCacheDurationInHours": <cache-time>は、APIゲートウェイがイントロスペクション・エンドポイントからのレスポンスをキャッシュする時間(1から24)を指定します。
- "additionalValidationPolicy": {"issuers": ...}は、トークン検証の追加の詳細を指定します:
  - <issuer-URL>は、APIデプロイメントへのアクセスに使用されるJWTの発行者(iss)クレームで許可される認可サーバーのURL (またはテキスト文字列)です。たとえば、OCI IAMによって発行され、アイデンティティ・ドメインとともに発行されたJWTをAPIデプロイメントへのアクセスに使用できるようにするには、https://identity.oraclecloud.com/を指定します。1台または複数の承認サーバー(最大5台)を指定できます。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
  - <intended-audience>は、トークンの目的の受信者を識別するためにJWTのオーディエンス(aud)クレームで許可される値です。たとえば、オーディエンスはAPIゲートウェイのホスト名である場合がありますが、必ずしもそうである必要はありません。1人のオーディエンスまたは複数のオーディエンス(最大5人)を指定できます。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
  - "verifyClaims": {...}では、JWTで検証する1つ以上の追加クレームの追加クレーム名および値をオプションで指定します:
    - "key": "<claim-name>"は、JWTに含めることができるクレーム、またはJWTに含める必要があるクレームの名前です。指定するクレーム名には、サブジェクト(sub)クレームや、特定の認可サーバーによって発行されたカスタム・クレーム名など、予約済クレーム名を指定できます。
    - "values": ["<acceptable-value>", "<acceptable-value>"]は、(オプションで)クレームに使用できる1つ以上の値を示します。
    - "isRequired": <true|false>は、JWTにクレームを含める必要があるかどうかを示します。
    入力するキーの名前と値は単純に文字列として扱われ、JWTの名前および値と完全に一致する必要があります。パターン一致およびその他のデータ型はサポートされていません
たとえば、次のauthenticationポリシーは、認可リクエスト・ヘッダーのトークンを検証するために、OAuth 2.0イントロスペクション・エンドポイントに渡されたクライアント資格証明(Vaultサービスのボールトから取得されたクライアント・シークレットを含む)を使用してAPIゲートウェイを構成します:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "isAnonymousAccessAllowed": false,
      "maxClockSkewInSeconds": 10,
      "validationPolicy": {
        "type": "REMOTE_DISCOVERY",
        "clientDetails": {
          "type": "CUSTOM",
          "clientId": "5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1",
          "clientSecretId": "ocid1.vaultsecret.oc1.iad.amaaaaaa______cggit3q",
          "clientSecretVersionNumber": 1
        },          
        "sourceUriDetails": {
          "type": "DISCOVERY_URI",
          "uri": "https://my-idp/oauth2/default/.well-known/openid-configuration"
        },
        "isSslVerifyDisabled": false,
        "maxCacheDurationInHours": 2,
        "additionalValidationPolicy": {
          "issuers": ["https://identity.oraclecloud.com/"],
          "audiences": ["api.dev.io"],
          "verifyClaims": [{
            "key": "is_admin",
            "values": ["service:app", "read:hello"],
            "isRequired": true
          }]
        }
      }
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
実行時にアイデンティティ・プロバイダから公開検証キーを取得してAPIゲートウェイでJWTを検証する場合は、空のvalidationPolicyセクションに次の検証ポリシーを追加します:
```
      "validationPolicy": {
        "type": "REMOTE_JWKS",
        "uri": "<uri-for-jwks>",
        "isSslVerifyDisabled": <true|false>,
        "maxCacheDurationInHours": <cache-time>,
        "additionalValidationPolicy": {
          "issuers": ["<issuer-url>", "<issuer-url>"],
          "audiences": ["<intended-audience>"],
          "verifyClaims": [{
            "key": "<claim-name>",
            "values": ["<acceptable-value>", "<acceptable-value>"],
            "isRequired": <true|false>
          }]
        }
      }
```
ここでは:
- "validationPolicy": {"type": "REMOTE_JWKS"...は、実行時にアイデンティティ・プロバイダから最大10個の公開検証キーを取得するようにAPIゲートウェイを構成することを指定します。
- "uri": "<uri-for-jwks>"は、JWTの署名の検証に使用するJSON Web Key Set (JWKS)の取得元のURIを指定します。指定するURIの詳細は、issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。次に注意してください:
  - URIは、APIがデプロイされているAPIゲートウェイを含むサブネットからルーティングできる必要があります。
  - APIゲートウェイがJWKSの取得に失敗した場合、APIデプロイメントへのすべてのリクエストはHTTP 500レスポンス・コードを返します。エラーの詳細は、APIゲートウェイの実行ログを参照してください(APIデプロイメントへのロギングの追加を参照)。
  - JWTの署名を検証するには、JWKSに特定のキー・パラメータが存在する必要があります(JWT署名の検証に必要なキー・パラメータを参照)。
  - JWKSには最大10個のキーを含めることができます。
- "isSslVerifyDisabled": <true|false>は、アイデンティティ・プロバイダとの通信時にSSL検証を無効にするかどうかを示します。JWT検証が損なわれる可能性があるため、Oracleではこのオプションをtrue に設定しないことをお薦めします。APIゲートウェイは、アイデンティティ・ドメイン、Oracle Identity Cloud Service (IDCS)、Auth0およびOktaでOCI IAMに対して発行された複数の認証局からの証明書を信頼します。
- "maxCacheDurationInHours": <cache-time>は、取得後にAPIゲートウェイがJWKSをキャッシュする時間数(1から24)を指定します。
- "additionalValidationPolicy": {"issuers": ...}は、トークン検証の追加の詳細を指定します:
  - <issuer-url>は、APIデプロイメントへのアクセスに使用されるJWTの発行者(iss)クレームで許可されるアイデンティティ・プロバイダのURL (またはテキスト文字列)です。たとえば、アイデンティティ・ドメインを使用してOCI IAMによって発行されたJWTをAPIデプロイメントへのアクセスに使用できるようにするには、https://identity.oraclecloud.com/と入力します。1つまたは複数のアイデンティティ・プロバイダを指定できます(最大5つ)。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
  - <intended-audience>は、トークンの目的の受信者を識別するためにJWTのオーディエンス(aud)クレームで許可される値です。たとえば、オーディエンスはAPIゲートウェイのホスト名である場合がありますが、必ずしもそうである必要はありません。1人のオーディエンスまたは複数のオーディエンス(最大5人)を指定できます。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
  - verifyClaimsでは、JWTで検証する1つ以上の追加クレームの追加クレーム名および値をオプションで指定します(最大10個)。
    - "key": "<claim-name>"は、JWTに含めることができるクレーム、またはJWTに含める必要があるクレームの名前です。指定するクレーム名には、サブジェクト(sub)クレームなどの予約済クレーム名、または特定のアイデンティティ・プロバイダによって発行されたカスタム・クレーム名を指定できます。
    - "values": ["<acceptable-value>", "<acceptable-value>"]は、(オプションで)クレームに使用できる1つ以上の値を示します。
    - "isRequired": <true|false>は、JWTにクレームを含める必要があるかどうかを示します。
    入力するキーの名前と値は単純に文字列として扱われ、JWTの名前および値と完全に一致する必要があります。パターン一致およびその他のデータ型はサポートされていません
たとえば、次のauthenticationポリシーは、実行時にアイデンティティ・プロバイダから公開検証キーを取得することで、認可リクエスト・ヘッダーのJWTを検証するようにAPIゲートウェイを構成します:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "isAnonymousAccessAllowed": false,
      "validationPolicy": {
        "type": "REMOTE_JWKS",
        "uri": "https://my-tenant-id.identity.oraclecloud.com/admin/v1/SigningCert/jwk",
        "isSslVerifyDisabled": false,
        "maxCacheDurationInHours": 2,
        "additionalValidationPolicy": {
          "issuers": ["https://identity.oraclecloud.com/"],
          "audiences": ["api.dev.io"],
          "verifyClaims": [{
            "key": "is_admin",
            "values": ["service:app", "read:hello"],
            "isRequired": true
          }]
        }
      }
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
APIゲートウェイで、アイデンティティ・プロバイダによってすでに発行されている公開検証キーを使用してJWTを検証する場合(アイデンティティ・プロバイダに接続せずにAPIゲートウェイでJWTをローカルに検証できるようにする場合)は、空のvalidationPolicyセクションに次の検証ポリシーを追加します:
```
      "validationPolicy": {
        "type": "STATIC_KEYS",
        "keys": [{<key-config>}],
        "isSslVerifyDisabled": <true|false>,
        "maxCacheDurationInHours": <cache-time>,
        "additionalValidationPolicy": {
          "issuers": ["<issuer-url>", "<issuer-url>"],
          "audiences": ["<intended-audience>"],
          "verifyClaims": [{
            "key": "<claim-name>",
            "values": ["<acceptable-value>", "<acceptable-value>"],
            "isRequired": <true|false>
          }]
        }
      }
```
ここでは:
- "validationPolicy": {"type": "STATIC_KEYS"...では、アイデンティティ・プロバイダによってすでに発行されている最大10個の公開検証キーを使用してAPIゲートウェイを構成することを指定します(APIゲートウェイは、アイデンティティ・プロバイダに接続することなくJWTをローカルで検証できます)。
- "keys": [{<key-config>}]は、JWTの署名に使用される静的キーの識別子を指定します。指定する詳細は、アイデンティティ・プロバイダによってすでに発行されているキーの形式によって異なります(形式に関係なく、最大10個のキーを指定できます):
  - 静的キーがJSON Webキーの場合は、"format": "JSON_WEB_KEY"を指定し、JWTの署名に使用される静的キーの識別子を"kid"パラメータの値として指定し、JWTの署名を検証するための他のパラメータの値を指定します。
    
    例:
```
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ]
```
    JWTの署名を検証するには、静的キーに特定のキー・パラメータが存在する必要があります(JWT署名の検証に必要なキー・パラメータを参照)。また、現在サポートされているキー・タイプ(kty)はRSAのみであることにも注意してください。
  - 静的キーがPEMでエンコードされた公開キーの場合は、"format": "PEM"を指定し、JWTの署名に使用される静的キーの識別子を"kid"の値として指定し、キーを"key"の値として指定します。
    
    例:
```
        "keys": [
          {
            "format": "PEM",
            "kid": "master_key"
            "key": -----BEGIN PUBLIC KEY-----XsEiCeYgglwW/KAhSSNRVdD60QlXYMWHOhXzSFDZCLf1WXxKMZCiMvVrsBIzmFEXnFmcsO2mxwlL5/8qQudomoP+yycJ2gWPIgqsZcQRheJWxVC5ep0MeEHlvLnEvCi9utpAnjrsZCQ7plfZVPX7XORvezwqQhBfYzwA27M2FgOOs8DOIYfqQ1Ki3DMqEppFnjLcjgQtknbTlT7YgG6tzobwig8M2KIrPjJ0BmbJAFH-----END PUBLIC KEY-----
          }
        ]
```
    -----BEGIN PUBLIC KEY-----および-----END PUBLIC KEY-----マーカーが必要です。
- "isSslVerifyDisabled": <true|false>は、アイデンティティ・プロバイダとの通信時にSSL検証を無効にするかどうかを示します。JWT検証が損なわれる可能性があるため、Oracleではこのオプションをtrue に設定しないことをお薦めします。APIゲートウェイは、アイデンティティ・ドメイン、Oracle Identity Cloud Service (IDCS)、Auth0およびOktaでOCI IAMに対して発行された複数の認証局からの証明書を信頼します。
- "maxCacheDurationInHours": <cache-time>は、取得後にAPIゲートウェイがJWKSをキャッシュする時間数(1から24)を指定します。
- "additionalValidationPolicy": {"issuers": ...}は、トークン検証の追加の詳細を指定します:
  - <issuer-url>は、APIデプロイメントへのアクセスに使用されるJWTの発行者(iss)クレームで許可されるアイデンティティ・プロバイダのURL (またはテキスト文字列)です。たとえば、アイデンティティ・ドメインを使用してOCI IAMによって発行されたJWTをAPIデプロイメントへのアクセスに使用できるようにするには、https://identity.oraclecloud.com/と入力します。1つまたは複数のアイデンティティ・プロバイダを指定できます(最大5つ)。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
  - <intended-audience>は、トークンの目的の受信者を識別するためにJWTのオーディエンス(aud)クレームで許可される値です。たとえば、オーディエンスはAPIゲートウェイのホスト名である場合がありますが、必ずしもそうである必要はありません。1人のオーディエンスまたは複数のオーディエンス(最大5人)を指定できます。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
  - verifyClaimsでは、JWTで検証する1つ以上の追加クレームの追加クレーム名および値をオプションで指定します(最大10個)。
    - "key": "<claim-name>"は、JWTに含めることができるクレーム、またはJWTに含める必要があるクレームの名前です。指定するクレーム名には、サブジェクト(sub)クレームなどの予約済クレーム名、または特定のアイデンティティ・プロバイダによって発行されたカスタム・クレーム名を指定できます。
    - "values": ["<acceptable-value>", "<acceptable-value>"]は、(オプションで)クレームに使用できる1つ以上の値を示します。
    - "isRequired": <true|false>は、JWTにクレームを含める必要があるかどうかを示します。
    入力するキーの名前と値は単純に文字列として扱われ、JWTの名前および値と完全に一致する必要があります。パターン一致およびその他のデータ型はサポートされていません
たとえば、次のauthenticationポリシーでは、認可リクエスト・ヘッダーでJWTを検証するために、アイデンティティ・プロバイダによってすでに発行された公開検証キーを使用してAPIゲートウェイを構成します:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "isAnonymousAccessAllowed": false,
      "validationPolicy": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ],
        "isSslVerifyDisabled": false,
        "maxCacheDurationInHours": 2,
        "additionalValidationPolicy": {
          "issuers": ["https://identity.oraclecloud.com/"],
          "audiences": ["api.dev.io"],
          "verifyClaims": [{
            "key": "is_admin",
            "values": ["service:app", "read:hello"],
            "isRequired": true
          }]
        }
      }
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
(オプション)検証失敗ポリシーを設定することで、APIゲートウェイで失敗した認証レスポンスを処理する方法を指定できます(欠落または無効なトークンを検証しようとして失敗した後に返されます)。
1. APIゲートウェイでHTTP 401ステータス・コードおよびレスポンスのWWW-Authenticateヘッダー(欠落または無効なトークンに対するデフォルトのレスポンス)を送信する場合は、検証失敗ポリシーを定義しないでください。
2. APIゲートウェイでOpenID Connect認可フローを使用して新しいJWTアクセス・トークンを取得する場合は、OAUTH2タイプの検証失敗ポリシーを定義します。このオプションは、REMOTE_DISCOVERY型の validationPolicyを指定した場合にのみ使用できます。次を指定します:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      ...
      "validationPolicy": {
        "type": "REMOTE_DISCOVERY",
        ...
      },
      "validationFailurePolicy": {
        "type": "OAUTH2",
        "scopes": ["<scope>", "<scope"],
        "clientDetails": {
          "type": "<VALIDATION_BLOCK|CUSTOM>",
          "clientId": "<client-id>",
          "clientSecretId": "<secret-ocid>",
          "clientSecretVersionNumber": <secret-version-number>
          },
        "sourceUriDetails": {
          "type": "VALIDATION_BLOCK"
          },
        "maxExpiryDurationInHours": <number-of-hours>,
        "useCookiesForSession": <true|false>,
        "useCookiesForIntermediateSteps": <true|false>,
        "usePkce": <true|false>,
        "responseType": "code",
        "fallbackRedirectPath": "<redirect-path>",
        "logoutPath": "<logout-path>"
      }
    }
  },
  "routes": [
    ...
  ]
}
```
  ここでは:
  - "scopes": ["<scope>", "<scope"]は、認可サーバーに送信されるscopeクレームに含める1つ以上のアクセス・スコープを指定します。OpenID Connect認可フローを使用するには、スコープの1つとしてopenidを含める必要があります。例: "scopes": ["openid", "email:read", "profile"]
  - clientDetails": {...}では、次のように、認可サーバーから新しいJWTアクセス・トークンを取得するために使用するクライアント詳細を指定します:
    - "type": "<VALIDATION_BLOCK|CUSTOM>"は、前のvalidationPolicyで指定された詳細と同じまたは別のクライアント詳細を使用するかどうかを指定します。前と同じクライアント詳細(通常は該当)を使用する場合は、"type": "VALIDATION_BLOCK"を指定し、追加の詳細を指定しないでください。異なるクライアント詳細を使用する場合は、"type": "CUSTOM"を指定し、"clientId"、"clientSecretId"および"clientSecretVersionNumber"の値を設定します。
    - "clientId": "<client-ID>"は、イントロスペクション・エンドポイントに送信するクライアントIDを指定します。"type": "CUSTOM"の場合にのみ使用されます。例: 5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1
    - "clientSecretId": "<secret-OCID>"は、イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むボールト・シークレットのOCIDを指定します。"type": "CUSTOM"の場合にのみ使用されます。例: ocid1.vaultsecret.oc1.iad.amaaaaaa______cggit3q
    - "clientSecretVersionNumber": <secret-version-number>は、イントロスペクション・エンドポイントに送信するクライアント・シークレットを含むボールト・シークレットのバージョンを指定します。"type": "CUSTOM"の場合にのみ使用されます。例: 1
  - "sourceUriDetails": {"type": "VALIDATION_BLOCK"}は、APIゲートウェイが認可メタデータ・エンドポイントを取得する認可サーバーの既知のURLとして、前のvalidationPolicyで指定されたURLと同じURLを使用することを指定します。
  - "maxExpiryDurationInHours": <number-of-hours>は、認可フローによって生成されたJWTトークンをキャッシュする時間の長さを指定します。デフォルトは1です。
  - "useCookiesForSession": <true|false>では、OpenID Connect認可フローの最後に、新しく生成されたJWTトークンを非人間が読める文字列として格納する方法を指定します:
    - 新しいJWTトークンをセッションCookieに格納する場合は、このオプションをtrueに設定します。潜在的なCSRF攻撃を防ぐために、APIゲートウェイがトークンをセッションCookieに格納すると、X-CSRF-TOKENレスポンス・ヘッダーにCSRFトークンも返されます。後続のリクエスト(GETリクエスト以外)では、自動的に含まれるセッションCookieのJWTトークンに加えて、X-CSRF-TOKENリクエスト・ヘッダーにCSRFトークンを含める必要があります。
    - セッションCookieに新しいJWTトークンを格納しない場合は、このオプションをfalseに設定します。かわりに、APIゲートウェイは、X-APIGW-TOKENレスポンス・ヘッダーで非人間が読めるトークンを返します。APIゲートウェイへの後続のリクエストでは、X-APIGW-TOKENリクエスト・ヘッダーに同じトークンを含める必要があります。
    Cross-Site Request Forgery (CSRF)の保護に関するノートを参照してください
  - "useCookiesForIntermediateSteps": <true|false>は、認可フローの中間ステップ値(リクエスト・パラメータなど)を格納する方法を指定します。ブラウザCookieに値を格納するには、このオプションをtrueに設定します。APIゲートウェイで値を格納するには、このオプションをfalseに設定します。
  - "usePkce": <true|false>は、セキュリティを強化するためにPKCE (コード交換のプルーフ・キー)を使用するかどうかを指定します。PKCEは、CSRF (クロスサイト・リクエスト・フォージェリ)および認可コード・インジェクション攻撃を防ぐためのOAuth 2.0セキュリティ拡張です。PKCEはクライアントシークレットの代わりにはなりません。クライアントシークレットが使用されている場合でもPKCEをお勧めします。PKCEの詳細については、OAuth 2.0のドキュメントを参照してください。
  - "responseType": "code"は、認可フローから必要なレスポンスのタイプを指定します。レスポンス・タイプとしてcodeを指定します。
  - "fallbackRedirectPath": "/home"は、オプションで、元のリクエストがPUTリクエストまたはPOSTリクエストであった場合にAPIクライアントのリダイレクト先となる現在のAPIデプロイメントの相対パスを指定します。たとえば、/homeです。
    元のリクエストがGETリクエストであった場合、リクエスト処理は新しいJWTアクセス・トークンで再開されるため、フォールバック・パスは使用されません。
  - "logoutPath": "<revoke-path>"オプションで、現在のAPIデプロイメントのログアウト・バック・エンドへの相対パスを指定します。指定するパスは、ログアウト・バック・エンドに定義されているルート・パスと一致する必要があります。たとえば、"logoutPath": "/revoke"です。
    APIクライアントは、ログアウト・バック・エンドをコールしてトークンを取り消すことができます。ログアウト・バック・エンドへのコールには、postLogoutUrlという名前の問合せパラメータとしてログアウト後のURLを含めることができます。APIゲートウェイ・バックエンドとしてのログアウトの追加を参照してください。
  例:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      ...
      "validationPolicy": {
        "type": "REMOTE_DISCOVERY",
        ...
      },
      "validationFailurePolicy": {
        "type": "OAUTH2",
        "scopes": ["openid", "email:read", "profile"],
        "clientDetails": {
          "type": "VALIDATION_BLOCK"
          },
        "sourceUriDetails": {
          "type": "VALIDATION_BLOCK"
        },
        "maxExpiryDurationInHours": 2,
        "useCookiesForSession": true,
        "useCookiesForIntermediateSteps": true,
        "usePkce": true,
        "responseType": "code",
        "fallbackRedirectPath": "/home",
        "logoutPath": "/revoke"
      }
    }
  },
  "routes": [
    ...
  ]
}
```
3. 欠落または無効なトークンを検証しようとして失敗した試行へのレスポンスをカスタマイズする場合は、MODIFY_RESPONSEタイプの検証失敗ポリシーを定義し、次のようにAPIクライアントに戻るステータス・コード(およびオプションのメッセージ本文)を指定します:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      ...
      "validationPolicy": {
        ...
      },
      "validationFailurePolicy": {
        "type": "MODIFY_RESPONSE",
        "responseCode": "<alternative-response-code>",
        "responseMessage": "<custom-message-body>",
        "responseTransformations": {
          "headerTransformations": {
            <valid-header-transformation-response-policy>
          }
        }
      }
    }
  },
  "routes": [
    ...
  ]
}
```
  ここでは:
  - responseCode: 代替HTTPステータス・コードを指定します。たとえば、500です。
  - responseMessage: (オプション)メッセージ本文を指定します。例: Unfortunately, authentication failed.メッセージ本文には、任意のコンテキスト変数を含めることができます(request.bodyを除く)。
  - responseTransformations: (オプション)ヘッダー変換レスポンス・ポリシーを指定して、APIゲートウェイがAPIクライアントに返すレスポンスのヘッダーを変更します。ヘッダー変換ポリシーの詳細は、ヘッダー変換レスポンス・ポリシーの追加を参照してください。
  例:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      ...
      "validationPolicy": {
        ...
      },
      "validationFailurePolicy": {
        "type": "MODIFY_RESPONSE",
        "responseCode": "500",
        "responseMessage": "Unfortunately, authentication failed.",
      }
    }
  },
  "routes": [
    ...
  ]
}
```
APIデプロイメント仕様の各ルートに、authorizationリクエスト・ポリシーを追加します:
1. 最初のルートのbackendセクションの後にrequestPoliciesセクションを挿入します(まだ存在しない場合)。例:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "isAnonymousAccessAllowed": false,
      "validationPolicy": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ],
        "isSslVerifyDisabled": false,
        "maxCacheDurationInHours": 2,
        "additionalValidationPolicy": {
          "issuers": ["https://identity.oraclecloud.com/"],
          "audiences": ["api.dev.io"],
          "verifyClaims": [{
            "key": "is_admin",
            "values": ["service:app", "read:hello"],
            "isRequired": true
          }]
        }
      }
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {}
    }
  ]
}
```
2. 次のauthorizationポリシーを新しいrequestPoliciesセクションに追加します:
```
      "requestPolicies": {
        "authorization": {
          "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">, 
          "allowedScope": [ "<scope>" ]
        }
      }
```
  ここでは:
  - "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">は、ルートへのアクセス権を付与する方法を示します:
    - "AUTHENTICATION_ONLY": 正常に認証されたエンド・ユーザーにのみアクセス権を付与します。この場合、APIデプロイメント仕様のauthenticationポリシーの"isAnonymousAccessAllowed"プロパティは無効です。
    - "ANY_OF": JWTのscopeクレームに、allowedScopeプロパティで指定したアクセス・スコープのいずれかが含まれる場合に、正常に認証されたエンド・ユーザーにのみアクセス権を付与します。この場合、APIデプロイメント仕様のauthenticationポリシーの"isAnonymousAccessAllowed"プロパティは無効です。
    - "ANONYMOUS": 正常に認証されていない場合でも、すべてのエンド・ユーザーにアクセス権を付与します。この場合、APIデプロイメント仕様のauthenticationポリシーで"isAnonymousAccessAllowed"プロパティを明示的にtrueに設定する必要があります。
  - "allowedScope": [ "<scope>" ]は、JWTのscopeクレームに含まれるアクセス・スコープに対応する1つ以上の文字列のカンマ区切りリストです。この場合、typeプロパティを"ANY_OF"に設定する必要があります(typeプロパティが"AUTHENTICATION_ONLY"または"ANONYMOUS"に設定されている場合、"allowedScope"プロパティは無視されます)。また、複数のスコープを指定した場合、指定したスコープのいずれかがJWTのscopeクレームに含まれると、ルートへのアクセス権が付与されることにも注意してください。
  たとえば、次のリクエスト・ポリシーは、read:helloスコープを持つ認証されたエンド・ユーザーのみにアクセスを許可する/helloルートを定義します:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "isAnonymousAccessAllowed": false,
      "validationPolicy": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ],
        "isSslVerifyDisabled": false,
        "maxCacheDurationInHours": 2,
        "additionalValidationPolicy": {
          "issuers": ["https://identity.oraclecloud.com/"],
          "audiences": ["api.dev.io"],
          "verifyClaims": [{
            "key": "is_admin",
            "values": ["service:app", "read:hello"],
            "isRequired": true
          }]
        }
      }
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "authorization": {
          "type": "ANY_OF",
          "allowedScope": [ "read:hello" ]
        }
      }
    }
  ]
}
```
3. APIデプロイメント仕様内の残りのすべてのルートに、authorizationリクエスト・ポリシーを追加します。
ノート

特定のルートのauthorizationポリシーを含めない場合、そのようなポリシーが存在し、typeプロパティが"AUTHENTICATION_ONLY"に設定されているかのように、アクセス権が付与されます。つまり、APIデプロイメント仕様のauthenticationポリシーでのisAnonymousAccessAllowedプロパティの設定に関係なく、次のようになります:
- ルートにアクセスできるのは、認証されたエンド・ユーザーのみです
- JWTのscopeクレームのアクセス・スコープに関係なく、すべての認証済エンド・ユーザーがルートにアクセスできます
- 匿名のエンド・ユーザーはルートにアクセスできません
APIデプロイメント仕様を含むJSONファイルを保存します。
APIデプロイメント仕様は、次の方法でAPIデプロイメントを作成または更新するときに使用します:
- 「既存のAPIのアップロード」オプションを選択して、コンソールでJSONファイルを指定します
- APIゲートウェイREST APIへのリクエストでJSONファイルを指定します
詳細は、APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイおよびAPIゲートウェイまたはAPIデプロイメントの更新を参照してください。
(オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。

issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細

JWTを発行したアイデンティティ・プロバイダによって、JWTで発行者(iss)およびオーディエンス(aud)クレームに指定する必要がある許容値が決まります。JWTを発行したアイデンティティ・プロバイダによって、JWTの署名を検証するためにJSON Web Key Set (JWKS)を取得するURIも決まります。

アイデンティティ・プロバイダに関係なく、JWKSには最大10個のキーを含めることができます。

次の表を使用して、アイデンティティ・ドメイン、Oracle Identity Cloud Service (IDCS)、OktaおよびAuth0アイデンティティ・プロバイダでOCI IAMによって発行されるJWTに指定する内容を確認します。


アイデンティティ・プロバイダ	発行者(`iss`)クレーム	オーディエンス(`aud`)クレーム	JWKSの取得元のURIの形式
アイデンティティ・ドメインのあるOCI IAM	https://identity.oraclecloud.com	顧客固有。アイデンティティ・ドメインを使用するOCI IAMドキュメントのアプリケーションの管理を参照してください。	https://<tenant-base-url>/admin/v1/SigningCert/jwk
IDCS	https://identity.oraclecloud.com/	顧客固有。 Oracle Identity Cloud Serviceドキュメントのアクセス・トークンの検証に関する項を参照してください。	https://<tenant-base-url>/admin/v1/SigningCert/jwk Oracle Identity Cloud ServiceにログインせずにJWKSを取得するには、Oracle Identity Cloud Serviceドキュメントのデフォルト設定の変更に関する項を参照してください。
Okta	https://<your-okta-tenant-name>.com	顧客固有。 Okta開発者コンソールで認可サーバー用に構成されたオーディエンス。Oktaドキュメントのアクセス・トークンの追加検証に関する項を参照してください。	https://<your-okta-tenant-name>.com/oauth2/<auth-server-id> /v1/keys Oktaドキュメントを参照してください。
Auth0	https://<your-account-name>.auth0.com/	顧客固有。 Auth0ドキュメントのオーディエンスに関する項を参照してください。	https://<your-account-name>.auth0.com/.well-known/jwks.json

JWT署名の検証に必要なキー・パラメータ

JWTの署名を検証するには、APIゲートウェイで、URIから返されたJWKSまたは指定した静的JSON Webキーのいずれかに次のキー・パラメータが存在する必要があります。


キー・パラメータ	ノート
`kid`	JWTの署名に使用されるキーの識別子。値はJWTヘッダーの`kid`クレームと一致する必要があります。たとえば、`master_key`です。
`kty`	JWTの署名に使用されるキーのタイプ。現在サポートされているキー・タイプはRSAのみであることに注意してください。
`use`または`key_ops`	`use`パラメータが存在する場合は、`sig`に設定する必要があります。`key-ops`パラメータが存在する場合、`verify`は有効な値のいずれかである必要があります。
`n`	公開キーのモジュール。
`e`	公開キーの指数。
`alg`	署名アルゴリズム(存在する場合)は、RS256、RS384またはRS512のいずれかに設定する必要があります。

JWT_AUTHENTICATION認証リクエスト・ポリシーの使用(非推奨)

ノート

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

既存のJWT_AUTHENTICATIONリクエスト・ポリシーは、現在もサポートされています。また、新しいJWT_AUTHENTICATIONリクエスト・ポリシーを作成するには、JSONファイルでAPIデプロイメント仕様を定義します(この項の元の手順を参照)。かわりに、タイプTOKEN_AUTHENTICATIONの認証リクエスト・ポリシーを作成することをお薦めします。

JWT_AUTHENTICATIONタイプの認証リクエスト・ポリシーを使用する場合、エンド・ユーザーは、認証および認可にJWTを使用するAPIデプロイメントにアクセスする前に、アイデンティティ・プロバイダからJWTを取得する必要があります。

APIゲートウェイにデプロイされたAPIをコールする場合、APIクライアントはJWTを問合せパラメータまたはリクエストのヘッダーとして指定します。APIゲートウェイは、発行アイデンティティ・プロバイダが提供する対応する公開検証キーを使用してJWTを検証します。APIデプロイメントのJWT_AUTHENTICATION認証リクエスト・ポリシーを使用して、APIゲートウェイによるJWTの検証方法を構成できます:

実行時にアイデンティティ・プロバイダから公開検証キーを取得するようにAPIゲートウェイを構成できます。この場合、アイデンティティ・プロバイダは認可サーバーとして機能します。
APIゲートウェイは、アイデンティティ・プロバイダによってすでに発行されている公開検証キー(「静的キー」と呼ばれる)を使用して事前に構成できるため、APIゲートウェイはアイデンティティ・プロバイダに接続しなくても実行時にJWTをローカルで検証できます。その結果、トークン検証が高速になります。

JSONファイルのAPIデプロイメント仕様に新しいJWT_AUTHENTICATION認証および認可リクエスト・ポリシーを追加するには:

APIデプロイメント仕様のすべてのルートに適用するauthenticationリクエスト・ポリシーを追加します:
1. routesセクションの前にrequestPoliciesセクションを挿入します(まだ存在しない場合)。例:
```
{
  "requestPolicies": {},
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
         "type": "ORACLE_FUNCTIONS_BACKEND",
         "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
2. 次のauthenticationポリシーを新しいrequestPoliciesセクションに追加します。
```
{
  "requestPolicies": {
    "authentication": {
      "type": "JWT_AUTHENTICATION",
      "isAnonymousAccessAllowed": <true|false>,
      "issuers": ["<issuer-url>", "<issuer-url>"],
      <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">,
      "tokenAuthScheme": "<authentication-scheme>",
      "audiences": ["<intended-audience>"],
      "publicKeys": {
        "type": <"REMOTE_JWKS"|"STATIC_KEYS">,
        <public-key-config>
      },
      "verifyClaims": [
        {"key": "<claim-name>",
         "values": ["<acceptable-value>", "<acceptable-value>"],
         "isRequired": <true|false>
        }
      ],
      "maxClockSkewInSeconds": <seconds-difference>
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
  ここでは:
  - "isAnonymousAccessAllowed": <true|false>は、オプションで、未証(つまり、匿名)のエンド・ユーザーがAPIデプロイメント仕様のルートにアクセスできるかどうかを示します。匿名のエンド・ユーザーがルートにアクセスできないようにする場合は、このプロパティをfalseに設定します。このプロパティをauthenticationポリシーに含めない場合、デフォルトのfalseが使用されます。このプロパティを使用してtrueに設定する場合は、各ルートのauthorizationポリシーでtypeプロパティを"ANONYMOUS"に設定することで、匿名アクセスが許可されているすべてのルートを明示的に指定する必要もあります。
  - <issuer-url>は、APIデプロイメントへのアクセスに使用されるJWTの発行者(iss)クレームで許可されるアイデンティティ・プロバイダのURL (またはテキスト文字列)です。たとえば、アイデンティティ・ドメインを使用してOCI IAMによって発行されたJWTをAPIデプロイメントへのアクセスに使用できるようにするには、https://identity.oraclecloud.com/と入力します。1つまたは複数のアイデンティティ・プロバイダを指定できます(最大5つ)。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
  - <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">は、JWTを含むリクエスト・ヘッダーであるか(そうであれば)、JWTを含む問合せパラメータであるか(そうであれば、問合せパラメータの名前)を示します。"tokenHeader": "<token-header-name>"または"tokenQueryParam": "<token-query-param-name>">のいずれかを指定できますが、両方を指定することはできません。
  - <tokenAuthScheme>は、JWTがリクエスト・ヘッダーに含まれる場合に使用する認証スキームの名前です。たとえば、"Bearer"です。
  - <intended-audience>は、トークンの目的の受信者を識別するためにJWTのオーディエンス(aud)クレームで許可される値です。たとえば、オーディエンスはAPIゲートウェイのホスト名である場合がありますが、必ずしもそうである必要はありません。1人のオーディエンスまたは複数のオーディエンス(最大5人)を指定できます。issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。
  - "type": <"REMOTE_JWKS"|"STATIC_KEYS">は、APIゲートウェイで公開検証キーを使用してJWTを検証する方法を示します。REMOTE_JWKSを指定して、実行時にアイデンティティ・プロバイダから最大10個の公開検証キーを取得するようにAPIゲートウェイを構成します。STATIC_KEYSを指定すると、アイデンティティ・プロバイダによってすでに発行されている最大10個の公開検証キーを使用してAPIゲートウェイが構成されます(APIゲートウェイは、アイデンティティ・プロバイダに接続しなくてもローカルでJWTを検証できます)。
  - <public-key-config>は、次のように、"type":の値として"REMOTE_JWKS"または"STATIC_KEYS"を指定したかどうかに応じてJWT検証の詳細を示します:
    - 実行時にアイデンティティ・プロバイダから公開検証キーを取得してJWTを検証するようにAPIゲートウェイを構成するために"type": "REMOTE_JWKS"を指定した場合は、次のように詳細を指定します:
      "publicKeys": { "type": "REMOTE_JWKS", "uri": "<uri-for-jwks>", "maxCacheDurationInHours": <cache-time>, "isSslVerifyDisabled": <true|false> }
      ここでは:
      - "uri": "<uri-for-jwks>"は、JWTの署名の検証に使用するJSON Web Key Set (JWKS)の取得元のURIを指定します。指定するURIの詳細は、issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細を参照してください。次に注意してください:
        
        URIは、APIがデプロイされているAPIゲートウェイを含むサブネットからルーティングできる必要があります。
        
        APIゲートウェイがJWKSの取得に失敗した場合、APIデプロイメントへのすべてのリクエストはHTTP 500レスポンス・コードを返します。エラーの詳細は、APIゲートウェイの実行ログを参照してください(APIデプロイメントへのロギングの追加を参照)。
        
        JWTの署名を検証するには、JWKSに特定のキー・パラメータが存在する必要があります(JWT署名の検証に必要なキー・パラメータを参照)。
        
        JWKSには最大10個のキーを含めることができます。
      - "maxCacheDurationInHours": <cache-time>は、取得後にAPIゲートウェイがJWKSをキャッシュする時間数(1から24)を指定します。
      - "isSslVerifyDisabled": <true|false>は、アイデンティティ・プロバイダとの通信時にSSL検証を無効にするかどうかを示します。JWT検証が損なわれる可能性があるため、Oracleではこのオプションをtrueに設定しないことをお薦めします。APIゲートウェイは、アイデンティティ・ドメイン、Oracle Identity Cloud Service (IDCS)、Auth0およびOktaでOCI IAMに対して発行された複数の認証局からの証明書を信頼します。
      例:
      "publicKeys": { "type": "REMOTE_JWKS", "uri": "https://www.somejwksprovider.com/oauth2/v3/certs", "maxCacheDurationInHours": 3, "isSslVerifyDisabled": false }
    - "type": "STATIC_KEYS"を指定した場合、指定する詳細は、アイデンティティ・プロバイダによってすでに発行されているキーの形式によって異なります(形式に関係なく、最大10個のキーを指定できます):
      - 静的キーがJSON Webキーの場合は、"format": "JSON_WEB_KEY"を指定し、JWTの署名に使用される静的キーの識別子を"kid"パラメータの値として指定し、JWTの署名を検証するための他のパラメータの値を指定します。
        
        例:
        
        "publicKeys": { "type": "STATIC_KEYS", "keys": [ { "format": "JSON_WEB_KEY", "kid": "master_key", "kty": "RSA", "n": "0vx7agoebGc...KnqDKgw", "e": "AQAB", "alg": "RS256", "use": "sig" } ]
        
        JWTの署名を検証するには、静的キーに特定のキー・パラメータが存在する必要があります(JWT署名の検証に必要なキー・パラメータを参照)。また、現在サポートされているキー・タイプ(kty)はRSAのみであることにも注意してください。
      - 静的キーがPEMでエンコードされた公開キーの場合は、"format": "PEM"を指定し、JWTの署名に使用される静的キーの識別子を"kid"の値として指定し、キーを"key"の値として指定します。
        
        例:
        
        "publicKeys": { "type": "STATIC_KEYS", "keys": [ { "format": "PEM", "kid": "master_key" "key": -----BEGIN PUBLIC KEY-----XsEiCeYgglwW/KAhSSNRVdD60QlXYMWHOhXzSFDZCLf1WXxKMZCiMvVrsBIzmFEXnFmcsO2mxwlL5/8qQudomoP+yycJ2gWPIgqsZcQRheJWxVC5ep0MeEHlvLnEvCi9utpAnjrsZCQ7plfZVPX7XORvezwqQhBfYzwA27M2FgOOs8DOIYfqQ1Ki3DMqEppFnjLcjgQtknbTlT7YgG6tzobwig8M2KIrPjJ0BmbJAFH-----END PUBLIC KEY----- } ]
        
        -----BEGIN PUBLIC KEY-----および-----END PUBLIC KEY-----マーカーが必要です。
  - verifyClaimsでは、JWTで検証する1つ以上の追加クレームの追加クレーム名および値をオプションで指定します(最大10個)。
    - "key": "<claim-name>"は、JWTに含めることができるクレーム、またはJWTに含める必要があるクレームの名前です。指定するクレーム名には、サブジェクト(sub)クレームなどの予約済クレーム名、または特定のアイデンティティ・プロバイダによって発行されたカスタム・クレーム名を指定できます。
    - "values": ["<acceptable-value>", "<acceptable-value>"]は、(オプションで)クレームに使用できる1つ以上の値を示します。
    - "isRequired": <true|false>は、JWTにクレームを含める必要があるかどうかを示します。
    入力するキーの名前と値は単純に文字列として扱われ、JWTの名前および値と完全に一致する必要があります。パターン一致およびその他のデータ型はサポートされていません
  - maxClockSkewInSeconds: <seconds-difference>では、JWTを発行したアイデンティティ・プロバイダのシステム・クロックとAPIゲートウェイの間の最大時間差をオプションで指定します。指定した値は、APIゲートウェイがJWTの有効開始日(nbf)クレーム(存在する場合)および有効期限(exp)クレームを使用して、JWTを検証して有効かどうかを判断するときに考慮されます。最小値(およびデフォルト)は0、最大値は120です。
  たとえば、次のauthenticationポリシーは、アイデンティティ・プロバイダによってすでに発行されている公開検証キーを使用してAPIゲートウェイを構成し、認可リクエスト・ヘッダーのJWTを検証します:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "JWT_AUTHENTICATION",
      "isAnonymousAccessAllowed": false,
      "issuers": ["https://identity.oraclecloud.com/"],
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "audiences": ["api.dev.io"],
      "publicKeys": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ]
      },
      "verifyClaims": [
        {
          "key": "is_admin",
          "values": ["service:app", "read:hello"],
          "isRequired": true
        }
      ],
      "maxClockSkewInSeconds": 10
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```

APIデプロイメント仕様の各ルートに、authorizationリクエスト・ポリシーを追加します:

最初のルートのbackendセクションの後にrequestPoliciesセクションを挿入します(まだ存在しない場合)。例:

{
  "requestPolicies": {
    "authentication": {
      "type": "JWT_AUTHENTICATION",
      "isAnonymousAccessAllowed": false,
      "issuers": ["https://identity.oraclecloud.com/"],
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "audiences": ["api.dev.io"],
      "publicKeys": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ]
      },
      "verifyClaims": [
        {
          "key": "is_admin",
          "values": ["service:app", "read:hello"],
          "isRequired": true
        }
      ],
      "maxClockSkewInSeconds": 10
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
         "type": "ORACLE_FUNCTIONS_BACKEND",
         "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {}
    }
  ]
}

次のauthorizationポリシーをrequestPoliciesセクションに追加します:

{
  "requestPolicies": {
    "authentication": {
      "type": "JWT_AUTHENTICATION",
      "isAnonymousAccessAllowed": false,
      "issuers": ["https://identity.oraclecloud.com/"],
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "audiences": ["api.dev.io"],
      "publicKeys": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ]
      },
      "verifyClaims": [
        {
          "key": "is_admin",
          "values": ["service:app", "read:hello"],
          "isRequired": true
        }
      ],
      "maxClockSkewInSeconds": 10
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "authorization": {
          "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">, 
          "allowedScope": [ "<scope>" ]
        }
      }
    }
  ]
}

ここでは:

"type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">は、ルートへのアクセス権を付与する方法を示します:
- "AUTHENTICATION_ONLY": 正常に認証されたエンド・ユーザーにのみアクセス権を付与します。この場合、APIデプロイメント仕様のauthenticationポリシーの"isAnonymousAccessAllowed"プロパティは無効です。
- "ANY_OF": JWTのscopeクレームに、allowedScopeプロパティで指定したアクセス・スコープのいずれかが含まれる場合に、正常に認証されたエンド・ユーザーにのみアクセス権を付与します。この場合、APIデプロイメント仕様のauthenticationポリシーの"isAnonymousAccessAllowed"プロパティは無効です。
- "ANONYMOUS": 正常に認証されていない場合でも、すべてのエンド・ユーザーにアクセス権を付与します。この場合、APIデプロイメント仕様のauthenticationポリシーで"isAnonymousAccessAllowed"プロパティを明示的にtrueに設定する必要があります。
"allowedScope": [ "<scope>" ]は、JWTのscopeクレームに含まれるアクセス・スコープに対応する1つ以上の文字列のカンマ区切りリストです。この場合、typeプロパティを"ANY_OF"に設定する必要があります(typeプロパティが"AUTHENTICATION_ONLY"または"ANONYMOUS"に設定されている場合、"allowedScope"プロパティは無視されます)。また、複数のスコープを指定した場合、指定したスコープのいずれかがJWTのscopeクレームに含まれると、ルートへのアクセス権が付与されることにも注意してください。

たとえば、次のリクエスト・ポリシーは、read:helloスコープを持つ認証されたエンド・ユーザーのみにアクセスを許可する/helloルートを定義します:

{
  "requestPolicies": {
    "authentication": {
      "type": "JWT_AUTHENTICATION",
      "isAnonymousAccessAllowed": false,
      "issuers": ["https://identity.oraclecloud.com/"],
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "audiences": ["api.dev.io"],
      "publicKeys": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ]
      },
      "verifyClaims": [
        {
          "key": "is_admin",
          "values": ["service:app", "read:hello"],
          "isRequired": true
        }
      ],
      "maxClockSkewInSeconds": 10
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "authorization": {
          "type": "ANY_OF",
          "allowedScope": [ "read:hello" ]
        }
      }
    }
  ]
}

APIデプロイメント仕様内の残りのすべてのルートに、authorizationリクエスト・ポリシーを追加します。

ノート

特定のルートのauthorizationポリシーを含めない場合、そのようなポリシーが存在し、typeプロパティが"AUTHENTICATION_ONLY"に設定されているかのように、アクセス権が付与されます。つまり、APIデプロイメント仕様のauthenticationポリシーでのisAnonymousAccessAllowedプロパティの設定に関係なく、次のようになります:

ルートにアクセスできるのは、認証されたエンド・ユーザーのみです
JWTのscopeクレームのアクセス・スコープに関係なく、すべての認証済エンド・ユーザーがルートにアクセスできます
匿名のエンド・ユーザーはルートにアクセスできません

APIデプロイメント仕様を含むJSONファイルを保存します。
APIデプロイメント仕様は、次の方法でAPIデプロイメントを作成または更新するときに使用します:
- 「既存のAPIのアップロード」オプションを選択して、コンソールでJSONファイルを指定します
- APIゲートウェイREST APIへのリクエストでJSONファイルを指定します
詳細は、APIデプロイメントの作成によるAPIゲートウェイへのAPIのデプロイおよびAPIゲートウェイまたはAPIデプロイメントの更新を参照してください。
(オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。

例: TOKEN_AUTHENTICATIONリクエスト・ポリシーへのJWT_AUTHENTICATIONリクエスト・ポリシーの移行

この項では、TOKEN_AUTHENTICATIONポリシーに移行された既存のJWT_AUTHENTICATIONリクエスト・ポリシーの例を示します。

移行アプローチの1つの方法は、空のTOKEN_AUTHENTICATIONリクエスト・ポリシーを作成し、JWT_AUTHENTICATIONリクエスト・ポリシーから値を移入することです。

移行前:

移行前の元のJWT_AUTHENTICATIONリクエスト・ポリシー:

{
  "requestPolicies": {
    "authentication": {
      "type": "JWT_AUTHENTICATION",
      "isAnonymousAccessAllowed": false,
      "issuers": ["https://identity.oraclecloud.com/"],
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "audiences": ["api.dev.io"],
      "publicKeys": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ]
      },
      "verifyClaims": [
        {
          "key": "is_admin",
          "values": ["service:app", "read:hello"],
          "isRequired": true
        }
      ],
      "maxClockSkewInSeconds": 10
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "authorization": {
          "type": "ANY_OF",
          "allowedScope": [ "read:hello" ]
        }
      }
    }
  ]
}

移行後:

元のJWT_AUTHENTICATIONリクエスト・ポリシーから値が移入された新しいTOKEN_AUTHENTICATIONリクエスト・ポリシー:

{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      "isAnonymousAccessAllowed": false,
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "maxClockSkewInSeconds": 10,
      "validationPolicy": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ],
        "additionalValidationPolicy": {
          "audiences": [
            "api.dev.io"
          ],
          "verifyClaims": [
            {
              "key": "is_admin",
              "values": [
                "service:app",
                "read:hello"
              ],
              "isRequired": true
            }
          ],
          "issuers": [
            "https://identity.oraclecloud.com/"
          ]
        }
      }
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": [
        "GET"
      ],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "authorization": {
          "type": "ANY_OF",
          "allowedScope": [
            "read:hello"
          ]
        }
      }
    }
  ]
}

Oracle Cloud Infrastructureドキュメント

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

トークン認証中に何が起こりますか。

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

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

クロスサイト・リクエスト・フォージェリ(CSRF)の保護に関するノート

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

トークン認証の前提条件

コンソールを使用したトークン認証および認可リクエスト・ポリシーの追加

JSONファイルを編集してトークン認証および認可リクエスト・ポリシーを追加

issおよびaudクレームとJWKS URIに使用するアイデンティティ・プロバイダの詳細

JWT署名の検証に必要なキー・パラメータ

JWT_AUTHENTICATION認証リクエスト・ポリシーの使用(非推奨)

例: TOKEN_AUTHENTICATIONリクエスト・ポリシーへのJWT_AUTHENTICATIONリクエスト・ポリシーの移行

移行前:

移行後: