JWT_AUTHENTICATION認証リクエスト・ポリシーの使用(非推奨)
JWT_AUTHENTICATIONタイプの認証リクエスト・ポリシーを使用する場合、エンド・ユーザーは、認証および認可にJSON Webトークン(JWT)を使用するAPIデプロイメントにアクセスする前に、アイデンティティ・プロバイダからJWTを取得する必要があります。
以前のリリースでは、認証にJWTを使用するJWT_AUTHENTICATIONタイプの認証リクエスト・ポリシーを作成していた可能性があります。
JWTを使用するための新しい認証リクエスト・ポリシーを作成する場合は、かわりにタイプTOKEN_AUTHENTICATIONの認証リクエスト・ポリシーを作成することをお薦めします(コンソールを使用したトークン認証および認可リクエスト・ポリシーの追加およびトークン認証および認可リクエスト・ポリシーを追加するためのJSONファイルの編集を参照)。また、既存のJWT_AUTHENTICATIONリクエスト・ポリシーをTOKEN_AUTHENTICATIONポリシーに移行することをお薦めします。
既存のJWT_AUTHENTICATIONリクエスト・ポリシーは、現在もサポートされています。また、APIデプロイメント仕様をJSONファイル(この項の元の手順を参照)で定義することで、新しいJWT_AUTHENTICATIONリクエスト・ポリシーを作成できますが、かわりに、タイプTOKEN_AUTHENTICATIONの認証リクエスト・ポリシーを作成することをお薦めします。
APIゲートウェイにデプロイされたAPIをコールする場合、APIクライアントはJWTを問合せパラメータまたはリクエストのヘッダーとして指定します。APIゲートウェイは、発行アイデンティティ・プロバイダが提供する対応する公開検証キーを使用してJWTを検証します。APIデプロイメントのJWT_AUTHENTICATION認証リクエスト・ポリシーを使用して、APIゲートウェイによるJWTの検証方法を構成できます:
- 実行時にアイデンティティ・プロバイダから公開検証キーを取得するようにAPIゲートウェイを構成できます。この場合、アイデンティティ・プロバイダは認可サーバーとして機能します。
- APIゲートウェイは、アイデンティティ・プロバイダによってすでに発行されている公開検証キー(「静的キー」と呼ばれる)を使用して事前に構成できるため、APIゲートウェイはアイデンティティ・プロバイダに接続しなくても実行時にJWTをローカルで検証できます。その結果、トークン検証が高速になります。
JSONファイルのAPIデプロイメント仕様に新しいJWT_AUTHENTICATION認証および認可リクエスト・ポリシーを追加するには:
-
APIデプロイメント仕様のすべてのルートに適用する
authenticationリクエスト・ポリシーを追加します:-
routesセクションの前にrequestPoliciesセクションを挿入します(まだ存在しない場合)。例:{ "requestPolicies": {}, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] } -
次の
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ゲートウェイを構成します。アイデンティティ・プロバイダによってすでに発行されている公開検証キーを使用してAPIゲートウェイを構成するには、STATIC_KEYSを指定します(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 Gateway trusts certificates from multiple Certificate Authorities issued for OCI IAM with Identity Domains, Oracle Identity Cloud Service (IDCS), Auth0, and Okta.
例:
"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のコールを参照)。
例: 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"
]
}
}
}
]
}