多引数アクセス・トークンおよび認可プロバイダ・ファンクションの認証および認可リクエスト・ポリシーの追加(推奨)

リクエスト・ポリシーを追加して、ユーザー定義の複数引数のアクセス・トークンおよび複数引数の認可プロバイダ・ファンクションを使用した認証および認可を提供します。

次の方法でリクエスト・ポリシーを追加できます。

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

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

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

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

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

デフォルトでは、このオプションは選択されていません。匿名のユーザーがルートにアクセスできないようにする場合は、このオプションを選択しないでください。このオプションを選択した場合は、各ルートの認可ポリシーで「匿名」を「認証タイプ」として選択することで、匿名アクセスを許可する各ルートを明示的に指定する必要もあります。
「認証タイプ」オプション・リストから「認可プロバイダ・ファンクション」を選択します。
複数引数のアクセス・トークンの認証に使用する複数引数の認可プロバイダ・ファンクションを指定します。
- Oracle Functionsアプリケーション:認可プロバイダ・ファンクションを含むOCI Functionsのアプリケーションの名前。別のコンパートメントからアプリケーションを選択できます。
- Oracleファンクション: OCIファンクションの認可プロバイダ・ファンクションの名前。
「複数引数の認可プロバイダ・ファンクション」を選択して、リクエストの1つ以上の要素をアクセス・トークンとして、複数引数のアクセス・トークンを受け入れることができる認可プロバイダ・ファンクションに渡すように指定します。
「関数の引数」パネルで、入力する引数名を持つ引数として認可プロバイダ・ファンクションに渡す値を指定する1つ以上のコンテキスト変数を指定します:
1. 認可プロバイダ・ファンクションに引数として渡す値を指定するコンテキスト変数を指定します。
  - コンテキスト表:リストからコンテキスト変数を含むコンテキスト表を選択します。
    - リクエストに含まれる問合せパラメータ名および値を含むrequest.queryコンテキスト表
    - リクエストに含まれるヘッダー名および値を含むrequest.headersコンテキスト表
    - request.certコンテキスト表。APIクライアントによって提示され、mTLSハンドシェイク中に正常に検証された証明書のBase64エンコード・バージョンが含まれます。
    - リクエストの送信先ホストの名前を含むrequest.hostコンテキスト表(リクエストのHostヘッダー・フィールドから抽出)
    - リクエストの本文を含むrequest.bodyコンテキスト表
  - ヘッダー名または問合せパラメータ名: request.headersまたはrequest.paramsコンテキスト表を選択した場合は、認可プロバイダ・ファンクションに渡すヘッダーまたは問合せパラメータの名前を入力します。たとえば、X-Api-Key、stateです。
  - 引数名:コンテキスト変数の値を代入する引数の名前を入力します。引数が認可プロバイダ・ファンクションに渡されます。入力する引数名は、認可プロバイダ・ファンクションが受け取ることを想定している引数名に対応している必要があります。
2. 必要に応じて、追加のコンテキスト変数および引数を指定します(必要に応じて「別の引数」を選択します)。
オプションで、複数引数の認可プロバイダ・ファンクションからレスポンスをキャッシュする方法をカスタマイズします。
1. 「詳細オプション」を選択します。
  「ファンクション結果キャッシュ」パネルには、キャッシュ・キーに存在する引数が表示されます。キャッシュ・キーは、元の認証リクエストで渡された引数および引数値を使用して、認可プロバイダ・ファンクションから返されたキャッシュされたレスポンスを一意に識別します。デフォルトでは、認可プロバイダ・ファンクションに渡すために指定したすべての引数および引数値(request.bodyコンテキスト表からの値を持つ引数を除く)が、キャッシュ・キーの作成に使用されます。
2. キャッシュ・キーに対して引数を追加または削除するには、「編集」を選択します。
3. 認可プロバイダ・ファンクションに渡された引数を選択または選択解除して、それらをキャッシュ・キーに含めるか除外します。
「複数引数の認可プロバイダ・ファンクション結果のキャッシュに関するノート」を参照してください。
オプションで、検証失敗ポリシーを設定して、複数引数の認可プロバイダ・ファンクションから失敗した認証レスポンスを処理する方法をカスタマイズします。
1. 「詳細オプション」を選択します。
  「失敗した認証のカスタム・レスポンス」パネルには、認可プロバイダ・ファンクションがリクエストを認証できない場合、APIクライアントに戻るためのHTTPステータス・コードおよびメッセージ本文が表示されます。デフォルトでは、APIゲートウェイはHTTP 401ステータス・コードとWWW-Authenticateヘッダーをレスポンスで送信します。検証失敗ポリシーに関するノートおよび複数引数の認可プロバイダ・ファンクションからの失敗した認証レスポンスの処理を参照してください。
2. 認可プロバイダ・ファンクションがリクエストを認証できない場合、APIクライアントに戻るステータス・コード(およびオプションのメッセージ本文)を指定します:
  - HTTPステータス・コード:代替HTTPステータス・コード(たとえば、500)を入力します。または、認可プロバイダ・ファンクションによって返されたコードを返すコンテキスト変数を含めることができます。たとえば、認可プロバイダ・ファンクションがresponseCodeパラメータでレスポンス・コードを返す場合は、request.auth[responseCode]を指定します。
  - メッセージ本文:メッセージ本文を入力します。たとえば、Unfortunately, authentication failed.メッセージ本文には、任意のコンテキスト変数を含めることができます(request.bodyを除く)。たとえば、Unfortunately, authentication failed ${request.auth[my-auth-variable]}です。
3. オプションで、APIゲートウェイがAPIクライアントに返すレスポンスのヘッダーを変更するには、「拡張オプション」を選択し、ヘッダー変換レスポンス・ポリシーを指定します:
  - レスポンスに含めるヘッダーを制限するには、次を指定します:
    - アクション: フィルタ。
    - タイプ: 「ブロック」を選択して明示的にリストしたヘッダーをレスポンスから削除するか、「許可」を選択して明示的にリストしたヘッダーのみをレスポンスで許可します(他のヘッダーはレスポンスから削除されます)。
    - ヘッダー名の指定:レスポンスから削除するか、レスポンスで許可するヘッダーのリスト(「タイプ」の設定によって決まります)。指定する名前は大/小文字が区別されず、ルートの他の変換レスポンス・ポリシーに含めることはできません(許可としてフィルタした項目を除く)。たとえば、User-Agentです。
  - (元の値を保持したまま)レスポンスに含まれるヘッダーの名前を変更するには、次を指定します:
    - アクション: 名前の変更。
    - ヘッダー名:名前を変更するヘッダーの元の名前。指定する名前は大/小文字が区別されず、ルートの他の変換レスポンス・ポリシーに含めることはできません。たとえば、X-Usernameです。
    - 新規ヘッダー名:名前を変更するヘッダーの新規名前。指定する名前は大/小文字が区別されず(大文字の使用は無視されます)、ルートの他の変換レスポンス・ポリシーに含めることはできません(ALLOWリストの項目を除く)。たとえば、X-User-IDです。
  - レスポンスに新しいヘッダーを追加する(またはレスポンスにすでに含まれている既存のヘッダーの値を変更または保持する)には、次を指定します:
    - アクション: 設定。
    - 動作: ヘッダーがすでに存在する場合は、ヘッダーの既存の値で何を行うかを指定します:
      - 上書き: ヘッダーの既存の値を指定した値に置き換えます。
      - 追加: 指定した値をヘッダーの既存の値に追加します。
      - スキップ: ヘッダーの既存の値を保持します。
    - ヘッダー名:レスポンスに追加する(または値を変更)ヘッダーの名前。指定する名前は大/小文字が区別されず、ルートの他の変換レスポンス・ポリシーに含めることはできません(許可としてフィルタした項目を除く)。たとえば、X-Api-Keyです。
    - 値: 新しいヘッダーの値(または動作の設定に応じて既存のヘッダーの値に置換または追加する値)。複数の値を指定できます。指定する値には、単純な文字列を指定することも、${...}デリミタで囲まれたコンテキスト変数を含めることもできます(request.bodyを除く)。たとえば、"value": "zyx987wvu654tsu321"です。
  ヘッダー変換レスポンス・ポリシーの詳細は、「ヘッダー変換レスポンス・ポリシーの追加」を参照してください
「次」を選択して、「ルート」ページのAPIデプロイメント内の個々のルートの詳細を入力します。
「ルートの追加」を選択し、1つのパスと1つ以上のメソッドをバックエンド・サービスにマップするAPIデプロイメント内の最初のルートを指定してください:
- パス: リストされたメソッドを使用したバックエンド・サービスへのAPIコールのパス。指定するルート・パスで次の点に注意してください:
  - デプロイメント・パス接頭辞に対して相対的です
  - 先頭にスラッシュ(/)を付ける必要があります。単一のスラッシュのみも可能です
  - スラッシュは複数使用でき(連続していない場合)、スラッシュで終了できます
  - 英数字の大文字と小文字を使用できます
  - 特殊文字$ - _ . + ! * ' ( ) , % ; : @ & = を使用できます
  - パラメータおよびワイルドカードを使用できます(ルート・パスへのパス・パラメータおよびワイルドカードの追加を参照)
- メソッド: バックエンド・サービスが受け入れる1つ以上のメソッド(カンマ区切り)。たとえば、GET, PUTです。
- 単一のバックエンドの追加または複数のバックエンドの追加: すべてのリクエストを同じバックエンドにルーティングするか、入力したコンテキスト変数およびルールに従ってリクエストを異なるバックエンドにルーティングするか。
  
  次の手順では、単一のバックエンドを使用することを前提にしているため、「単一のバックエンドの追加」を選択します。別のバックエンドを使用する場合は、「複数のバックエンドの追加」を選択し、コンソールを使用したAPIデプロイメント仕様への動的バックエンド選択の追加の手順に従います。
- バックエンド・タイプ:バックエンド・サービスのタイプ。次のいずれかです:
  - HTTP: HTTPバック・エンドの場合、URL、タイムアウト詳細、およびSSL検証を無効にするかどうかを指定する必要もあります(APIゲートウェイ・バック・エンドとしてのHTTPまたはHTTPS URLの追加を参照)。
  - Oracle Functions: OCI Functionsバック・エンドの場合、アプリケーションとファンクションを指定する必要もあります(APIゲートウェイ・バック・エンドとしてのOCI Functionsでのファンクションの追加を参照)。
  - 標準レスポンス:ストック・レスポンス・バック・エンドの場合、HTTPステータス・コードとレスポンス本文のコンテンツ、および1つまたは複数のHTTPヘッダー・フィールドを指定する必要もあります(APIゲートウェイ・バック・エンドとしての標準応答の追加を参照)。
  - ログアウト: ログアウト・バック・エンドの場合、トークンを取り消すためにリクエストをリダイレクトできる許可されたURLのリストと、オプションでログアウトURLに渡すデータも指定する必要があります(APIゲートウェイ・バック・エンドとしてのログアウトの追加を参照)。
個々のルートに適用する認可ポリシーを指定するには、「ルート・リクエスト・ポリシーの表示」を選択し、「認可」の横にある「追加」ボタンをクリックして、次を指定します:
- 認可のタイプ:ルートへのアクセス権を付与する方法。次を指定します:
  - 任意:認可プロバイダ・ファンクションで「許容される範囲の追加」フィールドに指定したアクセス・スコープのいずれかも戻された場合、正常に認証したエンド・ユーザーにのみアクセス権を付与します. この場合、認証ポリシーの「匿名アクセス権の有効化」オプションは無効です。
  - 匿名: 認可プロバイダ・ファンクションによって正常に認証されていない場合でも、すべてのエンド・ユーザーにアクセス権を付与します。この場合、認証ポリシーの匿名アクセスの有効化オプションを選択しておく必要があります。
  - 認証のみ: 認可プロバイダ・ファンクションによって正常に認証されたエンド・ユーザーにのみアクセス権を付与します。この場合、認証ポリシーの「匿名アクセス権の有効化」オプションは無効です。
- 許可される範囲の追加: 「認可のタイプ」として「任意」を選択した場合は、認可プロバイダ・ファンクションによって返されたアクセス・スコープに対応する1つ以上の文字列をカンマ区切りリストを入力します。アクセス権は、指定したアクセス・スコープのいずれかが認可プロバイダ・ファンクションによって返された場合に、正常に認証されたエンド・ユーザーにのみ付与されます。たとえば、read:helloです
ノート

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

JSONファイルの編集による複数引数の認証および認可のリクエスト・ポリシーの追加

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

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

APIデプロイメント仕様には、少なくとも次の内容を含むroutesセクションが含まれます:
- パス。たとえば、/helloです
- 1つ以上のメソッド。たとえば、GETです
- バック・エンドの定義。たとえば、URL、またはOCI Functions内のファンクションのOCID。
たとえば、次の基本的なAPIデプロイメント仕様では、OCI関数の単純なHello Worldサーバーレス・ファンクションを単一のバック・エンドとして定義しています:
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
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": "<type-value>",
      "isAnonymousAccessAllowed": <true|false>,
      "functionId": "<function-ocid>",
      "parameters": {
        "<argument-n>": "<context-variable>",
        "<argument-n>": "<context-variable>",
        "<argument-n>": "<context-variable>"
      },
      "cacheKey": [
        "<cache-key-argument-n>", "<cache-key-argument-n>"
      ]
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
  ここでは:
  - <type-value>は認証タイプです。認証に認可プロバイダ・ファンクションを使用するには、CUSTOM_AUTHENTICATIONを指定します。
  - "isAnonymousAccessAllowed": <true|false>は、オプションで、未証(つまり、匿名)のエンド・ユーザーがAPIデプロイメント仕様のルートにアクセスできるかどうかを示します。匿名のエンド・ユーザーがルートにアクセスできないようにする場合は、このプロパティをfalseに設定します。このプロパティをauthenticationポリシーに含めない場合、デフォルトのfalseが使用されます。このプロパティを使用してtrueに設定する場合は、各ルートのauthorizationポリシーでtypeプロパティを"ANONYMOUS"に設定することで、匿名アクセスが許可されているすべてのルートを明示的に指定する必要もあります。
  - <function-ocid>は、OCI関数にデプロイされた認可プロバイダ・ファンクションのOCIDです、
  - <argument-n>は、1つのコンテキスト変数の値を割り当てる引数の名前であり、1つのコンテキスト変数のみです。引数が認可プロバイダ・ファンクションに渡されます。入力する引数名は、認可プロバイダ・ファンクションが受け取ることを想定している引数名に対応している必要があります。複数の引数とコンテキストの変数ペアを含めることができます。
  - <context-variable>は、対応する引数に割り当てる値のコンテキスト変数です。<context-variable>は、<context-table-name>または<context-table-name>[<key>]の形式である必要があります。<context-table-name>は、次のいずれかです。
    - request.query: リクエストに含まれる問合せパラメータの名前と値を含むコンテキスト表。問合せパラメータを指定する場合は、request.queryコンテキスト表と問合せパラメータの名前の両方をキーとしてrequest.query[<query-parameter-name>]の書式で指定する必要があります。たとえば、request.query[state]
    - request.headers: リクエストに含まれるヘッダー名および値を含むコンテキスト表。ヘッダーを指定する場合は、request.headersコンテキスト表とヘッダーの名前の両方をキーとしてrequest.headers[<header-name>]の書式で指定する必要があります。たとえば、request.headers[X-Api-Key]
    - request.certコンテキスト表。APIクライアントによって提示され、mTLSハンドシェイク中に正常に検証された証明書のBase64エンコード・バージョンが含まれます。
    - request.host: リクエストの送信先ホストの名前を含むコンテキスト表(リクエストのHostヘッダー・フィールドから抽出)
    - request.body: リクエストの本文を含むコンテキスト表。
  - "cacheKey": ["<cache-key-argument-n>", "<cache-key-argument-n>"]は、オプションで、指定した引数のみを使用するようにキャッシュ・キーを制限します。キャッシュ・キーは、元の認証リクエストで渡された引数および引数値を使用して、認可プロバイダ・ファンクションから返されたキャッシュされたレスポンスを一意に識別します。デフォルトでは、parameters: {…}リストのすべての引数および引数値(request.bodyコンテキスト表からの値を持つ引数を除く)がキャッシュ・キーの作成に使用されます。<cache-key-argument-n>に指定する引数は、parameters: {…}リストの引数の1つである必要があります。「複数引数の認可プロバイダ・ファンクション結果のキャッシュに関するノート」を参照してください。
3. オプションで、validationFailurePolicyをauthenticationポリシー・セクションに追加します。
```
{
  "requestPolicies": {
    "authentication": {
      "type": "<type-value>",
      "isAnonymousAccessAllowed": <true|false>,
      "functionId": "<function-ocid>",
      "parameters": {
        "<argument-n>": "<context-variable>",
        "<argument-n>": "<context-variable>",
        "<argument-n>": "<context-variable>"
      },
      "cacheKey": [
        "<cache-key-argument-n>", "<cache-key-argument-n>"
      ],
      "validationFailurePolicy": {
        "type": "MODIFY_RESPONSE",
        "responseCode": "<alternative-response-code>",
        "responseMessage": "<custom-message-body>",
        "responseTransformations": {
          "headerTransformations": {
            <valid-header-transformation-response-policy>
          }
        }
      }
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
  ここでは:
  - "validationFailurePolicy": {…}では、認可プロバイダ・ファンクションがリクエストを認証できない場合、オプションで、APIクライアントへのレスポンスのHTTPステータス・コード、メッセージ本文およびヘッダーを変更できます。デフォルトでは、APIゲートウェイはHTTP 401ステータス・コードとWWW-Authenticateヘッダーをレスポンスで送信します。検証失敗ポリシーに関するノートおよび複数引数の認可プロバイダ・ファンクションからの失敗した認証レスポンスの処理を参照してください。
  - <policy-type>は、検証失敗ポリシーのタイプです。レスポンスを変更するには、MODIFY_RESPONSEを指定します。
  - "responseCode": "<alternative-response-code>"は、代替HTTPステータス・コードを指定します。例: "responseCode": "500"。または、認可プロバイダ・ファンクションによって返されたコードを返すコンテキスト変数を含めることができます。たとえば、認可プロバイダ・ファンクションがresponseCodeパラメータでレスポンス・コードを返す場合は、"request.auth[responseCode]"を指定します。
  - "responseMessage": "<custom-message-body>"は、メッセージ本文に含めるコンテンツを指定します。たとえば、"responseMessage": "Unfortunately, authentication failed."です。メッセージ本文には、任意のコンテキスト変数を含めることができます(request.bodyを除く)。たとえば、"responseMessage": "Unfortunately, authentication failed ${request.auth[my-auth-variable]}"です。
  - "headerTransformations": {<valid-header-transformation-response-policy>}は、有効なヘッダー変換レスポンス・ポリシーです。「ヘッダー変換レスポンス・ポリシーの追加」を参照してください。
APIデプロイメント仕様の各ルートに、authorizationリクエスト・ポリシーを追加します:
1. 最初のルートのbackendセクションの後にrequestPoliciesセクションを挿入します(まだ存在しない場合)。例:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "CUSTOM_AUTHENTICATION",
      .
      .
      .
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
         "type": "ORACLE_FUNCTIONS_BACKEND",
         "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {}
    }
  ]
}
```
2. 次のauthorizationポリシーをrequestPoliciesセクションに追加します:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "CUSTOM_AUTHENTICATION",
      .
      .
      .
    }
  },
  "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": 認可プロバイダ・ファンクションによって、allowedScopeプロパティで指定したアクセス・スコープのいずれかも戻された場合に、正常に認証されたエンド・ユーザーにのみアクセス権を付与します。この場合、APIデプロイメント仕様のauthenticationポリシーの"isAnonymousAccessAllowed"プロパティは無効です。
    - "ANONYMOUS": 正常に認証されていない場合でも、すべてのエンド・ユーザーにアクセス権を付与します。この場合、APIデプロイメント仕様のauthenticationポリシーで"isAnonymousAccessAllowed"プロパティを明示的にtrueに設定する必要があります。
  - "allowedScope": [ "<scope>" ]は、認可プロバイダ・ファンクションによって戻されるアクセス・スコープに対応する1つ以上の文字列のカンマ区切りリストです。この場合、typeプロパティを"ANY_OF"に設定する必要があります(typeプロパティが"AUTHENTICATION_ONLY"または"ANONYMOUS"に設定されている場合、"allowedScope"プロパティは無視されます)。また、複数のスコープを指定した場合、指定したスコープのいずれかが認可プロバイダ・ファンクションによって戻されると、ルートへのアクセス権が付与されることにも注意してください。
  たとえば、次のリクエスト・ポリシーは、read:helloスコープを持つ認証されたエンド・ユーザーのみにアクセスを許可する/helloルートを定義します:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "CUSTOM_AUTHENTICATION",
      .
      .
      .
    }
  },
  "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プロパティの設定に関係なく、次のようになります:
- ルートにアクセスできるのは、認証されたエンド・ユーザーのみです
- 認証されたすべてのエンド・ユーザーは、認可プロバイダ・ファンクションから返されたアクセス・スコープに関係なく、ルートにアクセスできます
- 匿名のエンド・ユーザーはルートにアクセスできません
APIデプロイメント仕様を含むJSONファイルを保存します。
APIデプロイメント仕様は、次の方法でAPIデプロイメントを作成または更新するときに使用します:
- 「既存のデプロイメントAPIのアップロード」オプションを選択したときに、コンソールでJSONファイルを指定します
- APIゲートウェイREST APIへのリクエストでJSONファイルを指定します
詳細は、APIデプロイの作成によるAPIゲートウェイのAPIのデプロイおよびAPIゲートウェイの更新を参照してください
(オプション) コールしてAPIが正常にデプロイされていることを確認します(APIゲートウェイにデプロイされたAPIのコールを参照)。

複数引数の認可プロバイダ・ファンクションおよびアクセス・トークンの使用に関するノート

複数引数の認可プロバイダ・ファンクション結果のキャッシュに関するノート

認可プロバイダ・ファンクションを使用する場合、APIゲートウェイはデフォルトで認可プロバイダ・ファンクションからのレスポンスを内部的にキャッシュします。レスポンスをキャッシュすると、認可プロバイダ・ファンクションを再度コールせずに、後でレスポンスを再利用して同様の認証リクエストに応答できます。

認証リクエストに対して認可プロバイダ・ファンクションによって返されたキャッシュされたレスポンスを一意に識別するために、APIゲートウェイは、レスポンスを明示した認可プロバイダ・ファンクションに渡された引数値から導出されたキャッシュ・キーを使用します。後続の認証リクエストの引数と引数の値がキャッシュ・キーと一致する場合は、認可プロバイダ・ファンクションを不必要にコールするかわりに、キャッシュされたレスポンスが使用されます。

マルチ引数認可プロバイダ・ファンクションの場合、デフォルトでは、認可プロバイダ・ファンクションに渡されるすべての引数および引数値(request.bodyコンテキスト表からの値を持つ引数を除く)がキャッシュ・キーの作成に使用されます。ただし、キャッシュ・キーの作成に使用される引数および引数値をカスタマイズできるため、キャッシュ・キーには指定した引数および引数値のみが含まれます。キャッシュ・キーから引数および引数値を削除すると、正常に認証されたリクエストに対する以前のレスポンスのキャッシュ・キーと一致する受信無効な認証リクエストのリスクが生じる可能性があることに注意してください。リクエストの認証で引数が役に立たないことを確認した場合にのみ、キャッシュ・キーから引数を削除します。

検証失敗ポリシーおよび複数引数の認可プロバイダ・ファンクションからの失敗した認証レスポンスの処理に関するノート

複数引数の認可プロバイダ・ファンクションを使用する場合は、検証失敗ポリシーを定義できます。検証失敗ポリシーを使用すると、複数引数の認可プロバイダ・ファンクションからの認証レスポンスが失敗した場合に、APIゲートウェイがAPIクライアントに送信するHTTPステータス・コード、メッセージおよびレスポンス・ヘッダーをカスタマイズできます。

アクセス・トークンがアイデンティティ・プロバイダで正常に検証されたが、アイデンティティ・プロバイダがトークンが無効であると判断した場合、複数引数の認可プロバイダ・ファンクションはHTTP 200レスポンス(レスポンスのJSON本文に"active": falseおよびWWW-Authenticateヘッダーを含む)を返す必要があります。

認可プロバイダ・ファンクションがレスポンス本文に"active": falseを指定してHTTP 200レスポンスを返す場合、デフォルトでは、APIゲートウェイはAPIクライアントにHTTP 401ステータス・コードを(レスポンスのWWW-Authenticateヘッダーとともに)送信します。ただし、検証失敗ポリシーを定義して、戻す別のHTTPステータス・コードを指定し、レスポンス本文で戻すカスタム・メッセージを指定できます。

APIゲートウェイがAPIクライアントに返すレスポンスのヘッダーを変更するために、検証失敗ポリシーにヘッダー変換レスポンス・ポリシーを含めることもできます。検証失敗ポリシーにヘッダー変換レスポンス・ポリシーを含めることで、次のことができます。

レスポンスに含めるヘッダーを制限する
(元の値を保存したまま)レスポンスに含まれるヘッダーの名前を変更します。
レスポンスに新しいヘッダーを追加する(またはレスポンスにすでに含まれている既存のヘッダーの値を変更または保持する)

検証失敗ポリシーの追加の詳細は、「JSONファイルの編集による複数引数の認証および認可のリクエスト・ポリシーの追加」を参照してください。

複数引数アクセス・トークンを使用したデプロイメント仕様の例

次のAPIデプロイメント仕様で定義します。

認証を実行する複数引数の認可プロバイダ・ファンクションをコールする認証リクエスト・ポリシー。
認証されたエンド・ユーザーが実行できる操作を指定する認可リクエスト・ポリシー。

{
  "requestPolicies": {
    "authentication": {
      "type": "CUSTOM_AUTHENTICATION",
      "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
      "isAnonymousAccessAllowed": true,
      "parameters": {
        "xapikey": "request.headers[X-Api-Key]",
        "referer": "request.headers[Referer]",
        "state": "request.query[state]",
        "city": "request.query[city]",
        "cert": "request.cert",
        "body": "request.body",
        "host": "request.host"
        },
      "cacheKey": [
        "xapikey", "referer"
        ],
      "validationFailurePolicy": {
        "type": "MODIFY_RESPONSE",
        "responseCode": "request.auth[responseCode]",
        "responseMessage": "Unfortunately, authentication failed.",
        "responseTransformations": {
        "headerTransformations": {
          "setHeaders": {
            "items": [
              {
                "name": "Location",
                "values": [
                  "${request.auth[location]}"
                  ]
                }
              ]
            },
          "filterHeaders": {
            "type": "BLOCK",
            "items": [
              {
                "name": "topSecret"
                }
              ]
            }
          }
        }
      }
    }
  },
  "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デプロイメント仕様の認証リクエスト・ポリシー:

認証を実行するためにコールする複数引数の認可プロバイダ・ファンクションを指定し、認可プロバイダ・ファンクションに渡すxapikey、referer、state、city、cert、bodyおよびhostの各引数を定義します。これらの引数の値は、元のリクエストからの値を持つコンテキスト変数から取得されます。
認可プロバイダ・ファンクションから返されたキャッシュされたレスポンスを一意に識別するカスタム・キャッシュ・キーを定義します。この認証リクエスト・ポリシーでは、認可プロバイダ・ファンクションに送信されるすべての引数を含むデフォルトのキャッシュ・キーを使用するのではなく、認可プロバイダ・ファンクションに渡されるxapikeyおよびreferrer引数の値のみをキャッシュ・キーで構成することを指定します。
デフォルトの検証失敗レスポンスを変更して、デフォルトのHTTP 401ステータス・コードをrequest.auth[responseCode]コンテキスト変数の値に置き換える検証失敗ポリシーが含まれます。request.auth[responseCode]コンテキスト変数には、認可プロバイダ・ファンクションによって戻される認証パラメータ(この場合はresponseCode)の値があります。同様に、デフォルトの検証失敗メッセージは、カスタム・メッセージ文字列("Unfortunately, authentication failed.")に置き換えられます。
locationヘッダーを検証失敗レスポンスに追加するヘッダー変換リクエスト・ポリシーを検証失敗ポリシーに含めます。locationヘッダーには、認可プロバイダ・ファンクションによって戻される認証パラメータ(この場合はlocation)の値を持つrequest.auth[location]コンテキスト変数の値が指定されます。ヘッダー変換リクエスト・ポリシーでは、レスポンスからtopSecretという名前のヘッダーも削除されます。

このAPIデプロイメント仕様の認可リクエスト・ポリシーでは、認可プロバイダ・ファンクションおよびread:helloスコープで認証されたエンド・ユーザーのみが/helloルートにアクセスできます。