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

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

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

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

ノート

Oracleでは、追加の汎用性のために、単一引数の認可プロバイダ・ファンクションではなく、複数引数の認可プロバイダ・ファンクションを使用することをお薦めします。以前のリリースでは、単一引数の認可プロバイダ・ファンクションが提供されていましたが、引き続きサポートされていました。ただし、複数引数の認可プロバイダ・ファンクションは、リクエスト・ヘッダーおよび問合せパラメータに含まれる単一引数のアクセス・トークンも受け入れることができるため、新しい単一引数の認可プロバイダ・ファンクションを作成する理由はありません。さらに、単一引数の認可プロバイダ・ファンクションは、将来のリリースで非推奨になる予定です。

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

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

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

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

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

デフォルトでは、このオプションは選択されていません。匿名のユーザーがルートにアクセスできないようにする場合は、このオプションを選択しないでください。このオプションを選択した場合は、各ルートの認可ポリシーで「匿名」を「認証タイプ」として選択することで、匿名アクセスを許可する各ルートを明示的に指定する必要もあります。
「認証タイプ」オプション・リストから「認可プロバイダ・ファンクション」を選択します。
単一引数のアクセス・トークンの認証に使用する単一引数の認可プロバイダ・ファンクションを指定します。
- Oracle Functionsアプリケーション:認可プロバイダ・ファンクションを含むOCI Functionsのアプリケーションの名前。別のコンパートメントからアプリケーションを選択できます。
- ファンクション名: OCIファンクションの認可プロバイダ・ファンクションの名前。
「単一引数の認可プロバイダ・ファンクション」を選択して、ヘッダーまたは問合せパラメータの単一引数のアクセス・トークンを単一引数の認可プロバイダ・ファンクションに渡すように指定します。
「アクセス・トークン」パネルで、認証に使用するアクセス・トークンを識別します:
- トークンの場所: 「ヘッダー」または「問合せパラメータ」を選択して、リクエスト内のアクセス・トークンの場所を指定します。
- トークン・ヘッダー名またはトークン・パラメータ名:アクセス・トークンの場所に応じて、アクセス・トークンを含むヘッダーまたは問合せパラメータの名前を入力します。
「次」を選択して、「ルート」ページの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>",
      <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">
    }
  },
  "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です、
  - <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">は、アクセス・トークンを含むリクエスト・ヘッダーであるか(そうであれば、ヘッダーの名前)またはアクセス・トークンを含む問合せパラメータであるか(そうであれば、問合せパラメータの名前)を示します。"tokenHeader": "<token-header-name>"または"tokenQueryParam": "<token-query-param-name>">のいずれかを指定できますが、両方を指定することはできません。
  たとえば、次のauthenticationポリシーでは、認可リクエスト・ヘッダーのアクセス・トークンを検証するOCIファンクションを指定します:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "CUSTOM_AUTHENTICATION",
      "isAnonymousAccessAllowed": false,
      "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
      "tokenHeader": "Authorization"
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
APIデプロイメント仕様の各ルートに、authorizationリクエスト・ポリシーを追加します:
1. 最初のルートのbackendセクションの後にrequestPoliciesセクションを挿入します(まだ存在しない場合)。例:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "CUSTOM_AUTHENTICATION",
      "isAnonymousAccessAllowed": false,
      "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
      "tokenHeader": "Authorization"
    }
  },
  "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",
      "isAnonymousAccessAllowed": false,
      "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
      "tokenHeader": "Authorization"
    }
  },
  "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",
      "isAnonymousAccessAllowed": false,
      "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
      "tokenHeader": "Authorization"
    }
  },
  "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のコールを参照)。

Oracle Cloud Infrastructureドキュメント

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

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

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