---
title: JwkSetSecretStore
description: Manages a secret store for JSON Web Keys (JWK) from a local or remote JWK Set.
component: pinggateway
version: 7.2
page_id: pinggateway:reference:JwkSetSecretStore
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/JwkSetSecretStore.html
llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
revdate: 2025-06-22T16:30:54Z
superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/JwkSetSecretStore.html
section_ids:
  JwkSetSecretStore-usage: Usage
  JwkSetSecretStore-properties: Properties
  JwkSetSecretStore-log: Log level
  JwkSetSecretStore-example: Example
  JwkSetSecretStore-moreinfo: More information
---

# JwkSetSecretStore

Manages a secret store for JSON Web Keys (JWK) from a local or remote JWK Set.

The secrets provider queries the JwkSetSecretStore, as follows:

* If the JWT contains a `kid`, the secrets provider queries the JwkSetSecretStore for a named secret, identified by value of the `kid` of a JWK stored in the JwkSetSecretStore.

* If the JWT doesn't contain a `kid`, the secrets provider queries the JwkSetSecretStore for list of valid secrets, whose purpose matches the secret ID and any purpose contraints. The JwkSetSecretStore returns the secrets in the order that they are listed in the JWK set.

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, see [Secrets](../gateway-guide/about.html#about-secrets).

Learn about JWKs and JWK Sets in [JSON Web Key (JWK)](https://www.rfc-editor.org/rfc/rfc7517).

## Usage

```json
{
  "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](preface.html#definition-url)>, required*

  A URL that contains the client's public keys in JWK format.

* `"handler"`: *Handler [reference](preface.html#definition-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](preface.html#definition-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](preface.html#definition-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](preface.html#definition-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` or `unlimited`, IG 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`:

```xml
<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, see [Validate signed access_tokens with the StatelessAccessTokenResolver and JwkSetSecretStore](../gateway-guide/oauth2-rs.html#oauth2-rs-stateless-signed-sat).

## More information

[org.forgerock.openig.secrets.JwkSetSecretStoreHeaplet](../_attachments/apidocs/org/forgerock/openig/secrets/JwkSetSecretStoreHeaplet.html)

[JSON Web Key (JWK)](https://www.rfc-editor.org/rfc/rfc7517)