From 23e7f9b4f6880fe4b23ae7832a5dbe15a3809713 Mon Sep 17 00:00:00 2001 From: Charles Rea Date: Fri, 17 Jul 2026 12:33:25 +0100 Subject: [PATCH 1/2] feat: Add guidance on JWKS caching --- .../json-web-tokens/json-web-key-sets.mdx | 20 +++++++++++++++++++ .../locate-json-web-key-sets.mdx | 2 +- .../secure/tokens/token-best-practices.mdx | 2 +- 3 files changed, 22 insertions(+), 2 deletions(-) diff --git a/main/docs/secure/tokens/json-web-tokens/json-web-key-sets.mdx b/main/docs/secure/tokens/json-web-tokens/json-web-key-sets.mdx index f25d491775..02ea247c26 100644 --- a/main/docs/secure/tokens/json-web-tokens/json-web-key-sets.mdx +++ b/main/docs/secure/tokens/json-web-tokens/json-web-key-sets.mdx @@ -21,6 +21,26 @@ Currently, Auth0 signs with only one JWK at a time; however, it is important to +## Cache the JSON Web Key Set + +We recommend that you cache the JWKS your application retrieves from the JWKS endpoint, as this will: + +* Improve performance by avoiding a network request to the JWKS endpoint on every token validation. +* Avoid consuming your tenant's [rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy) with repeated requests. +* Improve resiliency, so your application can continue validating tokens if the JWKS endpoint is briefly unavailable. + +### Pick up rotated keys + +Cache the JWKS for at least 5-10 minutes to avoid fetching it on every request. Longer intervals further reduce requests and latency. + +When you [rotate signing keys](/docs/get-started/tenant-settings/signing-keys/rotate-signing-keys), Auth0 signs new tokens with the new key. If you validate a token whose key ID (`kid`) is not in your cached JWKS, invalidate your cache and fetch the JWKS again to retrieve the new key. This refetch on an unknown `kid` - not the cache lifetime - is what lets your application pick up rotated keys promptly, so a longer cache interval does not delay rotation. + +Limit how often you refetch on a cache miss - for example, retry only once - so that a batch of tokens signed with unknown keys cannot trigger a flood of requests to the JWKS endpoint and consume your rate limits. Set your cache interval based on how quickly you need to stop accepting tokens signed with a manually [revoked key](/docs/get-started/tenant-settings/signing-keys/revoke-signing-keys). + +### Use a library + +Rather than implement caching yourself, use a JWKS library or your framework's middleware that caches keys, refetches on an unknown `kid`, and rate-limits those refetches. Our [Quickstarts](/docs/quickstarts) use libraries that handle this for you. + ## Learn more * [Signing Keys](/docs/get-started/tenant-settings/signing-keys) diff --git a/main/docs/secure/tokens/json-web-tokens/locate-json-web-key-sets.mdx b/main/docs/secure/tokens/json-web-tokens/locate-json-web-key-sets.mdx index 9566a7ece3..a9e086c66d 100644 --- a/main/docs/secure/tokens/json-web-tokens/locate-json-web-key-sets.mdx +++ b/main/docs/secure/tokens/json-web-tokens/locate-json-web-key-sets.mdx @@ -20,7 +20,7 @@ For more info about the structure of a JWT, see [JSON Web Token Structure](/docs It's good practice to assume that multiple signing keys could be present in your JWKS. This may seem unnecessary since the Auth0 JWKS endpoint typically contains a single signing key; however, multiple keys can be found in the JWKS when rotating signing certificates. -We recommend that you cache your signing keys to improve application performance and avoid running into [rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy), but you will want to make sure that if decoding a token fails, you invalidate the cache and retrieve new signing keys before trying **only one** more time. +We recommend that you cache your signing keys to improve application performance and avoid running into rate limits. To learn how to cache safely and still pick up rotated keys, read [Cache the JSON Web Key Set](/docs/secure/tokens/json-web-tokens/json-web-key-sets#cache-the-json-web-key-set). ## Learn more diff --git a/main/docs/secure/tokens/token-best-practices.mdx b/main/docs/secure/tokens/token-best-practices.mdx index 0683c8c7ad..baf5829ca5 100644 --- a/main/docs/secure/tokens/token-best-practices.mdx +++ b/main/docs/secure/tokens/token-best-practices.mdx @@ -96,7 +96,7 @@ The most secure practice, and our recommendation, is to use **RS256** because: It's good practice to assume that multiple signing keys could be present in your JWKS. This may seem unnecessary since the Auth0 JWKS endpoint typically contains a single signing key; however, multiple keys can be found in the JWKS when rotating signing certificates. -We recommend that you cache your signing keys to improve application performance and avoid running into rate limits, but you will want to make sure that if decoding a token fails, you invalidate the cache and retrieve new signing keys before trying **only one** more time. +We recommend that you cache your signing keys to improve application performance and avoid running into rate limits. To learn how to cache safely and still pick up rotated keys, read [Cache the JSON Web Key Set](/docs/secure/tokens/json-web-tokens/json-web-key-sets#cache-the-json-web-key-set). ## Learn more From 96da9394f983e1796939700c7c52c7bd92882eb2 Mon Sep 17 00:00:00 2001 From: Charles Rea Date: Fri, 17 Jul 2026 16:39:13 +0100 Subject: [PATCH 2/2] Updates following review feedback --- .../tokens/json-web-tokens/json-web-key-sets.mdx | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/main/docs/secure/tokens/json-web-tokens/json-web-key-sets.mdx b/main/docs/secure/tokens/json-web-tokens/json-web-key-sets.mdx index 02ea247c26..cf0383331c 100644 --- a/main/docs/secure/tokens/json-web-tokens/json-web-key-sets.mdx +++ b/main/docs/secure/tokens/json-web-tokens/json-web-key-sets.mdx @@ -23,23 +23,22 @@ Currently, Auth0 signs with only one JWK at a time; however, it is important to ## Cache the JSON Web Key Set -We recommend that you cache the JWKS your application retrieves from the JWKS endpoint, as this will: +You should ensure that you cache the JWKS your application retrieves from the JWKS endpoint, as this will: -* Improve performance by avoiding a network request to the JWKS endpoint on every token validation. * Avoid consuming your tenant's [rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy) with repeated requests. +* Improve performance by avoiding a network request to the JWKS endpoint on every token validation. * Improve resiliency, so your application can continue validating tokens if the JWKS endpoint is briefly unavailable. -### Pick up rotated keys +Rather than implement caching yourself, we recommend you use a JWKS library or your framework's middleware that caches keys, refetches on an unknown `kid`, and rate-limits those refetches. Our [Quickstarts](/docs/quickstarts) use libraries that handle this for you. If you instead implement this yourself, follow the guidance below. + +### Implementation guidance Cache the JWKS for at least 5-10 minutes to avoid fetching it on every request. Longer intervals further reduce requests and latency. -When you [rotate signing keys](/docs/get-started/tenant-settings/signing-keys/rotate-signing-keys), Auth0 signs new tokens with the new key. If you validate a token whose key ID (`kid`) is not in your cached JWKS, invalidate your cache and fetch the JWKS again to retrieve the new key. This refetch on an unknown `kid` - not the cache lifetime - is what lets your application pick up rotated keys promptly, so a longer cache interval does not delay rotation. +When you [rotate signing keys](/docs/get-started/tenant-settings/signing-keys/rotate-signing-keys), Auth0 signs new tokens with the new key. If you receive a token whose key ID (`kid`) is not in your cached JWKS, invalidate your cache and fetch the JWKS again to retrieve the new key. This refetch on an unknown `kid` - not the cache lifetime - is what lets your application pick up rotated keys promptly, so a longer cache interval does not delay rotation. Limit how often you refetch on a cache miss - for example, retry only once - so that a batch of tokens signed with unknown keys cannot trigger a flood of requests to the JWKS endpoint and consume your rate limits. Set your cache interval based on how quickly you need to stop accepting tokens signed with a manually [revoked key](/docs/get-started/tenant-settings/signing-keys/revoke-signing-keys). -### Use a library - -Rather than implement caching yourself, use a JWKS library or your framework's middleware that caches keys, refetches on an unknown `kid`, and rate-limits those refetches. Our [Quickstarts](/docs/quickstarts) use libraries that handle this for you. ## Learn more