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"
      }
    }
  ]
}
```

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サービスのボールトから取得されたクライアント・シークレットを含む)を使用してOAuth 2.0認可サーバーのイントロスペクション・エンドポイントでJWTトークンと非JWTトークンの両方を検証する場合は、空の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です。URLは、APIがデプロイされているAPIゲートウェイを含むサブネットからルーティングできる必要があります。
- "isSslVerifyDisabled": <true|false>は、認可サーバーとの通信時にSSL検証を無効にするかどうかを示します。JWT検証を損なう可能性があるため、Oracleではこのオプションをtrueに設定しないことをお薦めします。API Gateway trusts certificates from multiple Certificate Authorities issued for OCI IAM with Identity Domains, Oracle Identity Cloud Service (IDCS), Auth0, and Okta.
- "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つ以上の追加クレームの追加クレーム名および値を指定します(最大10個)。
    - "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 Gateway trusts certificates from multiple Certificate Authorities issued for OCI IAM with Identity Domains, Oracle Identity Cloud Service (IDCS), Auth0, and Okta.
- "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"
      }
    }
  ]
}
```
アイデンティティ・プロバイダによってすでに発行されている公開検証キーを使用したJWTの検証をAPIゲートウェイで行う場合(アイデンティティ・プロバイダに接続しなくても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"...では、アイデンティティ・プロバイダによってすでに発行されている公開検証キーを使用して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 Gateway trusts certificates from multiple Certificate Authorities issued for OCI IAM with Identity Domains, Oracle Identity Cloud Service (IDCS), Auth0, and Okta.
- "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ポリシーは、アイデンティティ・プロバイダによってすでに発行されている公開検証キーを使用してAPIゲートウェイを構成し、認可リクエスト・ヘッダーのJWTを検証します:
```
{
  "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を使用することを指定します。
  - "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トークンを含める必要があります。
    - 新しいJWTトークンをセッションCookieに格納しない場合は、このオプションをfalseに設定します。かわりに、APIゲートウェイは、X-APIGW-TOKENレスポンス・ヘッダーで人間が読めないトークンを返します。APIゲートウェイへの後続のリクエストでは、X-APIGW-TOKENリクエスト・ヘッダーに同じトークンを含める必要があります。
    Notes about Cross-Site Request Forgery (CSRF) Protectionを参照してください。
  - "useCookiesForIntermediateSteps": <true|false>は、認可フローの中間ステップ値の格納方法(リクエスト・パラメータなど)を指定します。ブラウザのCookieに値を格納するには、このオプションをtrueに設定します。APIゲートウェイに値を格納するには、このオプションをfalseに設定します。
  - "usePkce": <true|false>は、セキュリティを強化するためにPKCE (Proof Key for Code Exchange)を使用するかどうかを指定します。PKCEは、CSRF (Cross-Site Request Forgery)および認可コード・インジェクション攻撃を防ぐための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のコールを参照)。

Oracle Cloud Infrastructureドキュメント

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