Docs for 5.10

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/api-management/gateway-events.md

@@ -60,15 +60,11 @@ Three different categories of *event handler* can be registered for each event:
 - your own [custom event handler]({{< ref "api-management/gateway-events#custom-api-event-handlers" >}}) that will run in a JavaScript virtual machine on the Tyk server
 
 {{< note success >}}
-**Note**  
+**Note**
 
 Remember that <b>quota usage monitoring</b> has a [dedicated mechanism]({{< ref "api-management/gateway-events#monitoring-quota-consumption" >}}) for handling these special events.
 {{< /note >}}
 
-### Event metadata
-
-When an API event is fired, if there is an *event handler* registered for that combination of API and event then the handler will be provided with a rich set of [metadata]({{< ref "api-management/gateway-events#event-metadata-1" >}}) that can be used by the external system (webhook) or custom (JavaScript) code to determine the action to be taken.
-
 ## Event Types
 
 The built-in events that Tyk Gateway will generate are:
@@ -111,21 +107,58 @@ The built-in events that Tyk Gateway will generate are:
 - `TokenUpdated`: a token has been changed/updated
 - `TokenDeleted`: a token has been deleted
 
+### Certificate expiry events
+
+- `CertificateExpiringSoon`: a certificate has been used within the expiry threshold and should be updated
+- `CertificateExpired`: an expired certificate has been used in a request
+
 ## Event Metadata
 
-When Tyk generates an [event]({{< ref "api-management/gateway-events#event-types" >}}) it will compile the following metadata that is passed to the event handler:
+When an event is fired, and an *event handler* is registered for that specific API and event combination, Tyk Gateway provides the handler with a rich set of [metadata]({{< ref "api-management/gateway-events#event-metadata" >}}). The external system (webhook) or custom (JavaScript) code can then use this metadata to decide what action to take.
 
-- `Message` (string): a human readable message from Tyk Gateway that adds detail about the event
-- `Path` (string): the path of the API endpoint request that led to the event being fired
-- `Origin` (string): origin data for the source of the request (if this exists)
-- `Key` (string): the key that was used in the request
-- `OriginatingRequest` (string): Based64-encoded [raw inbound request](#raw-request-data)
+Most events provide common metadata as follows:
 
-{{< note success >}}
-**Note**  
+- `message` (string): a human-readable message from Tyk Gateway that provides details about the event
+- `path` (string): the path of the API endpoint request that led to the event being fired
+- `origin` (string): origin data for the source of the request (if this exists)
+- `key` (string): the key that was used in the request
+- `originating_request` (string): a Base64-encoded [raw inbound request]({{< ref "#raw-request-data" >}})
 
-Circuit breaker events provide different metadata, see [Circuit Breakers]({{< ref "planning-for-production/ensure-high-availability/circuit-breakers/" >}}) to see what is provided when the `BreakerTripped`, `BreakerReset` or `BreakerTriggered` events are generated.
-{{< /note >}}
+### Specific Event Metadata
+
+Some events provide alternative metadata specific to that event. The following sections detail the event-specific metadata provided for such events.
+
+<ul>
+
+<li>
+<details>
+<summary>CertificateExpiringSoon</summary>
+
+- `message` (string): a human readable message from Tyk Gateway that adds detail about the event
+- `cert_id` (string): the certificate ID
+- `cert_name` (string): the name of the certificate
+- `expires_at` (string, RFC3339): the certificate expiry date
+- `days_remaining` (integer): the remaining days until the certificate expires
+- `api_id`(string): the ID of the API that triggered the event
+
+</details>
+</li>
+
+<li>
+<details>
+<summary>CertificateExpired</summary>
+
+- `message` (string): a human readable message from Tyk Gateway that adds detail about the event
+- `cert_id` (string): the certificate ID
+- `cert_name` (string): the name of the certificate
+- `expired_at` (string, RFC3339): the date when the certificate expired
+- `days_since_expiry` (integer): the number of days since the certificate expired
+- `api_id`(string): the ID of the API that triggered the event
+
+</details>
+</li>
+
+</ul>
 
 ### Using the metadata
 
@@ -143,7 +176,7 @@ The Tyk platform can be configured to log at various verbosity levels (info, deb
 
 <br>
 {{< note success >}}
-**Note**  
+**Note**
 
 Logging event handlers are currently only supported by Tyk Classic APIs.
 {{< /note >}}
@@ -218,7 +251,7 @@ When an API circuit breaker triggers due to an unresponsive upstream service, th
 
 With Tyk Gateway, the webhook event handler is a process that runs asynchronously in response to an API event being fired. It will issue an HTTP request to any open endpoint and is fully configurable within the API definition.
 
-The HTTP method, body, header values, and target URL can all be configured in the API definition. The [request body](#webhook-payload) is generated using a Tyk template file that has access to the [event metadata]({{< ref "api-management/gateway-events#event-metadata-1" >}}).
+The HTTP method, body, header values, and target URL can all be configured in the API definition. The [request body](#webhook-payload) is generated using a Tyk template file that has access to the [event metadata]({{< ref "api-management/gateway-events#event-metadata" >}}).
 
 The webhook event handler runs in its own process and so does not block the operation of the Gateway.
 
@@ -232,7 +265,7 @@ When your webhook event handler is triggered, it will send an HTTP request to th
 
 If no template is provided in the webhook event handler configuration in the API definition, Tyk Gateway will look for the default file `templates/default_webhook.json`. Any text file accessible to the Gateway can be used to store the Go template to be used by the event handler when constructing the payload.
 
-The event handler has access to the [event metadata]({{< ref "api-management/gateway-events#event-metadata-1" >}}) and this can be accessed by the template using the `{{.Meta.XXX}}` namespace.
+The event handler has access to the [event metadata]({{< ref "api-management/gateway-events#event-metadata" >}}) and this can be accessed by the template using the `{{.Meta.XXX}}` namespace.
 
 The [event type]({{< ref "api-management/gateway-events#event-types" >}}) that triggered the event handler can be accessed as `{{.Type}}`.
 
@@ -454,7 +487,7 @@ Note, however, that to test this you will need to create a *global webhook* in y
 <br>
 <br>
 {{< note success >}}
-**Note**  
+**Note**
 
 When a *global webhook* is registered to a Tyk OAS API, Tyk will create a read-only copy of the webhook [configuration](#local-webhook-configuration) (`url`, `method`, `bodyTemplate`, `headers`) within the API definition. This is so that Tyk Gateway knows how to handle the event, as it does not have access to the store of *global webhooks* registered with Tyk Dashboard.
 <br>
@@ -465,7 +498,7 @@ If the global webhook is subsequently deleted from the Tyk Dashboard, the webhoo
 
 #### Set up a webhook event handler in the Tyk Dashboard
 
-It is very simple to register webhooks to be triggered in response to specific API events when using Tyk OAS APIs with the Tyk Dashboard. The API Designer in the Dashboard allows you to define *local webhooks* and to register *global webhooks* to handle events. 
+It is very simple to register webhooks to be triggered in response to specific API events when using Tyk OAS APIs with the Tyk Dashboard. The API Designer in the Dashboard allows you to define *local webhooks* and to register *global webhooks* to handle events.
 
 If you want to use a *global webhook* then you'll need to declare it first, following [these instructions]({{< ref "api-management/gateway-events#creating-a-global-webhook-definition-using-tyk-dashboard" >}}).
 
@@ -663,7 +696,7 @@ The Tyk platform can be configured to log at various verbosity levels (info, deb
 
 <br>
 {{< note success >}}
-**Note**  
+**Note**
 
 Logging event handlers are currently only supported by Tyk Classic APIs.
 {{< /note >}}
@@ -720,7 +753,7 @@ Custom event handlers have access to the [JavaScript API]({{< ref "api-managemen
 
 <br>
 {{< note success >}}
-**Note**  
+**Note**
 
 Custom event handlers are currently only supported by Tyk Classic APIs.
 {{< /note >}}
@@ -745,7 +778,7 @@ sampleHandler.NewHandler(function(event, context) {
 
 #### The `event` object
 
-This contains the [event metadata]({{< ref "api-management/gateway-events#event-metadata-1" >}}) in the following structure:
+This contains the [event metadata]({{< ref "api-management/gateway-events#event-metadata" >}}) in the following structure:
 
 ```json
 {
@@ -821,7 +854,7 @@ Unlike API event [webhooks]({{< ref "api-management/gateway-events#event-handlin
 
 <br>
 {{< note success >}}
-**Note**  
+**Note**
 
 Advanced quota threshold monitoring is currently only supported by Tyk Classic APIs.
 {{< /note >}}
@@ -861,7 +894,7 @@ With this configuration, a monitor is configured to issue a request to `POST htt
 
 <br>
 {{< note success >}}
-**Note**  
+**Note**
 
 If you are using our [Classic Developer Portal]({{< ref "tyk-developer-portal/tyk-portal-classic/portal-events-notifications" >}}), developers registered in the portal will also receive emails about quota threshold limits being reached.
 {{< /note >}}
@@ -904,7 +937,7 @@ When the quota consumption monitor is fired, the webhook request that is issued
 
 <br>
 {{< warning success >}}
-**Warning**  
+**Warning**
 
 When the monitor is triggered by a user hitting their quota threshold, the <b>raw API key</b> is provided in the webhook payload. It is important to secure the webhook endpoint and to handle the payload securely on the receiving end.
 {{< /warning >}}

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`.