Availability
Introduction
A JSON Web Token consists of three parts separated by dots:header.payload.signature. The signature verifies that the sender of the JWT is who it claims to be and that the message wasn’t altered along the way.
Tyk can validate the signature of incoming JWTs to ensure that they meet your security requirements before granting access to your APIs.
JWT Signature Fundamentals
The JWT signature serves three main purposes:- Integrity: If anyone modifies the header or payload, the signature will no longer match.
- Authenticity: Confirms that the token was issued by a trusted source.
- Security: Prevents malicious users from forging tokens or altering claims.
How JWT Signatures Are Created
The JWT signature is created by taking the encoded header, the encoded payload, a secret, and the algorithm specified in the header. Example:Verification Process
When Tyk receives a JWT, it performs the following steps to validate the signature:- It extracts the header and payload.
- Recomputes the signature using its own secret/public key.
- Compares it with the token’s signature.
- If they match, the token is valid.
- If not, the token is rejected.
Supported Algorithms for Signature Validation
Configuration Options
Tyk supports two approaches to supplying the key or secret used to validate incoming JWTs:- Identity Provider (IdP): Tyk fetches public keys from a JWKS endpoint exposed by the IdP. The IdP can be configured centrally in the Identity Provider Registry, or directly in the API definition.
- Local Keys: The key or secret is supplied directly in the API definition, either as a hard-coded value or as a reference to an external secret store.
Identity Providers
An Identity Provider (IdP) issues JWTs and exposes a JWKS endpoint where Tyk fetches the public keys needed to validate token signatures. The IdP can be configured centrally in the Identity Provider Registry, or directly in the API definition.Feature Compatibility Summary
Identity Provider Registry
The Identity Provider Registry is a centralized store for IdP configuration (JWKS endpoints, scope claim names, and scope-to-policy mappings) managed independently of API definitions in the Tyk Dashboard. Available from Tyk 5.14.0 (Enterprise), it is the recommended approach when using Dynamic Client Registration or when multiple systems need to manage IdP configuration for the same API. Adopting the registry is a non-breaking change: existing API definitions are unaffected.Configuring IdPs in the API Definition
If you are not using the Identity Provider Registry, JWKS endpoints can be configured directly in the API definition. Multiple JWKS Endpoints From Tyk 5.9.0 onwards, Tyk OAS APIs can validate against multiple JWKS endpoints, allowing different IdPs to issue JWTs for the same API. Multiple JWKS endpoints can be configured in the<jwtAuthScheme>.jwksURIs array. Tyk retrieves the JSON Web Key Sets from each endpoint and uses them to attempt to validate the received JWT.
For example, the following fragment configures the JWT authentication middleware to retrieve the JWKS from both Auth0 and Keycloak when validating the signature of incoming JWTs:
Multiple JWKS endpoints and the
jwksURIs array are not supported by Tyk Classic APIs.server.authentication.securitySchemes.<jwtAuthScheme>.source (in Tyk Classic, this is jwt_source). This field accepts the base64-encoded full URI (including the protocol) of the JWKS endpoint.
For example, the following Tyk OAS fragment configures the JWT authentication middleware to retrieve the JWKS from https://your-tenant.auth0.com/.well-known/jwks.json:
The
<jwtAuthScheme>.source URIs must be base64 encoded in the API definition.If both <jwtAuthScheme>.source and <jwtAuthScheme>.jwksURIs are configured, the latter will take precedence.Local Keys
The key or secret used to validate JWTs can be supplied directly in the API definition viaserver.authentication.securitySchemes.<jwtAuthScheme>.source (in Tyk Classic, this is jwt_source). The value must be base64 encoded.
This approach supports both symmetric (HMAC shared secret) and asymmetric (RSA/ECDSA public key) algorithms.
Rather than hard-coding the value, the recommended approach is to store the key or secret in an external secret store such as Consul or Vault, and place a KV reference in source instead. The reference is base64 encoded in the same way as a hard-coded value.
For example, the following fragment hard-codes the secret mysecret:
JWKS Caching
Tyk caches public keys fetched from Identity Providers to reduce the performance impact of contacting external services during request handling.Feature Compatibility Summary
Configuration Options
Gateway-Level Configuration
Unless otherwise configured, all cached keys expire after 240 seconds, after which the cache is refreshed when a new request is received. From Tyk 5.12.0, this default timeout is configurable in the Gateway config file (tyk.conf) or the equivalent environment variable:
timeout is given in seconds. This setting applies to all IdPs, including those configured via the Identity Provider Registry.
API-Level Configuration
From Tyk 5.10, Tyk OAS APIs support a per-IdP cache timeout on each IdP configured viajwksURIs. If set, this overrides the gateway-level timeout for that IdP.
For example, the following fragment assigns a 300 second cache timeout to Auth0 and 180 seconds to Keycloak:
For more details, refer to the Tyk OAS API definition reference.
Tyk Classic APIs do not support per-IdP cache timeouts and use the gateway-level timeout (from Tyk 5.12.0) or the default of 240 seconds.
Cache Management
Tyk Gateway and Tyk Dashboard APIs expose endpoints to manage JWKS caches programmatically for both Tyk OAS and Tyk Classic APIs:The Dashboard API endpoint is restricted to users with
admin privileges and can only be used to flush the cache for APIs in the user’s Organisation.FAQ
Can I use different signing methods for different APIs?
Can I use different signing methods for different APIs?
Yes, each API definition can have its own JWT configuration with different signing methods and keys.
How do I handle JWTs signed with different keys (e.g., from different issuers)?
How do I handle JWTs signed with different keys (e.g., from different issuers)?
The recommended approach is to use the Identity Provider Registry (Enterprise, from Tyk 5.14.0), which natively supports multiple IdPs per API. If you are not using the registry, Tyk OAS APIs from Tyk 5.9.0 support multiple JWKS endpoints via the
jwksURIs array.Can I use JWKS endpoints with symmetric cryptography (HMAC)?
Can I use JWKS endpoints with symmetric cryptography (HMAC)?
No, JWKS endpoints are designed for asymmetric cryptography (RSA and ECDSA), where public keys are used for signature verification. Symmetric cryptography (HMAC) requires a shared secret, which cannot be retrieved from a JWKS endpoint.
How often does Tyk refresh the JWKS cache?
How often does Tyk refresh the JWKS cache?
By default, cached keys expire after 240 seconds. This can be changed gateway-wide using the
jwks.cache.timeout setting in the Gateway config. For Tyk OAS APIs with IdPs configured directly in the API definition via jwksURIs, a per-IdP cacheTimeout can override the gateway-level setting. IdPs configured via the Identity Provider Registry always use the gateway-level timeout and cannot currently be tuned per IdP.Is JWKS Pre-fetching configurable?
Is JWKS Pre-fetching configurable?
The JWKS (JSON Web Key Set) pre-fetching functionality in Tyk Gateway is automatic and not configurable in terms of enabling/disabling it. When you configure JWKS URLs in your API definition, Tyk automatically pre-fetches the keys when the API loads.