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

tyk-docs/content/api-management/client-authentication.md

@@ -106,7 +106,7 @@ Allow unrestricted access for public APIs.
 Tyk has previously offered two types of OAuth authentication flow; [Tyk as the authorization server]() and Tyk connecting to an external *auth server* via a dedicated *External OAuth* option. The dedicated external *auth server* option was deprecated in Tyk 5.7.0.
 <br>
 
-For third-party OAuth integration we recommend using the JSON Web Token (JWT) middleware which is described [above]({{< 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.
+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.
 <br>
 
 The remainder of this section is left for reference and is not maintained.

tyk-docs/content/basic-config-and-security/security/authentication-authorization/json-web-tokens.md

@@ -278,7 +278,7 @@ You must provide Tyk with the secret or key to be used to validate the incoming
 
 ##### Locally Stored Keys and Secrets
 
-When storing the key or secret in the API definition, it is first base64 encoded and then configured in `server.authentication.securitySchemes.<jwtAuthScheme>.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.
+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`:
 
@@ -293,9 +293,11 @@ x-tyk-api-gateway:
 
 ##### Remotely Stored Keys (JWKS endpoint)
 
-Prior to Tyk 5.9.0, the middleware can only validate the incoming JWT against a single JWKS endpoint. The full URI (including protocol) must be base64 encoded and configured in `<jwtAuthScheme>.source`.
+###### Single JWKS endpoint
 
-For example, the following 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`:
+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`:
 
 ```yaml
 x-tyk-api-gateway:
@@ -306,7 +308,9 @@ x-tyk-api-gateway:
           source: aHR0cHM6Ly95b3VyLXRlbmFudC5hdXRoMC5jb20vLndlbGwta25vd24vandrcy5qc29u
 ```
 
-From **Tyk 5.9.0** onwards, Tyk 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.
+###### 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:
 
@@ -329,6 +333,76 @@ x-tyk-api-gateway:
 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:
+
+```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 >}}
+
+###### 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:**
+```bash
+# 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+ |
+
 ### JWT Validity and Clock Skew
 
 JSON Web Tokens have a validity period described using three [Registered Claims](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1): `IssueAt`, `ExpireAt` and `NotBefore`.