このページは、まだ日本語ではご利用いただけません。翻訳中です。
構成
このプラグインはDBレスモードに対応しています。
互換性のあるプロトコル
Kong JWT Signerプラグインは以下のプロトコルに対応しています:
grpc
, grpcs
, http
, https
パラメータ
このプラグインの設定で使用できるすべてのパラメータのリストは次のとおりです。
-
name or plugin
string requiredプラグイン名。この場合は
jwt-signer
。- Kong Admin API、Kong Konnect API、宣言型構成、または decK ファイルを使用する場合、フィールドは
name
です。 - Kubernetes で KongPlugin オブジェクトを使用する場合、フィールドは
plugin
です。
- Kong Admin API、Kong Konnect API、宣言型構成、または decK ファイルを使用する場合、フィールドは
-
instance_name
stringプラグインのインスタンスを識別するための任意のカスタム名 (例:
jwt-signer_my-service
。インスタンス名はKong ManagerとKonnectに表示されるので、 例えば複数のサービスで同じプラグインを複数のコンテキストで実行する場合に便利です。また、Kong Admin API経由で特定のプラグインインスタンスに アクセスするためにも使用できます。
インスタンス名は、次のコンテキスト内で一意である必要があります。
- Kong Gateway Enterpriseのワークスペース内
- Konnectのコントロールプレーン(CP)またはコントロールプレーン(CP)グループ内
- Kong Gateway (OSS)の全世界
-
service.name or service.id
stringプラグインが対象とするサービス名または ID。最上位の
/plugins
エンドポイント. からプラグインをサービスに追加する場合は、これらのパラメータのいずれかを設定してください/services/{serviceName|Id}/plugins
を使用する場合は必要ありません。 -
route.name or route.id
stringプラグインがターゲットとするルート名または ID。最上位の
/plugins
エンドポイント. を通るルートにプラグインを追加する場合は、これらのパラメータのいずれかを設定してください/routes/{routeName|Id}/plugins
を使用する場合は必要ありません。 -
enabled
boolean default:true
このプラグインが適用されるかどうか。
-
config
record required-
realm
stringWhen authentication or authorization fails, or there is an unexpected error, the plugin sends an
WWW-Authenticate
header with therealm
attribute value.
-
enable_hs_signatures
boolean default:false
Tokens signed with HMAC algorithms such as
HS256
,HS384
, orHS512
are not accepted by default. If you need to accept such tokens for verification, enable this setting.
-
enable_instrumentation
boolean default:false
Writes log entries with some added information using
ngx.CRIT
(CRITICAL) level.
-
access_token_issuer
string default:kong
The
iss
claim of a signed or re-signed access token is set to this value. Originaliss
claim of the incoming token (possibly introspected) is stored inoriginal_iss
claim of the newly signed access token.
-
access_token_keyset
string default:kong
The name of the keyset containing signing keys.
-
access_token_keyset_client_username
string referenceableThe client username that will be used to authenticate Kong if
access_token_keyset
is a uri that requires Basic Auth. Should be configured together withaccess_token_keyset_client_password
-
access_token_keyset_client_password
string referenceable encryptedThe client password that will be used to authenticate Kong if
access_token_keyset
is a uri that requires Basic Auth. Should be configured together withaccess_token_keyset_client_username
-
access_token_keyset_client_certificate
foreignThe client certificate that will be used to authenticate Kong if
access_token_keyset
is an https uri that requires mTLS Auth.
-
access_token_keyset_rotate_period
number default:0
Specify the period (in seconds) to auto-rotate the jwks for
access_token_keyset
. The default value 0 means no auto-rotation.
-
access_token_jwks_uri
stringSpecify the URI where the plugin can fetch the public keys (JWKS) to verify the signature of the access token.
-
access_token_jwks_uri_client_username
string referenceableThe client username that will be used to authenticate Kong if
access_token_jwks_uri
is a uri that requires Basic Auth. Should be configured together withaccess_token_jwks_uri_client_password
-
access_token_jwks_uri_client_password
string referenceable encryptedThe client password that will be used to authenticate Kong if
access_token_jwks_uri
is a uri that requires Basic Auth. Should be configured together withaccess_token_jwks_uri_client_username
-
access_token_jwks_uri_client_certificate
foreignThe client certificate that will be used to authenticate Kong if
access_token_jwks_uri
is an https uri that requires mTLS Auth.
-
access_token_jwks_uri_rotate_period
number default:0
Specify the period (in seconds) to auto-rotate the jwks for
access_token_jwks_uri
. The default value 0 means no auto-rotation.
-
access_token_request_header
string default:Authorization
This parameter tells the name of the header where to look for the access token.
-
access_token_leeway
number default:0
Adjusts clock skew between the token issuer and Kong. The value is added to the token’s
exp
claim before checking token expiry against Kong servers’ current time in seconds. You can disable access tokenexpiry
verification altogether withconfig.verify_access_token_expiry
.
-
access_token_scopes_required
array of typestring
Specify the required values (or scopes) that are checked by a claim specified by
config.access_token_scopes_claim
.
-
access_token_scopes_claim
array of typestring
default:scope
Specify the claim in an access token to verify against values of
config.access_token_scopes_required
.
-
access_token_consumer_claim
array of typestring
When you set a value for this parameter, the plugin tries to map an arbitrary claim specified with this configuration parameter (for example,
sub
orusername
) in an access token to Kong consumer entity.
-
access_token_consumer_by
array of typestring
default:username, custom_id
Must be one of:id
,username
,custom_id
When the plugin tries to apply an access token to a Kong consumer mapping, it tries to find a matching Kong consumer from properties defined using this configuration parameter. The parameter can take an array of alues. Valid values are
id
,username
, andcustom_id
.
-
access_token_upstream_header
string default:Authorization:Bearer
Removes the
config.access_token_request_header
from the request after reading its value. Withconfig.access_token_upstream_header
, you can specify the upstream header where the plugin adds the Kong signed token. If you don’t specify a value, such as usenull
or""
(empty string), the plugin does not even try to sign or re-sign the token.
-
access_token_upstream_leeway
number default:0
If you want to add or subtract (using a negative value) expiry time (in seconds) of the original access token, you can specify a value that is added to the original access token’s
exp
claim.
-
access_token_introspection_endpoint
stringWhen you use
opaque
access tokens and you want to turn on access token introspection, you need to specify the OAuth 2.0 introspection endpoint URI with this configuration parameter.
-
access_token_introspection_authorization
stringIf the introspection endpoint requires client authentication (client being the JWT Signer plugin), you can specify the
Authorization
header’s value with this configuration parameter.
-
access_token_introspection_body_args
stringThis parameter allows you to pass URL encoded request body arguments. For example:
resource=
ora=1&b=&c
.
-
access_token_introspection_hint
string default:access_token
If you need to give
hint
parameter when introspecting an access token, use this parameter to specify the value. By default, the plugin sendshint=access_token
.
-
access_token_introspection_jwt_claim
array of typestring
If your introspection endpoint returns an access token in one of the keys (or claims) within the introspection results (
JSON
). If the key cannot be found, the plugin responds with401 Unauthorized
. Also if the key is found but cannot be decoded as JWT, it also responds with401 Unauthorized
.
-
access_token_introspection_scopes_required
array of typestring
Specify the required values (or scopes) that are checked by an introspection claim/property specified by
config.access_token_introspection_scopes_claim
.
-
access_token_introspection_scopes_claim
array of typestring
required default:scope
Specify the claim/property in access token introspection results (
JSON
) to be verified against values ofconfig.access_token_introspection_scopes_required
. This supports nested claims. For example, with Keycloak you could use[ "realm_access", "roles" ]
, hich can be given asrealm_access,roles
(form post). If the claim is not found in access token introspection results, and you have specifiedconfig.access_token_introspection_scopes_required
, the plugin responds with403 Forbidden
.
-
access_token_introspection_consumer_claim
array of typestring
When you set a value for this parameter, the plugin tries to map an arbitrary claim specified with this configuration parameter (such as
sub
orusername
) in access token introspection results to the Kong consumer entity.
-
access_token_introspection_consumer_by
array of typestring
default:username, custom_id
Must be one of:id
,username
,custom_id
When the plugin tries to do access token introspection results to Kong consumer mapping, it tries to find a matching Kong consumer from properties defined using this configuration parameter. The parameter can take an array of values.
-
access_token_introspection_leeway
number default:0
Adjusts clock skew between the token issuer introspection results and Kong. The value is added to introspection results (
JSON
)exp
claim/property before checking token expiry against Kong servers current time in seconds. You can disable access token introspectionexpiry
verification altogether withconfig.verify_access_token_introspection_expiry
.
-
access_token_introspection_timeout
numberTimeout in milliseconds for an introspection request. The plugin tries to introspect twice if the first request fails for some reason. If both requests timeout, then the plugin runs two times the
config.access_token_introspection_timeout
on access token introspection.
-
access_token_signing_algorithm
string required default:RS256
Must be one of:HS256
,HS384
,HS512
,RS256
,RS512
,ES256
,ES384
,ES512
,PS256
,PS384
,PS512
,EdDSA
When this plugin sets the upstream header as specified with
config.access_token_upstream_header
, re-signs the original access token using the private keys of the JWT Signer plugin. Specify the algorithm that is used to sign the token. Theconfig.access_token_issuer
specifies whichkeyset
is used to sign the new token issued by Kong using the specified signing algorithm.
-
add_access_token_claims
mapAdd customized claims if they are not present yet. Value can be a regular or JSON string; if JSON, decoded data is used as the claim’s value.
-
set_access_token_claims
mapSet customized claims. If a claim is already present, it will be overwritten. Value can be a regular or JSON string; if JSON, decoded data is used as the claim’s value.
-
remove_access_token_claims
array of typestring
remove claims. It should be an array, and each element is a claim key string.
-
original_access_token_upstream_header
stringThe HTTP header name used to store the original access token.
-
access_token_optional
boolean default:false
If an access token is not provided or no
config.access_token_request_header
is specified, the plugin cannot verify the access token. In that case, the plugin normally responds with401 Unauthorized
(client didn’t send a token) or500 Unexpected
(a configuration error). Use this parameter to allow the request to proceed even when there is no token to check. If the token is provided, then this parameter has no effect
-
verify_access_token_signature
boolean default:true
Quickly turn access token signature verification off and on as needed.
-
verify_access_token_expiry
boolean default:true
Quickly turn access token expiry verification off and on as needed.
-
verify_access_token_scopes
boolean default:true
Quickly turn off and on the access token required scopes verification, specified with
config.access_token_scopes_required
.
-
verify_access_token_introspection_expiry
boolean default:true
Quickly turn access token introspection expiry verification off and on as needed.
-
verify_access_token_introspection_scopes
boolean default:true
Quickly turn off and on the access token introspection scopes verification, specified with
config.access_token_introspection_scopes_required
.
-
cache_access_token_introspection
boolean default:true
Whether to cache access token introspection results.
-
trust_access_token_introspection
boolean default:true
Use this parameter to enable and disable further checks on a payload before the new token is signed. If you set this to
true
, the expiry or scopes are not checked on a payload.
-
enable_access_token_introspection
boolean default:true
If you don’t want to support opaque access tokens, change this configuration parameter to
false
to disable introspection.
-
channel_token_issuer
string default:kong
The
iss
claim of the re-signed channel token is set to this value, which iskong
by default. The originaliss
claim of the incoming token (possibly introspected) is stored in theoriginal_iss
claim of the newly signed channel token.
-
channel_token_keyset
string default:kong
The name of the keyset containing signing keys.
-
channel_token_keyset_client_username
string referenceableThe client username that will be used to authenticate Kong if
channel_token_keyset
is a uri that requires Basic Auth. Should be configured together withchannel_token_keyset_client_password
-
channel_token_keyset_client_password
string referenceable encryptedThe client password that will be used to authenticate Kong if
channel_token_keyset
is a uri that requires Basic Auth. Should be configured together withchannel_token_keyset_client_username
-
channel_token_keyset_client_certificate
foreignThe client certificate that will be used to authenticate Kong if
channel_token_keyset
is an https uri that requires mTLS Auth.
-
channel_token_keyset_rotate_period
number default:0
Specify the period (in seconds) to auto-rotate the jwks for
channel_token_keyset
. The default value 0 means no auto-rotation.
-
channel_token_jwks_uri
stringIf you want to use
config.verify_channel_token_signature
, you must specify the URI where the plugin can fetch the public keys (JWKS) to verify the signature of the channel token. If you don’t specify a URI and you pass a JWT token to the plugin, then the plugin responds with401 Unauthorized
.
-
channel_token_jwks_uri_client_username
string referenceableThe client username that will be used to authenticate Kong if
channel_token_jwks_uri
is a uri that requires Basic Auth. Should be configured together withchannel_token_jwks_uri_client_password
-
channel_token_jwks_uri_client_password
string referenceable encryptedThe client password that will be used to authenticate Kong if
channel_token_jwks_uri
is a uri that requires Basic Auth. Should be configured together withchannel_token_jwks_uri_client_username
-
channel_token_jwks_uri_client_certificate
foreignThe client certificate that will be used to authenticate Kong if
access_token_jwks_uri
is an https uri that requires mTLS Auth.
-
channel_token_jwks_uri_rotate_period
number default:0
Specify the period (in seconds) to auto-rotate the jwks for
channel_token_jwks_uri
. The default value 0 means no auto-rotation.
-
channel_token_request_header
stringThis parameter tells the name of the header where to look for the channel token. If you don’t want to do anything with the channel token, then you can set this to
null
or""
(empty string).
-
channel_token_leeway
number default:0
Adjusts clock skew between the token issuer and Kong. The value will be added to token’s
exp
claim before checking token expiry against Kong servers current time in seconds. You can disable channel tokenexpiry
verification altogether withconfig.verify_channel_token_expiry
.
-
channel_token_scopes_required
array of typestring
Specify the required values (or scopes) that are checked by a claim specified by
config.channel_token_scopes_claim
.
-
channel_token_scopes_claim
array of typestring
default:scope
Specify the claim in a channel token to verify against values of
config.channel_token_scopes_required
. This supports nested claims.
-
channel_token_consumer_claim
array of typestring
When you set a value for this parameter, the plugin tries to map an arbitrary claim specified with this configuration parameter. Kong consumers have an
id
, ausername
, and acustom_id
. If this parameter is enabled but the mapping fails, such as when there’s a non-existent Kong consumer, the plugin responds with403 Forbidden
.
-
channel_token_consumer_by
array of typestring
default:username, custom_id
Must be one of:id
,username
,custom_id
When the plugin tries to do channel token to Kong consumer mapping, it tries to find a matching Kong consumer from properties defined using this configuration parameter. The parameter can take an array of valid values:
id
,username
, andcustom_id
.
-
channel_token_upstream_header
stringThis plugin removes the
config.channel_token_request_header
from the request after reading its value.
-
channel_token_upstream_leeway
number default:0
If you want to add or perhaps subtract (using negative value) expiry time of the original channel token, you can specify a value that is added to the original channel token’s
exp
claim.
-
channel_token_introspection_endpoint
stringWhen you use
opaque
access tokens and you want to turn on access token introspection, you need to specify the OAuth 2.0 introspection endpoint URI with this configuration parameter. Otherwise, the plugin does not try introspection and returns401 Unauthorized
instead.
-
channel_token_introspection_authorization
stringWhen using
opaque
channel tokens, and you want to turn on channel token introspection, you need to specify the OAuth 2.0 introspection endpoint URI with this configuration parameter. Otherwise the plugin will not try introspection, and instead returns401 Unauthorized
when using opaque channel tokens.
-
channel_token_introspection_body_args
stringIf you need to pass additional body arguments to introspection endpoint when the plugin introspects the opaque channel token, you can use this config parameter to specify them. You should URL encode the value. For example:
resource=
ora=1&b=&c
.
-
channel_token_introspection_hint
stringIf you need to give
hint
parameter when introspecting a channel token, you can use this parameter to specify the value of such parameter. By default, ahint
isn’t sent with channel token introspection.
-
channel_token_introspection_jwt_claim
array of typestring
If your introspection endpoint returns a channel token in one of the keys (or claims) in the introspection results (
JSON
), the plugin can use that value instead of the introspection results when doing expiry verification and signing of the new token issued by Kong.
-
channel_token_introspection_scopes_required
array of typestring
Use this parameter to specify the required values (or scopes) that are checked by an introspection claim/property specified by
config.channel_token_introspection_scopes_claim
.
-
channel_token_introspection_scopes_claim
array of typestring
default:scope
Use this parameter to specify the claim/property in channel token introspection results (
JSON
) to be verified against values ofconfig.channel_token_introspection_scopes_required
. This supports nested claims.
-
channel_token_introspection_consumer_claim
array of typestring
When you set a value for this parameter, the plugin tries to map an arbitrary claim specified with this configuration parameter (such as
sub
orusername
) in channel token introspection results to Kong consumer entity
-
channel_token_introspection_consumer_by
array of typestring
default:username, custom_id
Must be one of:id
,username
,custom_id
When the plugin tries to do channel token introspection results to Kong consumer mapping, it tries to find a matching Kong consumer from properties defined using this configuration parameter. The parameter can take an array of values. Valid values are
id
,username
andcustom_id
.
-
channel_token_introspection_leeway
number default:0
You can use this parameter to adjust clock skew between the token issuer introspection results and Kong. The value will be added to introspection results (
JSON
)exp
claim/property before checking token expiry against Kong servers current time (in seconds). You can disable channel token introspectionexpiry
verification altogether withconfig.verify_channel_token_introspection_expiry
.
-
channel_token_introspection_timeout
numberTimeout in milliseconds for an introspection request. The plugin tries to introspect twice if the first request fails for some reason. If both requests timeout, then the plugin runs two times the
config.access_token_introspection_timeout
on channel token introspection.
-
channel_token_signing_algorithm
string required default:RS256
Must be one of:HS256
,HS384
,HS512
,RS256
,RS512
,ES256
,ES384
,ES512
,PS256
,PS384
,PS512
,EdDSA
When this plugin sets the upstream header as specified with
config.channel_token_upstream_header
, it also re-signs the original channel token using private keys of this plugin. Specify the algorithm that is used to sign the token.
-
add_channel_token_claims
mapAdd customized claims if they are not present yet. Value can be a regular or JSON string; if JSON, decoded data is used as the claim’s value.
-
set_channel_token_claims
mapSet customized claims. If a claim is already present, it will be overwritten. Value can be a regular or JSON string; if JSON, decoded data is used as the claim’s value.
-
remove_channel_token_claims
array of typestring
remove claims. It should be an array, and each element is a claim key string.
-
original_channel_token_upstream_header
stringThe HTTP header name used to store the original channel token.
-
channel_token_optional
boolean default:false
If a channel token is not provided or no
config.channel_token_request_header
is specified, the plugin cannot verify the channel token. In that case, the plugin normally responds with401 Unauthorized
(client didn’t send a token) or500 Unexpected
(a configuration error). Enable this parameter to allow the request to proceed even when there is no channel token to check. If the channel token is provided, then this parameter has no effect
-
verify_channel_token_signature
boolean default:true
Quickly turn on/off the channel token signature verification.
-
verify_channel_token_expiry
boolean default:true
-
verify_channel_token_scopes
boolean default:true
Quickly turn on/off the channel token required scopes verification specified with
config.channel_token_scopes_required
.
-
verify_channel_token_introspection_expiry
boolean default:true
Quickly turn on/off the channel token introspection expiry verification.
-
verify_channel_token_introspection_scopes
boolean default:true
Quickly turn on/off the channel token introspection scopes verification specified with
config.channel_token_introspection_scopes_required
.
-
cache_channel_token_introspection
boolean default:true
Whether to cache channel token introspection results.
-
trust_channel_token_introspection
boolean default:true
Providing an opaque channel token for plugin introspection, and verifying expiry and scopes on introspection results may make further payload checks unnecessary before the plugin signs a new token. This also applies when using a JWT token with introspection JSON as per config.channel_token_introspection_jwt_claim. Use this parameter to manage additional payload checks before signing a new token. With true (default), payload’s expiry or scopes aren’t checked.
-
enable_channel_token_introspection
boolean default:true
If you don’t want to support opaque channel tokens, disable introspection by changing this configuration parameter to
false
.
-
add_claims
mapAdd customized claims to both tokens if they are not present yet. Value can be a regular or JSON string; if JSON, decoded data is used as the claim’s value.
-
set_claims
mapSet customized claims to both tokens. If a claim is already present, it will be overwritten. Value can be a regular or JSON string; if JSON, decoded data is used as the claim’s value.
-