[DX-2105 / TT-15380] Enhanced JWKS caching

[andyo-tyk]

User description

Added explanation of new enhanced JWKS caching feature:

• Cache management API (delete JWKS cache) - Tyk Classic and Tyk OAS
• Cache pre-fetch - Tyk OAS only
• Configurable cache timeout - Tyk OAS only

Contributor checklist

• Reviewed PR Code suggestions and updated accordingly
• Tyklings: Labled the PR with the relevant releases
• Tyklings: Added Jira DX PR ticket to the subject

---

New Contributors

• Start the PR branch from our latest master
• I have read the repository contribution guidelines
• I have read the repository technical guidelines

---

---

PR Type

Documentation

---

Description

• Add enhanced JWKS caching docs for OAS

• Explain single vs multiple JWKS endpoints

• Document cache management API endpoints

• Clarify config fields and Classic differences

---

Diagram Walkthrough

flowchart LR
  jwt["JWT middleware"] --> jwksSrc["JWKS sources"]
  jwksSrc -- "single endpoint (Classic/OAS)" --> single["<jwtAuthScheme>.source (b64 URL)"]
  jwksSrc -- "multiple endpoints (OAS)" --> multi["<jwtAuthScheme>.jwksURIs (plain URLs)"]
  multi --> cache["Enhanced JWKS cache\n(per-URL timeouts, prefetch)"]
  api["Gateway API"] -- "DELETE /tyk/cache/jwks[/<apiID>]" --> cache

Loading

File Walkthrough

Relevant files

Documentation

client-authentication.md Minor link wording correction to JWT docs                                tyk-docs/content/api-management/client-authentication.md Fix link text from "above" to "here" Maintain reference to JWT middleware doc +1/-1      json-web-tokens.md Add enhanced JWKS caching and JWKS configuration details  tyk-docs/content/basic-config-and-security/security/authentication-authorization/json-web-tokens.md Clarify config fields for Classic vs OAS (source/jwt_source) Detail single vs multiple JWKS endpoints (5.9.0+ OAS) Add enhanced JWKS caching (timeouts, prefetch, defaults) Document JWKS cache management API endpoints (5.10.0+) +78/-4

---

[github-actions]

⚠️ Deploy preview for PR #7000 did not become live after 3 attempts.
Please check Netlify or try manually: Preview URL

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Link Context The new sentence changes the link anchor wording from "above" to "here". Verify that the referenced shortcode resolves correctly on all pages/versions and does not break existing in-page navigation. For third-party OAuth integration we recommend using the JSON Web Token (JWT) middleware which is described [here]({{< ref "basic-config-and-security/security/authentication-authorization/json-web-tokens" >}}), which offers the same functionality with a more streamlined setup and reduced risk of misconfiguration. Classic vs OAS Clarity Multiple places now mention Classic vs OAS behavior (e.g., source vs jwt_source, single vs multiple JWKS). Ensure consistent, explicit scoping for each statement to prevent readers misapplying OAS-only settings to Classic APIs. When storing the key or secret in the API definition, it is first base64 encoded and then configured in `server.authentication.securitySchemes.<jwtAuthScheme>.source` (in Tyk Classic, this is `jwt_source`). For improved separation of concerns and flexibility, the key/secret can be placed in an [external key value store]({{< ref "tyk-configuration-reference/kv-store" >}}), with the appropriate reference configured in the API definition. For example, this fragment will configure the JWT authentication middleware to use the secret located at `consul://secrets/jwt-secret` to validate the signature of incoming JWTs. Note that the external KV store reference has been base64 encoded and then stored in `source`: ```yaml x-tyk-api-gateway: server: authentication: securitySchemes: jwtAuth: source: Y29uc3VsOi8vc2VjcmV0cy9qd3Qtc2VjcmV0 Remotely Stored Keys (JWKS endpoint) Single JWKS endpoint Prior to Tyk 5.9.0 and when using Tyk Classic APIs, Tyk can only retrieve a single JSON Web Key Set, from a JWKS endpoint configured in server.authentication.securitySchemes.<jwtAuthScheme>.source (in Tyk Classic, this is jwt_source). This field accepts the base64 encoded full URI (including protocol) of the JWKS endpoint. For example, the following Tyk OAS fragment will configure the JWT authentication middleware to retrieve the JWKS from https://your-tenant.auth0.com/.well-known/jwks.json when validating the signature of incoming JWTs. Note that the JWKS endpoint has been base64 encoded and then stored in source: x-tyk-api-gateway: server: authentication: securitySchemes: jwtAuth: source: aHR0cHM6Ly95b3VyLXRlbmFudC5hdXRoMC5jb20vLndlbGwta25vd24vandrcy5qc29u Multiple JWKS endpoints From Tyk 5.9.0 onwards, Tyk OAS APIs can validate against multiple JWKS endpoints, allowing you to use different IdPs to issue JWTs for the same API. Multiple JWKS endpoints can be configured in the <jwtAuthScheme>.jwksURIs array. Note that these URIs are not base64 encoded in the API definition and so are human-readable. Tyk will retrieve the JSON Web Key Sets from each of these endpoints and these will be used to attempt validation of the received JWT. For example, the following fragment will configure the JWT authentication middleware to retrieve the JWKS from both Auth0 and Keycloak when validating the signature of incoming JWTs: x-tyk-api-gateway: server: authentication: securitySchemes: jwtAuth: jwksURIs: - url: https://your-tenant.auth0.com/.well-known/jwks.json - url: http://your-keycloak-host/realms/tyk-demo/protocol/openid-connect/certs Multiple JWKS endpoints and the jwksURIs array are not supported by Tyk Classic APIs. {{< note success >}} Note If both <jwtAuthScheme>.source and <jwtAuthScheme>.jwksURIs are configured, the latter will take precedence. {{< /note >}} JWKS caching Tyk caches the JSON Web Key Set (JWKS) retrieved from JWKS endpoints to reduce the performance impact of contacting external services during request handling. A separate cache is maintained for each JWKS endpoint for each API, with a default validity period of 240 seconds, after which the cache will be refreshed when a new request is received. From Tyk 5.10.0 onwards, we have introduced enhanced JWKS caching for Tyk OAS APIs with the following improvements: Configurable cache timeout - Set custom validity periods per JWKS endpoint Pre-fetch functionality - Automatically retrieve and cache all JWKS when the API loads to the Gateway, ensuring the first request doesn't experience the latency of fetching keys from external endpoints Cache management API - New endpoints to manually invalidate JWKS caches For example, the following fragment will configure the JWT authentication middleware to retrieve the JWKS from both Auth0 and Keycloak when validating the signature of incoming JWTs, assigning a 300 second validity period to the Auth0 JWKS and 180 second validity period for Keycloak: x-tyk-api-gateway: server: authentication: securitySchemes: jwtAuth: jwksURIs: - url: https://your-tenant.auth0.com/.well-known/jwks.json cacheTimeout: "300s" # 5 minutes - url: http://your-keycloak-host/realms/tyk-demo/protocol/openid-connect/certs cacheTimeout: "3m" # 3 minutes (alternative format) Configuration Options Field Type Description Default Supported Formats url string JWKS endpoint URL Required Full URI including protocol cacheTimeout string Cache validity period 240s "300s", "5m", "1h", etc. {{< note success >}} Note Tyk Classic APIs continue to use the existing JWKS caching behavior with the 240-second default timeout. The enhanced caching features are available only for Tyk OAS APIs. {{< /note >}} JWKS Cache Management New Gateway API endpoints are available from Tyk 5.10.0 to manage JWKS caches programmatically. These endpoints work for both Tyk OAS and Tyk Classic APIs: Endpoint Method Description /tyk/cache/jwks DELETE Invalidate JWKS caches for all APIs /tyk/cache/jwks/{apiID} DELETE Invalidate JWKS cache for a specific API Note: These endpoints are currently available only through the Tyk Gateway API and are not yet extended to the Tyk Dashboard API. Example usage: # Flush all JWKS caches curl -X DELETE http://your-gateway:8080/tyk/cache/jwks \ -H "x-tyk-authorization: your-secret" # Flush JWKS cache for specific API curl -X DELETE http://your-gateway:8080/tyk/cache/jwks/your-api-id \ -H "x-tyk-authorization: your-secret" Feature Compatibility Summary Feature Tyk Classic Tyk OAS Available From Single JWKS endpoint ✅ ✅ All versions Multiple JWKS endpoints ❌ ✅ Tyk 5.9.0+ Configurable cache timeout ❌ ✅ Tyk 5.10.0+ Pre-fetch functionality ❌ ✅ Tyk 5.10.0+ Cache management API ✅ ✅ Tyk 5.10.0+ </details> <details><summary><a href='https://github.com/TykTechnologies/tyk-docs/pull/7000/files#diff-5f5816c71b61e522b61858ca547fc6349325f0c7a4683b1c7c3a9e641b7b3f53R338-R373'><strong>Caching Defaults</strong></a> JWKS caching default is stated as 240 seconds; confirm this remains accurate across versions and both Classic and OAS, especially with prefetch enabled, and document any cache invalidation behavior on API reloads. </summary> ```markdown Tyk caches the JSON Web Key Set (JWKS) retrieved from JWKS endpoints to reduce the performance impact of contacting external services during request handling. A separate cache is maintained for each JWKS endpoint for each API, with a default validity period of *240 seconds*, after which the cache will be refreshed when a new request is received. From **Tyk 5.10.0** onwards, we have introduced enhanced JWKS caching for Tyk OAS APIs with the following improvements: - **Configurable cache timeout** - Set custom validity periods per JWKS endpoint - **Pre-fetch functionality** - Automatically retrieve and cache all JWKS when the API loads to the Gateway, ensuring the first request doesn't experience the latency of fetching keys from external endpoints - **Cache management API** - New endpoints to manually invalidate JWKS caches For example, the following fragment will configure the JWT authentication middleware to retrieve the JWKS from both Auth0 and Keycloak when validating the signature of incoming JWTs, assigning a 300 second validity period to the Auth0 JWKS and 180 second validity period for Keycloak: ```yaml x-tyk-api-gateway: server: authentication: securitySchemes: jwtAuth: jwksURIs: - url: https://your-tenant.auth0.com/.well-known/jwks.json cacheTimeout: "300s" # 5 minutes - url: http://your-keycloak-host/realms/tyk-demo/protocol/openid-connect/certs cacheTimeout: "3m" # 3 minutes (alternative format) Configuration Options Field Type Description Default Supported Formats url string JWKS endpoint URL Required Full URI including protocol cacheTimeout string Cache validity period 240s "300s", "5m", "1h", etc. {{< note success >}} Note Tyk Classic APIs continue to use the existing JWKS caching behavior with the 240-second default timeout. The enhanced caching features are available only for Tyk OAS APIs. {{< /note >}} </details> </td></tr> </table>

[github-actions]

PR Code Suggestions ✨

No code suggestions found for the PR.

[netlify]

✅ PS. Add to the end of url /docs/nightly

Name	Link
🔨 Latest commit	0c0f15b
🔍 Latest deploy log	https://app.netlify.com/projects/tyk-docs/deploys/68dfc7155539610008c090eb
😎 Deploy Preview	https://deploy-preview-7000--tyk-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[netlify]

✅ PS. Add to the end of url /docs/nightly

Name	Link
🔨 Latest commit	f0288fd
🔍 Latest deploy log	https://app.netlify.com/projects/tyk-docs/deploys/68e7a15ee849160007afa8bb
😎 Deploy Preview	https://deploy-preview-7000--tyk-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[sharadregoti]

We should avoid using H5 & H6 headers. This makes the right side navigation nested.

We need to split this page and rearrange the sections in the right-side navigation.