JwkSetSecretStore
A secret store of JSON Web Keys (JWK) from a local or remote JWK Set.
This Secret store can only manage secrets of the CryptoKey type.
The secrets provider builds the secret, checking that the secret’s constraints are met, and returns a unique secret. If the secret’s constraints are not met, the secrets provider cannot build the secret and the secret query fails.
For a description of how secrets are managed, refer to About secrets.
For information about JWKs and JWK Sets, refer to JSON Web Key (JWK).
Usage
{
"name": string,
"type": "JwkSetSecretStore",
"config": {
"jwkUrl": configuration expression<url>,
"handler": Handler reference,
"cacheTimeout": configuration expression<duration>,
"cacheMissCacheTime": configuration expression<duration>,
"leaseExpiry": configuration expression<duration>
}
}
Properties
"jwkUrl"
: configuration expression<url>, required-
A URL that contains the client’s public keys in JWK format.
"handler"
: Handler reference, optional-
An HTTP client handler to communicate with the
jwkUrl
.Usually set this property to the name of a ClientHandler configured in the heap, or a chain that ends in a ClientHandler.
Default: ClientHandler
"cacheTimeout"
: configuration expression<duration>, optional-
Delay before the cache is reloaded. The cache contains the
jwkUrl
.The cache cannot be deactivated. If a value lower than 10 seconds is configured, a warning is logged and the default value is used instead.
Default: 2 minutes
"cacheMissCacheTime"
: configuration expression<duration>, optional-
If the
jwkUrl
is looked up in the cache and is not found, this is the delay before the cache is reloaded.Default: 2 minutes
"leaseExpiry"
: configuration expression<duration>, optional-
The amount of time that secrets produced by this store can be cached before they must be refreshed.
If the duration is
zero
orunlimited
, PingGateway issues a warning, and uses the default value.Default: 5 minutes
Log level
To facilitate debugging secrets for the JwkSetSecretStore, in
logback.xml
add a logger defined by the fully qualified package name of the
JwkSetSecretStore. The following line in logback.xml
sets the log level to ALL
:
<logger name="org.forgerock.secrets.jwkset" level="ALL">
Example
For an example of how to set up and use JwkSetSecretStore to validate signed access tokens, refer to Validate signed access_tokens with the StatelessAccessTokenResolver and JwkSetSecretStore.
In the following example, a StatelessAccessTokenResolver validates a signed access token by using a JwkSetSecretStore:
"accessTokenResolver": {
"type": "StatelessAccessTokenResolver",
"config": {
"secretsProvider": {
"type": "JwkSetSecretStore",
"config": {
"jwkUrl": "http://am.example.com:8088/openam/oauth2/connect/jwk_uri"
},
"issuer": "http://am.example.com:8088/openam/oauth2",
"verificationSecretId": "verification.secret.id"
}
}
}
The JWT signature is validated as follows:
-
If the JWT contains a
kid
with a matching secret in the JWK set:-
The secrets provider queries the JwkSetSecretStore for a named secret.
-
The JwkSetSecretStore returns the matching secret, identified by a stable ID.
-
The StatelessAccessTokenResolver tries to validate the signature with that named secret. If it fails, the token is considered as invalid.
In the route, note that the property
verificationSecretId
must be configured but is not used in named secret resolution. -
-
If the JWT contains a
kid
without a matching secret in the JWK set:-
The secrets provider queries the JwkSetSecretStore for a named secret.
-
Because the referenced JWK set doesn’t contain a matching secret, named secret resolution fails. PingGateway tries valid secret resolution in the same way as when the JWT doesn’t contain a
kid
.
-
-
If the JWT doesn’t contain a
kid
:-
The secrets provider queries the JwkSetSecretStore for list of valid secrets, whose secret ID is
verification.secret.id
. -
The JwkSetSecretStore returns all secrets in the JWK set whose purpose is signature verification. For example, signature verification keys can have the following JWK parameters:
{ "use": "sig" }
{ "key_opts": [ "verify" ] }
Secrets are returned in the order that they are listed in the JWK set.
-
The StatelessAccessTokenResolver tries to validate the signature with each secret sequentially, starting with the first, and stopping when it succeeds.
-
If none of the valid secrets can verify the signature, the token is considered as invalid.
-