[TT-15719] Gateway 5.10: Update documentation for master

tyk-docs/assets/others/gateway-swagger.yml

@@ -1603,6 +1603,66 @@ paths:
       summary: Invalidate cache.
       tags:
       - Cache Invalidation
+  /tyk/cache/jwks/{apiID}:
+    delete:
+      description: Invalidate JWK cache for the given API.
+      operationId: invalidateJWKCache
+      parameters:
+        - description: The API ID.
+          example: ae67bb862a3241a49117508e0f9ee839
+          in: path
+          name: apiID
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          content:
+            application/json:
+              example:
+                message: cache invalidated
+                status: ok
+              schema:
+                $ref: '#/components/schemas/ApiStatusMessage'
+          description: Cache invalidated.
+        "403":
+          content:
+            application/json:
+              example:
+                message: Attempted administrative access with invalid or missing key!
+                status: error
+              schema:
+                $ref: '#/components/schemas/ApiStatusMessage'
+          description: Forbidden
+      summary: Invalidate cache for given API ID.
+      tags:
+        - JWK cache invalidation
+  /tyk/cache/jwks:
+    delete:
+      description: Invalidate JWK cache for all APIs.
+      operationId: invalidateJWKCacheForAllAPIs
+      responses:
+        "200":
+          content:
+            application/json:
+              example:
+                message: cache invalidated
+                status: ok
+              schema:
+                $ref: '#/components/schemas/ApiStatusMessage'
+          description: Cache invalidated.
+        "403":
+          content:
+            application/json:
+              example:
+                message: Attempted administrative access with invalid or missing key!
+                status: error
+              schema:
+                $ref: '#/components/schemas/ApiStatusMessage'
+          description: Forbidden
+      summary: Invalidate JWK cache for all APIs
+      tags:
+        - JWK cache invalidation
   /tyk/certs:
     get:
       description: List all certificates in the Tyk Gateway.

tyk-docs/content/shared/gateway-config.md

@@ -114,6 +114,36 @@ Type: `[]string`<br />
 
 Certificates used for MDCB Mutual TLS
 
+### security.certificate_expiry_monitor
+CertificateExpiryMonitor configures the certificate expiry monitoring and notification feature
+
+### security.certificate_expiry_monitor.warning_threshold_days
+ENV: <b>TYK_GW_SECURITY_CERTIFICATEEXPIRYMONITOR_WARNINGTHRESHOLDDAYS</b><br />
+Type: `int`<br />
+
+WarningThresholdDays specifies the number of days before certificate expiry that the Gateway will start generating CertificateExpiringSoon events when the certificate is used
+Default: DefaultWarningThresholdDays (30 days)
+
+### security.certificate_expiry_monitor.check_cooldown_seconds
+ENV: <b>TYK_GW_SECURITY_CERTIFICATEEXPIRYMONITOR_CHECKCOOLDOWNSECONDS</b><br />
+Type: `int`<br />
+
+CheckCooldownSeconds specifies the minimum time in seconds that the Gateway will leave between checking for the expiry of a certificate when it is used in an API request - if a certificate is used repeatedly this prevents unnecessary expiry checks
+Default: DefaultCheckCooldownSeconds (3600 seconds = 1 hour)
+
+### security.certificate_expiry_monitor.event_cooldown_seconds
+ENV: <b>TYK_GW_SECURITY_CERTIFICATEEXPIRYMONITOR_EVENTCOOLDOWNSECONDS</b><br />
+Type: `int`<br />
+
+EventCooldownSeconds specifies the minimum time in seconds between firing the same certificate expiry event - this prevents unnecessary events from being generated for an expiring or expired certificate being used repeatedly; note that the higher of the value configured here or the default (DefaultEventCooldownSeconds) will be applied
+Default: DefaultEventCooldownSeconds (86400 seconds = 24 hours)
+
+### external_services
+ENV: <b>TYK_GW_EXTERNALSERVICES</b><br />
+Type: `ExternalServiceConfig`<br />
+
+External service configuration for proxy and mTLS support
+
 ### http_server_options
 Gateway HTTP server configuration
 

tyk-docs/content/shared/x-tyk-gateway.md

@@ -657,6 +657,15 @@ SecuritySchemes contains security schemes definitions.
 **Field: `customKeyLifetime` ([CustomKeyLifetime](#customkeylifetime))**
 CustomKeyLifetime contains configuration for the maximum retention period for access tokens.
 
+**Field: `securityProcessingMode` (`string`)**
+SecurityProcessingMode controls how Tyk will process the OpenAPI `security` field if multiple security requirement objects are declared.
+- "legacy" (default): Only the first security requirement object will be processed; uses BaseIdentityProvider to create the session object.
+- "compliant": All security requirement objects will be processed, request will be authorized if any of these are validated; the origin for the session object will be determined dynamically based on the validated security requirement.
+
+**Field: `security` (`[][]string`)**
+Security is an extension to the OpenAPI security field and is used when securityProcessingMode is set to "compliant".
+This can be used to combine any declared securitySchemes including Tyk proprietary auth methods.
+
 ### **ClientCertificates**
 
 ClientCertificates contains the configurations related to establishing static mutual TLS between the client and Tyk.
@@ -1536,6 +1545,10 @@ Tyk classic API definition:.
 - For OIDC: `scopes.oidc.scope_claim_name`
 - For JWT: `scopes.jwt.scope_claim_name`
 
+**Field: `claims` (`[]string`)**
+Claims specifies a list of claims that can be used to provide the scope-to-policy mapping.
+The first match from the list found in the token will be interrogated to retrieve the scopes that are then checked against the scopeToPolicyMapping.
+
 **Field: `scopeToPolicyMapping` ([[]ScopeToPolicy](#scopetopolicy))**
 ScopeToPolicyMapping contains the mappings of scopes to policy IDs.
 
@@ -2004,6 +2017,34 @@ ClientID is the application's ID.
 **Field: `clientSecret` (`string`)**
 ClientSecret is the application's secret.
 
+### **CustomClaimValidationConfig**
+
+CustomClaimValidationConfig defines the validation configuration for a custom JWT claim.
+
+**Field: `type` ([CustomClaimValidationType](#customclaimvalidationtype))**
+Type specifies the type of validation to perform on the claim.
+Supported types:
+- required: validates that the claim exists and is non-null.
+- exact_match: validates that the claim in the JWT equals one of the allowed values (case-sensitive).
+- contains: validates that the claim in the JWT contains one of the allowed values.
+
+**Field: `allowedValues` (`[]&ast.InterfaceType{Interface:194869, Methods:(*ast.FieldList)(0xc000371170), Incomplete:false}`)**
+AllowedValues contains the values that Tyk will use to validate the claim for "exact_match" and "contains" validation types.
+Not used for "required" validation type.
+Supports string, number, boolean, and array values.
+For arrays, validation succeeds if any array element matches any allowed value.
+
+**Field: `nonBlocking` (`boolean`)**
+NonBlocking determines if validation failure should log a warning (true) or reject the request (false).
+This enables gradual rollout of validation rules by monitoring before enforcing.
+Multiple rules can be mixed, some blocking and others non-blocking.
+
+### **CustomClaimValidationType**
+
+CustomClaimValidationType represents how a JWT claim should be validated.
+This determines the validation logic used to check the claim value.
+The validation behavior varies based on both the type selected and the claim's data type.
+
 ### **EndpointPostPlugin**
 
 EndpointPostPlugin contains endpoint level post plugin configuration.
@@ -2171,6 +2212,24 @@ For introspection caching, it is suggested to use a short interval.
 
 Tyk classic API definition: `external_oauth.providers[].introspection.cache.timeout`.
 
+### **JTIValidation**
+
+JTIValidation contains the configuration for the validation of the JWT ID.
+
+**Field: `enabled` (`boolean`)**
+Enabled indicates whether JWT ID claim is required.
+When true, tokens must include a 'jti' claim.
+
+### **JWK**
+
+JWK represents a JSON Web Key Set containing configuration for the JWKS endpoint and its cache timeout.
+
+**Field: `url` (`string`)**
+URL is the JWKS endpoint.
+
+**Field: `cacheTimeout` (`int64`)**
+CacheTimeout defines how long the JWKS will be kept in the cache before forcing a refresh from the JWKS endpoint.
+
 ### **JWT**
 
 JWT holds the configuration for the JWT middleware.
@@ -2187,7 +2246,7 @@ Source contains the source for the JWT.
 
 Tyk classic API definition: `jwt_source`.
 
-**Field: `jwksURIs` (`[]apidef.JWK`)**
+**Field: `jwksURIs` ([[]JWK](#jwk))**
 JwksURIs contains a list of JSON Web Key Sets (JWKS) endpoints from which Tyk will retrieve JWKS to validate JSON Web Tokens (JWTs).
 
 **Field: `signingMethod` (`string`)**
@@ -2203,6 +2262,9 @@ The identity fields that are checked in order are: `kid`, IdentityBaseField, `su
 
 Tyk classic API definition: `jwt_identity_base_field`.
 
+**Field: `subjectClaims` (`[]string`)**
+SubjectClaims specifies a list of claims that can be used to identity the subject of the JWT.
+
 **Field: `skipKid` (`boolean`)**
 SkipKid controls skipping using the `kid` claim from a JWT (default behaviour).
 When this is true, the field configured in IdentityBaseField is checked first.
@@ -2217,6 +2279,10 @@ The policy is applied to the session as a base policy.
 
 Tyk classic API definition: `jwt_policy_field_name`.
 
+**Field: `basePolicyClaims` (`[]string`)**
+BasePolicyClaims specifies a list of claims from which the base PolicyID is extracted.
+The policy is applied to the session as a base policy.
+
 **Field: `clientBaseField` (`string`)**
 ClientBaseField is used when PolicyFieldName is not provided. It will get
 a session key and use the policies from that. The field ensures that requests
@@ -2252,6 +2318,21 @@ ExpiresAtValidationSkew contains the duration in seconds for which the token can
 
 Tyk classic API definition: `jwt_expires_at_validation_skew`.
 
+**Field: `allowedIssuers` (`[]string`)**
+AllowedIssuers contains a list of accepted issuers for JWT validation.
+When configured, the JWT's issuer claim must match one of these values.
+
+**Field: `allowedAudiences` (`[]string`)**
+AllowedAudiences contains a list of accepted audiences for JWT validation.
+When configured, the JWT's audience claim must match one of these values.
+
+**Field: `jtiValidation` ([JTIValidation](#jtivalidation))**
+JTIValidation contains the configuration for the validation of the JWT ID.
+
+**Field: `allowedSubjects` (`[]string`)**
+AllowedSubjects contains a list of accepted subjects for JWT validation.
+When configured, the subject from kid/identityBaseField/sub must match one of these values.
+
 **Field: `idpClientIdMappingDisabled` (`boolean`)**
 IDPClientIDMappingDisabled prevents Tyk from automatically detecting the use of certain IDPs based on standard claims
 that they include in the JWT: `client_id`, `cid`, `clientId`. Setting this flag to `true` disables the mapping and avoids
@@ -2260,6 +2341,23 @@ accidentally misidentifying the use of one of these IDPs if one of their standar
 
 Tyk classic API definition: `idp_client_id_mapping_disabled`.
 
+**Field: `customClaimValidation` (`map[string]CustomClaimValidationConfig`)**
+CustomClaimValidation contains custom validation rules for JWT claims.
+It maps a claim name (including nested claims using dot notation) to its validation configuration.
+
+The validation can be one of three types:
+- "required": claim must exist in the token (null/empty values are considered invalid)
+- "exact_match": claim must exactly equal one of the specified values (case-sensitive)
+- "contains": for strings, must contain one of the values as substring; for arrays, must contain one of the values as element
+
+Examples:
+Basic validation: {"role": {"type": "exact_match", "allowedValues": ["admin", "user"]}}
+Nested claim: {"user.metadata.level": {"type": "contains", "allowedValues": ["gold", "silver"]}}
+Multiple rules: {"permissions": {"type": "contains", "allowedValues": ["read", "write"], "nonBlocking": true}}
+
+Claims can be of type string, number, boolean, or array. For arrays, the contains validation
+checks if any of the array elements exactly match any of the allowed values.
+
 ### **JWTValidation**
 
 JWTValidation holds configuration for validating access tokens by inspecing them
@@ -2827,3 +2925,4 @@ XTykStreaming represents the structure for Tyk streaming configurations.
 
 **Field: `streams` (`any`)**
 Streams contains the configurations related to Tyk Streams.
+