From 79fc85832929f52e2401afe816d2e6c960f011a4 Mon Sep 17 00:00:00 2001 From: Sharad Regoti Date: Mon, 3 Nov 2025 13:57:25 +0530 Subject: [PATCH 1/6] Fixes --- ai-management/ai-studio/ai-studio-swagger.mdx | 3 +- dashboard-admin-api.mdx | 15 ++++++++- docs.json | 18 +++++++++++ .../api-documentation/tyk-edp-api.mdx | 20 ++++++++++-- tyk-dashboard-api.mdx | 32 ++++++++++++++++++- tyk-gateway-api.mdx | 26 ++++++++++++++- tyk-mdcb-api.mdx | 6 +++- 7 files changed, 113 insertions(+), 7 deletions(-) diff --git a/ai-management/ai-studio/ai-studio-swagger.mdx b/ai-management/ai-studio/ai-studio-swagger.mdx index 00bd6ff44..4a34fc1f5 100644 --- a/ai-management/ai-studio/ai-studio-swagger.mdx +++ b/ai-management/ai-studio/ai-studio-swagger.mdx @@ -2,6 +2,7 @@ title: "Tyk AI Studio API" description: "Tyk AI Studio API" keywords: "OpenAPI Spec for AI Studio, Tyk AI Studio OAS, Tyk AI Portal REST" -sidebarTitle: "API Documentation" +sidebarTitle: "Overview" --- +This is the API for the AI Studio user and group management system. \ No newline at end of file diff --git a/dashboard-admin-api.mdx b/dashboard-admin-api.mdx index 083524ff2..98d611ec6 100644 --- a/dashboard-admin-api.mdx +++ b/dashboard-admin-api.mdx @@ -1,6 +1,19 @@ --- title: "Tyk Dashboard Admin API" +description: "Tyk Dashboard Admin API documentation. This page provides details on how to use the Tyk Dashboard Admin API for setting up and provisioning a Tyk Dashboard instance." order: 4 -sidebarTitle: "Dashboard Admin" +sidebarTitle: "Overview" --- + + +For Tyk On-Premises installations only, the Dashboard Admin API has two endpoints and is used to set up and provision a Tyk Dashboard instance without the command line. + +In order to use the Dashboard Admin API, you'll need to get the `admin_secret` value from your Tyk Dashboard configurations. + +The secret you set should then be sent along as a header with each Dashboard Admin API Request in order for it to be successful: + +``` +admin-auth: +``` + diff --git a/docs.json b/docs.json index 8a14dc997..16c129b2d 100644 --- a/docs.json +++ b/docs.json @@ -393,18 +393,30 @@ "tyk-apis", { "group": "Gateway", + "pages": [ + "tyk-gateway-api" + ], "openapi": "swagger/gateway-swagger.yml" }, { "group": "Dashboard", + "pages": [ + "tyk-dashboard-api" + ], "openapi": "swagger/dashboard-swagger.yml" }, { "group": "Dashboard Admin", + "pages": [ + "dashboard-admin-api" + ], "openapi": "swagger/dashboard-admin-swagger.yml" }, { "group": "MDCB", + "pages": [ + "tyk-mdcb-api" + ], "openapi": "swagger/mdcb-swagger.yml" }, "tyk-identity-broker/tib-rest-api" @@ -539,6 +551,9 @@ "product-stack/tyk-enterprise-developer-portal/deploy/configuration", { "group": "Developer Portal API", + "pages": [ + "product-stack/tyk-enterprise-developer-portal/api-documentation/tyk-edp-api" + ], "openapi": "swagger/enterprise-developer-portal-swagger.yaml" }, "product-stack/tyk-enterprise-developer-portal/api-documentation/list-of-endpoints/portal-api-list-of-endpoints", @@ -690,6 +705,9 @@ "ai-management/ai-studio/notifications", { "group": "API Documentation", + "pages": [ + "ai-management/ai-studio/ai-studio-swagger" + ], "openapi": "swagger/ai-studio-swagger.yml" } ] diff --git a/product-stack/tyk-enterprise-developer-portal/api-documentation/tyk-edp-api.mdx b/product-stack/tyk-enterprise-developer-portal/api-documentation/tyk-edp-api.mdx index 1cead1979..1e307ebd9 100644 --- a/product-stack/tyk-enterprise-developer-portal/api-documentation/tyk-edp-api.mdx +++ b/product-stack/tyk-enterprise-developer-portal/api-documentation/tyk-edp-api.mdx @@ -1,6 +1,22 @@ --- -title: "Tyk Enterprise Developer Portal API" +title: "Tyk Developer Portal API" +description: "Tyk Developer Portal API documentation. This page provides details on how to use the Tyk Developer Portal Management API for managing portal resources." order: 3 -sidebarTitle: "Developer Portal API" +sidebarTitle: "Overview" --- + + +## Introduction + +The Tyk Developer Portal Management API offers programmatic +access to all portal resources that your instance of the portal manages. +This API repeats functionality of the user interface and enables APIs +consumers integrating their portal instances with their other IT systems +such as billings, CRMs, ITSM systems and other software. + + +## Authentication + +This API requires an admin authorisation token that is available for admin +users of the portal in the profile page. diff --git a/tyk-dashboard-api.mdx b/tyk-dashboard-api.mdx index 52e3ef24e..92543bdbc 100644 --- a/tyk-dashboard-api.mdx +++ b/tyk-dashboard-api.mdx @@ -1,6 +1,36 @@ --- title: "Tyk Dashboard API" +description: "Tyk Dashboard API documentation. This page provides details on how to use the Tyk Dashboard API for managing organisations, users, API definitions, and more." order: 3 -sidebarTitle: "Dashboard" +sidebarTitle: "Overview" --- + + +## Introduction + +The Tyk Dashboard API offers granular, programmatic access to a centralised database of resources that your Tyk nodes can pull from. This API has a dynamic user administrative structure which means the secret key that is used to communicate with your Tyk nodes can be kept secret and access to the wider management functions can be handled on a user-by-user and organisation-by-organisation basis. + +A common question around using a database-backed configuration is how to programmatically add API definitions to your Tyk nodes, the Dashboard API allows much more fine-grained, secure and multi-user access to your Tyk cluster, and should be used to manage a database-backed Tyk node. + +The Tyk Dashboard API works seamlessly with the Tyk Dashboard (and the two come bundled together). + +## Security Hierarchy + +The Dashboard API provides a more structured security layer to managing Tyk nodes. + +### Organisations, APIs and Users + +With the Dashboard API and a database-backed Tyk setup, (and to an extent with file-based API setups - if diligence is used in naming and creating definitions), the following security model is applied to the management of Upstream APIs: + +* **Organisations**: All APIs are *owned* by an organisation, this is designated by the 'OrgID' parameter in the API Definition. +* **Users**: All users created in the Dashboard belong to an organisation (unless an exception is made for super-administrative access). +* **APIs**: All APIs belong to an Organisation and only Users that belong to that organisation can see the analytics for those APIs and manage their configurations. +* **API Keys**: API Keys are designated by organisation, this means an API key that has full access rights will not be allowed to access the APIs of another organisation on the same system, but can have full access to all APIs within the organisation. +* **Access Rights**: Access rights are stored with the key, this enables a key to give access to multiple APIs, this is defined by the session object in the core Tyk API. + +In order to use the Dashboard API, you'll need to get the 'Tyk Dashboard API Access Credentials' secret from your user profile on the Dashboard UI. + +The secret you set should then be sent along as a header with each Dashboard API Request in order for it to be successful: + +`authorization: ` diff --git a/tyk-gateway-api.mdx b/tyk-gateway-api.mdx index 21116dc3a..34671c323 100644 --- a/tyk-gateway-api.mdx +++ b/tyk-gateway-api.mdx @@ -1,7 +1,31 @@ --- title: "Tyk Gateway API" +description: "Tyk Gateway API documentation. This page provides details on how to use the Tyk Gateway API for managing session objects, policies, API definitions, and more." keywords: "OpenAPI Spec, OpenAPI Specification, OAS, REST, Tyk Gateway OpenAPI Spec, Tyk Gateway OAS, API Gateway OAS, API Gateway REST" order: 3 -sidebarTitle: "Gateway" +sidebarTitle: "Overview" --- + + + +The Tyk Gateway API is the primary means for integrating your application with the Tyk API Gateway system. This API is very small, and has no granular permissions system. It is intended to be used purely for internal automation and integration. + +**Warning: Under no circumstances should outside parties be granted access to this API.** + +The Tyk Gateway API is capable of: + +* Managing session objects (key generation). +* Managing and listing policies. +* Managing and listing API Definitions (only when not using the Tyk Dashboard). +* Hot reloads / reloading a cluster configuration. +* OAuth client creation (only when not using the Tyk Dashboard). + +In order to use the Gateway API, you'll need to set the **secret** parameter in your tyk.conf file. + +The shared secret you set should then be sent along as a header with each Gateway API Request in order for it to be successful: + +`x-tyk-authorization: ` +
+ +The Tyk Gateway API is subsumed by the Tyk Dashboard API in Pro installations. diff --git a/tyk-mdcb-api.mdx b/tyk-mdcb-api.mdx index cc2723a85..ad5d0b809 100644 --- a/tyk-mdcb-api.mdx +++ b/tyk-mdcb-api.mdx @@ -1,7 +1,11 @@ --- title: "Tyk MDCB API" +description: "Tyk MDCB API documentation. This page provides details on how to use the Tyk Multi Data Center Bridge (MDCB) API for monitoring connected Data Planes and accessing diagnostic data." keywords: "OpenAPI Spec, OpenAPI Specification, OAS, REST, Tyk MDCB OpenAPI Spec, Tyk MDCB OAS, MDCB API REST" order: 3 -sidebarTitle: "Multi Data Center Bridge" +sidebarTitle: "Overview" --- +This API provides operations for monitoring Data Planes connected to MDCB and accessing diagnostic data. +It includes endpoints for retrieving connected data plane details, performing health checks, +and accessing Go's built-in pprof diagnostics for advanced performance profiling. \ No newline at end of file From 0d0d6af4e23da2fb0d91771323b32d743ab95a2a Mon Sep 17 00:00:00 2001 From: Sharad Regoti Date: Thu, 20 Nov 2025 13:40:24 +0530 Subject: [PATCH 2/6] Fixes --- .gitignore | 12 + .../authentication/jwt-authorization.mdx | 2 +- .../authentication/jwt-claim-validation.mdx | 28 +- .../jwt-signature-validation.mdx | 308 +++++++++++++++++ .../authentication/jwt-split-token.mdx | 210 ++++++++++++ .../json-web-tokens.mdx | 309 ------------------ docs.json | 4 +- 7 files changed, 560 insertions(+), 313 deletions(-) create mode 100644 api-management/authentication/jwt-signature-validation.mdx create mode 100644 api-management/authentication/jwt-split-token.mdx diff --git a/.gitignore b/.gitignore index bcd218f54..14cce41af 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,15 @@ +.DS_Store +backup_unused/ +backup_unused_main/ +cleanup-unused-images.sh +index.js +mintlify-fix-redirect/ +not-found.txt +transform.sh +unused_images_log.txt +urls.txt +flatten_alpha_log* + ### Node template # Logs logs diff --git a/api-management/authentication/jwt-authorization.mdx b/api-management/authentication/jwt-authorization.mdx index 204ebbd09..a787e820a 100644 --- a/api-management/authentication/jwt-authorization.mdx +++ b/api-management/authentication/jwt-authorization.mdx @@ -1,6 +1,6 @@ --- title: "JWT Authorization" -description: "How JWT authorization works in Tyk API Gateway." +description: "Tyk Gateway's JWT Authorization process extracts user identity and applies security policies based on JWT claims for API access control." keywords: "Authentication, Authorization, JWT, JSON Web Tokens, Claims, Validation" sidebarTitle: "Authorization" --- diff --git a/api-management/authentication/jwt-claim-validation.mdx b/api-management/authentication/jwt-claim-validation.mdx index 01b72cd22..478aa99d1 100644 --- a/api-management/authentication/jwt-claim-validation.mdx +++ b/api-management/authentication/jwt-claim-validation.mdx @@ -1,6 +1,6 @@ --- title: "JWT Claim Validation" -description: "How to validate JWT claims in Tyk API Gateway." +description: "Tyk Gateway's JWT Claim Validation enables fine-grained access control by validating registered and custom claims in JSON Web Tokens." keywords: "Authentication, JWT, JSON Web Tokens, Claims, Validation" sidebarTitle: "Claim Validation" --- @@ -796,4 +796,28 @@ x-tyk-api-gateway: nonBlocking: true ``` -The `nonBlocking` flag in the validation rule for `user.preferences.notifications` means that if this claim is missing from the received token, the token will not fail validation, but a warning will be logged. \ No newline at end of file +The `nonBlocking` flag in the validation rule for `user.preferences.notifications` means that if this claim is missing from the received token, the token will not fail validation, but a warning will be logged. + +## FAQ + +
    + +
  • +
    +Can I restrict which issuers' tokens are accepted? + +Yes, you can configure `AllowedIssuers` to specify which iss (issuer) claim values are accepted. Tokens from other issuers will be rejected. + +
    +
    • + +
  • +
    +How can I validate custom claims in the JWT? + +Use the `CustomClaimValidation` configuration to validate specific claims with different validation types (Required, ExactMatch, or Contains). + +
    +
    • + +
\ No newline at end of file diff --git a/api-management/authentication/jwt-signature-validation.mdx b/api-management/authentication/jwt-signature-validation.mdx new file mode 100644 index 000000000..0cbe0b3d5 --- /dev/null +++ b/api-management/authentication/jwt-signature-validation.mdx @@ -0,0 +1,308 @@ +--- +title: JWT Signature Validation +description: How to validate JWT signatures in Tyk API Gateway. +keywords: ["Authentication", "JWT", "JSON Web Tokens", "Signature", "Validation"] +sidebarTitle: "Signature Validation" +--- + +## Availability + +| Component | Editions | +| ----------- | ------------------------ | +| Tyk Gateway | Community and Enterprise | + +## 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: + +1. **Integrity:** + If anyone modifies the header or payload, the signature will no longer match. + +2. **Authenticity:** + Confirms that the token was issued by a trusted source. + +3. **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**: + +``` +HMACSHA256( + base64UrlEncode(header) + "." + base64UrlEncode(payload), + secret +) +``` + +Or, for asymmetric algorithms like RSA or ECDSA: + +``` +RSASHA256( + base64UrlEncode(header) + "." + base64UrlEncode(payload), + private_key +) +``` + +### Verification Process + +When Tyk receives a JWT, it performs the following steps to validate the signature: + +1. It extracts the header and payload. +2. Recomputes the signature using its own secret/private key. +3. 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 + +| Method | Cryptographic Style | Secret Type | Supported Locations for Secret | Supported Algorithms | +| --------- | ------------------- | ------------- | ------------------------------ | ---------------------------------------------------- | +| **HMAC** | Symmetric | Shared secret | API definition | `HS256`, `HS384`, `HS512` | +| **RSA** | Asymmetric | Public key | API definition, JWKS endpoint | `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512` | +| **ECDSA** | Asymmetric | Public key | API definition, JWKS endpoint | `ES256`, `ES384`, `ES512` | + +## Configuration Options + +You can configure JWT signature validation using the Dashboard UI or the Tyk API definition. To configure it, you must provide Tyk with the secret or key to validate incoming JWTs. + +Tyk supports three methods for referencing keys and secrets: + +1. **Locally Stored Keys**: The key or secret is stored directly in the API definition. +2. **External Key Value Store**: The key or secret is stored in an external key value store (e.g., Consul, Vault) and referenced in the API definition. +3. **Remotely Stored Keys**: Tyk retrieves the key from a public JSON Web Key Set (JWKS) endpoint. + +Depending on the cryptographic style used, the options vary: + +| Cryptographic Style | Locally Stored Keys | External Key Value Store | Remotely Stored Keys (JWKS) | +| ------------------- | ------------------- | ------------------------ | --------------------------- | +| **Symmetric** | Yes | Yes | No | +| **Asymmetric** | Yes | Yes | Yes | + + +### 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..source` (in Tyk Classic, this is [jwt_source](/api-management/gateway-config-tyk-classic#configuring-authentication-for-tyk-classic-apis). + +For example, the Tyk OAS fragment below configures the secret `mysecret` to validate the signatures of incoming JWTs. **Note** that the secret has been base64 encoded and then stored in `source`: + +```yaml +x-tyk-api-gateway: + server: + authentication: + securitySchemes: + jwtAuth: + source: bXlzZWNyZXQ= +``` + +Refer to the [Tyk OAS API Definition](/api-management/gateway-config-tyk-oas#jwt) reference for details. + +### External Key Value Store + +For improved separation of concerns and flexibility, the key/secret can be placed in an [external key value store](/tyk-configuration-reference/kv-store), with the appropriate reference configured in the API definition. + +For example, this fragment configures the JWT authentication middleware to use the secret at `consul://secrets/jwt-secret` to validate the signatures 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) + +Tyk can retrieve public keys from JSON Web Key Sets (JWKS) endpoints to validate the signature of incoming JWTs. Tyk supports configuring [single](/api-management/authentication#single-jwks-endpoint) or [multiple](/api-management/authentication#multiple-jwks-endpoints) JWKS endpoints with [caching](/api-management/authentication#jwks-caching) capabilities. + +#### Feature Compatibility Summary + +| Feature | Tyk Classic APIs | Tyk OAS APIs | Available From | +| ------------------------------ | ---------------- | ------------ | -------------- | +| Single JWKS Endpoint Support | ✅ | ✅ | All versions | +| Multiple JWKS Endpoint Support | ❌ | ✅ | 5.9.0 | + +#### Single JWKS endpoint + +Before 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..source` (in Tyk Classic, this is [jwt_source](/api-management/gateway-config-tyk-classic#configuring-authentication-for-tyk-classic-apis)). 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` when validating the signatures of incoming JWTs. Note that the JWKS endpoint has been base64 encoded and then stored in `source`: + +```yaml +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 `.jwksURIs` array. Tyk will retrieve the JSON Web Key Sets from each of these endpoints, which will be used to attempt to validate the received JWT. + + +**Note** + +- The `.jwksURIs` URIs are not base64 encoded in the API definition and so are human-readable. +- If both `.source` and `.jwksURIs` are configured, the latter will take precedence. +- Multiple JWKS endpoints and the `jwksURIs` array are not supported by Tyk Classic APIs. + + +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: + +```yaml +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 +``` + +## JWKS caching + +Tyk caches the [JSON Web Key Set](https://datatracker.ietf.org/doc/html/rfc7517) (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 and API, with a default validity period of *240 seconds*, after which the cache is refreshed when a new request is received. + +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) +``` + +### Feature Compatibility Summary + +From **Tyk 5.10.0** onwards, we have introduced enhanced JWKS caching for [Tyk OAS APIs](/api-management/gateway-config-tyk-oas) 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 + +The table below summarizes the availability of JWKS caching features between Tyk Classic and Tyk OAS APIs: + + +| 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+ | + +### 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. | + +For more details, refer to the [Tyk OAS API definition reference](/api-management/gateway-config-tyk-oas#jwk). + + +**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. + + +### JWKS Cache Management + +New [Gateway API](/tyk-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](/tyk-gateway-api) and are not yet extended to the Tyk [Dashboard API](/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" +``` + +## FAQ + +
    +
  • +
    +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)? + +You can use JWKS (JSON Web Key Sets) by configuring `JWTJwksURIs` with the URLs of your JWKS endpoints. Tyk will automatically fetch and use the appropriate key based on the kid (Key ID) in the token header. + +
    +
    • + +
  • +
    +What happens if the JWKS endpoint is temporarily unavailable? + +Tyk caches JWKS responses. You can configure the cache timeout using the CacheTimeout parameter in the `JWTJwksURIs` configuration. This ensures that temporary JWKS endpoint outages don't affect API availability. + +
    +
    • + +
  • +
    +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? + +By default, Tyk refreshes the JWKS cache every 240 seconds. However, you can customize the cache timeout for each JWKS endpoint in Tyk OAS APIs using the `cacheTimeout` field in the API definition. + +
    +
    • + +
  • +
    +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 will automatically pre-fetch the keys when the API loads. + +
    +
    • + +
\ No newline at end of file diff --git a/api-management/authentication/jwt-split-token.mdx b/api-management/authentication/jwt-split-token.mdx new file mode 100644 index 000000000..020819631 --- /dev/null +++ b/api-management/authentication/jwt-split-token.mdx @@ -0,0 +1,210 @@ +--- +title: JWT Split Token +description: Learn how to implement JWT Split Token flow in Tyk to enhance security by separating JWT components and storing sensitive data server-side. +keywords: ["Authentication", "JWT", "JSON Web Tokens", "Split Token", "Security"] +sidebarTitle: "Split Token" +--- + +## Availability + +| Component | Editions | +| :------------- | :------------------------- | +| Tyk Gateway | Community and Enterprise | + +## Introduction + +Split Token Flow addresses a fundamental security concern with JWT tokens: when a JWT is stored on a client device (browser, mobile app, etc.), all of its contents can be easily decoded since JWTs are only base64-encoded, not encrypted. This means sensitive information in the payload is potentially exposed. + +The JWT consists of three parts: + +Split Token Example + +In the above example you can see that they are: + +- Header: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9` +- Payload: `eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJlbWFpbCI6ImhlbGxvQHdvcmxkLmNvbSJ9` +- Signature: `EwIaRgq4go4R2M2z7AADywZ2ToxG4gDMoG4SQ1X3GJ0` + +The Split Token approach provides a solution by: + +1. Separating the JWT into its three component parts: header, payload, and signature +2. Storing only the signature on the client side (which by itself is meaningless) +3. Keeping the header and payload securely on the server side (in Tyk) +4. Reconstructing the complete JWT when needed for authentication + +This approach combines the benefits of JWTs (rich claims, stateless validation) with the security of opaque tokens (no information disclosure). + +### When to Use Split Token Flow + +Consider using Split Token Flow when: + +- Your JWT payload contains sensitive information that shouldn't be exposed to clients +- You want to prevent token inspection by malicious actors +- You need the flexibility of JWT while maintaining higher security +- You're implementing systems that must meet strict security compliance requirements + +## How Split Token Flow Works + +Here's how the process works with Tyk Gateway: + +```mermaid +sequenceDiagram + participant Client + participant Tyk as Tyk Gateway + participant Redis as Tyk Redis + participant Auth as Authorization Server + + %% Token Issuance Flow + rect rgb(240, 240, 255) + note over Client, Auth: Token Issuance + Client->>Tyk: Request token from /token endpoint + Tyk->>Auth: Forward request to Auth Server + Auth->>Tyk: Return complete JWT (header.payload.signature) + Tyk->>Tyk: Split JWT into components + Tyk->>Redis: Store header & payload using signature as key + Tyk->>Client: Return only signature as "opaque" token + end + + %% Token Usage Flow + rect rgb(245, 255, 245) + note over Client, Auth: Token Usage + Client->>Tyk: API request with signature as Bearer token + Tyk->>Redis: Look up header & payload using signature + Redis->>Tyk: Return stored header & payload + Tyk->>Tyk: Reconstruct complete JWT + Tyk->>Tyk: Validate JWT + Tyk->>Auth: Forward request with complete JWT + Auth->>Tyk: Response + Tyk->>Client: Return response to client + end +``` + +1. **Token Issuance**: + + - A `/token` endpoint is configured on Tyk from which the client should request the access token + - Tyk requests an access token from an authorization server (e.g., Keycloak) on behalf of the client + - The authorization server returns a complete JWT + - Tyk intercepts this response through a [Virtual Endpoint](/api-management/traffic-transformation/virtual-endpoints) + - Tyk splits the JWT into its components and stores the header and payload in its Redis database + - Only the signature portion is returned to the client as an "opaque" token + +2. **Token Usage**: + + - The client makes API requests using only the signature as their access token + - Tyk receives the request and looks up the stored header and payload using the signature + - Tyk reconstructs the complete JWT and validates it + - If valid, Tyk forwards the request to the upstream API with the full JWT + +3. **Security Benefits**: + + - The client never possesses the complete JWT, only a meaningless signature + - Token contents cannot be inspected by client-side code or malicious actors + - Token validation still occurs using standard JWT verification + + +## Implementing Split Token Flow + +1. **Create a Virtual Endpoint for Token Issuance** + + First, create a virtual endpoint in Tyk that will: + + - Receive authentication requests from clients + - Forward these requests to your authorization server + - Split the returned JWT + - Store the header and payload in Tyk's storage + - Return only the signature to the client + - Here's a simplified implementation: + + ```javascript + function splitTokenHandler(request, session, config) { + // 1. Forward the client's credentials to the authorization server + var authServerResponse = forwardToAuthServer(request); + + if (authServerResponse.Code !== 200) { + return TykJsResponse({ + Body: authServerResponse.Body, + Code: authServerResponse.Code + }, session.meta_data); + } + + // 2. Extract the JWT from the response + var responseBody = JSON.parse(authServerResponse.Body); + var fullJWT = responseBody.access_token; + + // 3. Split the JWT into its components + var jwtParts = fullJWT.split("."); + var header = jwtParts[0]; + var payload = jwtParts[1]; + var signature = jwtParts[2]; + + // 4. Store the complete JWT in Tyk's Redis database using the signature as the key + // This function would use Tyk's storage API to save the data + storeJWTComponents(signature, header, payload, fullJWT); + + // 5. Modify the response to return only the signature + responseBody.access_token = signature; + + return TykJsResponse({ + Body: JSON.stringify(responseBody), + Code: 200 + }, session.meta_data); + } + ``` + + Note that this example includes some level of abstraction for clarity and so is not a full implementation. + +2. **Configure Custom Pre-Auth Plugin** + + Next, create a custom pre-auth plugin that reconstructs the JWT before it reaches the standard Tyk JWT Auth middleware: + + ```javascript + function reconstructJWT(request, session, config) { + // 1. Extract the signature from the Authorization header + var authHeader = request.Headers["Authorization"]; + var signature = authHeader.replace("Bearer ", ""); + + // 2. Retrieve the stored JWT components using the signature + var storedJWT = retrieveJWTComponents(signature); + + if (!storedJWT) { + return TykJsResponse({ + Body: "Invalid token", + Code: 401 + }, session.meta_data); + } + + // 3. Replace the Authorization header with the full JWT + request.SetHeaders["Authorization"] = "Bearer " + storedJWT.fullJWT; + + return request; + } + ``` + +3. **Test the Implementation** + + To test your Split Token Flow: + + Request a token from your Tyk virtual endpoint: + + ```bash + curl -X POST https://your-tyk-gateway/token \ + -d "grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret" + ``` + + You'll receive a response with only the signature as the access token, for example: + + ```json + { + "access_token": "EwIaRgq4go4R2M2z7AADywZ2ToxG4gDMoG4SQ1X3GJ0", + "token_type": "bearer", + "expires_in": 3600 + } + ``` + + Use this token to access your JWT Auth protected API where you have configured the custom pre-auth plugin and JWT Auth: + + ```bash + curl https://your-tyk-gateway/protected-api \ + -H "Authorization: Bearer EwIaRgq4go4R2M2z7AADywZ2ToxG4gDMoG4SQ1X3GJ0" + ``` + diff --git a/basic-config-and-security/security/authentication-authorization/json-web-tokens.mdx b/basic-config-and-security/security/authentication-authorization/json-web-tokens.mdx index 9d081e8ea..8d27255a8 100644 --- a/basic-config-and-security/security/authentication-authorization/json-web-tokens.mdx +++ b/basic-config-and-security/security/authentication-authorization/json-web-tokens.mdx @@ -249,312 +249,3 @@ x-tyk-api-gateway: ### Using Tyk Classic APIs As noted in the Tyk Classic API [documentation](/api-management/gateway-config-tyk-classic#configuring-authentication-for-tyk-classic-apis), you can select JSON Web Token authentication using the `use_jwt` option. Tyk Classic APIs do not natively support multiple JWKS endpoints, though a [custom authentication plugin](/api-management/plugins/plugin-types#authentication-plugins) could be used to implement this functionality. - -## Signature Validation - -| Method | Cryptographic Style | Secret Type | Supported Locations for Secret | Supported Algorithms | -| :--------- | :------------------- | :------------- | :------------------------------ | :---------------------------------------------------- | -| **HMAC** | Symmetric | Shared secret | API definition | `HS256`, `HS384`, `HS512` | -| **RSA** | Asymmetric | Public key | API definition, JWKS endpoint | `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512` | -| **ECDSA** | Asymmetric | Public key | API definition, JWKS endpoint | `ES256`, `ES384`, `ES512` | - -### Secret Management - -You must provide Tyk with the secret or key to be used to validate the incoming JWTs. - -- For the asymmetric methods (RSA and ECDSA) the public key can be stored in the API definition or Tyk can retrieve from a public JSON Web Key Sets (JWKS) endpoint (supporting dynamic rotation of keys in the JWKS) -- For symmetric encryption (HMAC), the secret is shared between the client and Tyk and so is stored within the API definition not on the public JWKS server - -#### 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..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](/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..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: - 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 `.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: - -```yaml -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.*

- - - -If both `.source` and `.jwksURIs` are configured, the latter will take precedence. - - - -#### 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. | - - - - -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. - - - -##### 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+ | - -## Split Token Flow - -Split Token Flow addresses a fundamental security concern with JWT tokens: when a JWT is stored on a client device (browser, mobile app, etc.), all of its contents can be easily decoded since JWTs are only base64-encoded, not encrypted. This means sensitive information in the payload is potentially exposed. - -The JWT consists of three parts: - -Split Token Example - -In the above example you can see that they are: - -- Header: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9` -- Payload: `eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJlbWFpbCI6ImhlbGxvQHdvcmxkLmNvbSJ9` -- Signature: `EwIaRgq4go4R2M2z7AADywZ2ToxG4gDMoG4SQ1X3GJ0` - -The Split Token approach provides a solution by: - -1. Separating the JWT into its three component parts: header, payload, and signature -2. Storing only the signature on the client side (which by itself is meaningless) -3. Keeping the header and payload securely on the server side (in Tyk) -4. Reconstructing the complete JWT when needed for authentication - -This approach combines the benefits of JWTs (rich claims, stateless validation) with the security of opaque tokens (no information disclosure). - -### When to Use Split Token Flow - -Consider using Split Token Flow when: - -- Your JWT payload contains sensitive information that shouldn't be exposed to clients -- You want to prevent token inspection by malicious actors -- You need the flexibility of JWT while maintaining higher security -- You're implementing systems that must meet strict security compliance requirements - -### How Split Token Flow Works - -Here's how the process works with Tyk Gateway: - -1. Token Issuance: - - - A `/token` endpoint is configured on Tyk from which the client should request the access token - - Tyk requests an access token from an authorization server (e.g., Keycloak) on behalf of the client - - The authorization server returns a complete JWT - - Tyk intercepts this response through a Virtual Endpoint - - Tyk splits the JWT into its components and stores the header and payload in its Redis database - - Only the signature portion is returned to the client as an "opaque" token - -2. Token Usage: - - - The client makes API requests using only the signature as their access token - - Tyk receives the request and looks up the stored header and payload using the signature - - Tyk reconstructs the complete JWT and validates it - - If valid, Tyk forwards the request to the upstream API with the full JWT - -3. Security Benefits: - - - The client never possesses the complete JWT, only a meaningless signature - - Token contents cannot be inspected by client-side code or malicious actors - - Token validation still occurs using standard JWT verification - - -### Implementing Split Token Flow - -1. **Create a Virtual Endpoint for Token Issuance** - - First, create a virtual endpoint in Tyk that will: - - - Receive authentication requests from clients - - Forward these requests to your authorization server - - Split the returned JWT - - Store the header and payload in Tyk's storage - - Return only the signature to the client - - Here's a simplified implementation: - - ```javascript - function splitTokenHandler(request, session, config) { - // 1. Forward the client's credentials to the authorization server - var authServerResponse = forwardToAuthServer(request); - - if (authServerResponse.Code !== 200) { - return TykJsResponse({ - Body: authServerResponse.Body, - Code: authServerResponse.Code - }, session.meta_data); - } - - // 2. Extract the JWT from the response - var responseBody = JSON.parse(authServerResponse.Body); - var fullJWT = responseBody.access_token; - - // 3. Split the JWT into its components - var jwtParts = fullJWT.split("."); - var header = jwtParts[0]; - var payload = jwtParts[1]; - var signature = jwtParts[2]; - - // 4. Store the complete JWT in Tyk's Redis database using the signature as the key - // This function would use Tyk's storage API to save the data - storeJWTComponents(signature, header, payload, fullJWT); - - // 5. Modify the response to return only the signature - responseBody.access_token = signature; - - return TykJsResponse({ - Body: JSON.stringify(responseBody), - Code: 200 - }, session.meta_data); - } - ``` - - Note that this example includes some level of abstraction for clarity and so is not a full implementation. - -2. **Configure Custom Pre-Auth Plugin** - - Next, create a custom pre-auth plugin that reconstructs the JWT before it reaches the standard Tyk JWT Auth middleware: - - ```javascript - function reconstructJWT(request, session, config) { - // 1. Extract the signature from the Authorization header - var authHeader = request.Headers["Authorization"]; - var signature = authHeader.replace("Bearer ", ""); - - // 2. Retrieve the stored JWT components using the signature - var storedJWT = retrieveJWTComponents(signature); - - if (!storedJWT) { - return TykJsResponse({ - Body: "Invalid token", - Code: 401 - }, session.meta_data); - } - - // 3. Replace the Authorization header with the full JWT - request.SetHeaders["Authorization"] = "Bearer " + storedJWT.fullJWT; - - return request; - } - ``` - -3. **Test the Implementation** - - To test your Split Token Flow: - - Request a token from your Tyk virtual endpoint: - - ```bash - curl -X POST https://your-tyk-gateway/token \ - -d "grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret" - ``` - - You'll receive a response with only the signature as the access token, for example: - - ```json - { - "access_token": "EwIaRgq4go4R2M2z7AADywZ2ToxG4gDMoG4SQ1X3GJ0", - "token_type": "bearer", - "expires_in": 3600 - } - ``` - - Use this token to access your JWT Auth protected API where you have configured the custom pre-auth plugin and JWT Auth: - - ```bash - curl https://your-tyk-gateway/protected-api \ - -H "Authorization: Bearer EwIaRgq4go4R2M2z7AADywZ2ToxG4gDMoG4SQ1X3GJ0" - ``` - - diff --git a/docs.json b/docs.json index a9341166f..c367025da 100644 --- a/docs.json +++ b/docs.json @@ -333,8 +333,10 @@ "group": "JSON Web Tokens", "pages": [ "basic-config-and-security/security/authentication-authorization/json-web-tokens", + "api-management/authentication/jwt-signature-validation", "api-management/authentication/jwt-claim-validation", - "api-management/authentication/jwt-authorization" + "api-management/authentication/jwt-authorization", + "api-management/authentication/jwt-split-token" ] }, "basic-config-and-security/security/authentication-authorization/hmac-signatures", From d07e70bff509c362bbb1db70490788848035e98a Mon Sep 17 00:00:00 2001 From: Sharad Regoti Date: Thu, 20 Nov 2025 13:41:33 +0530 Subject: [PATCH 3/6] Fixes --- .gitignore | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/.gitignore b/.gitignore index 14cce41af..bcd218f54 100644 --- a/.gitignore +++ b/.gitignore @@ -1,15 +1,3 @@ -.DS_Store -backup_unused/ -backup_unused_main/ -cleanup-unused-images.sh -index.js -mintlify-fix-redirect/ -not-found.txt -transform.sh -unused_images_log.txt -urls.txt -flatten_alpha_log* - ### Node template # Logs logs From 058e1d315668bc847181bf318241266914f1dd25 Mon Sep 17 00:00:00 2001 From: Sharad Regoti Date: Thu, 20 Nov 2025 13:50:55 +0530 Subject: [PATCH 4/6] Fixes --- .../authentication/jwt-claim-validation.mdx | 22 ++----- .../jwt-signature-validation.mdx | 58 +++++-------------- 2 files changed, 20 insertions(+), 60 deletions(-) diff --git a/api-management/authentication/jwt-claim-validation.mdx b/api-management/authentication/jwt-claim-validation.mdx index 478aa99d1..ecf7001d7 100644 --- a/api-management/authentication/jwt-claim-validation.mdx +++ b/api-management/authentication/jwt-claim-validation.mdx @@ -800,24 +800,14 @@ The `nonBlocking` flag in the validation rule for `user.preferences.notification ## FAQ -
    - -
  • -
    -Can I restrict which issuers' tokens are accepted? + + Yes, you can configure `AllowedIssuers` to specify which iss (issuer) claim values are accepted. Tokens from other issuers will be rejected. + -
    -
    • - -
  • -
    -How can I validate custom claims in the JWT? - + Use the `CustomClaimValidation` configuration to validate specific claims with different validation types (Required, ExactMatch, or Contains). + -
    -
    • - -
\ No newline at end of file + \ No newline at end of file diff --git a/api-management/authentication/jwt-signature-validation.mdx b/api-management/authentication/jwt-signature-validation.mdx index 0cbe0b3d5..ddb98d782 100644 --- a/api-management/authentication/jwt-signature-validation.mdx +++ b/api-management/authentication/jwt-signature-validation.mdx @@ -250,59 +250,29 @@ curl -X DELETE http://your-gateway:8080/tyk/cache/jwks/your-api-id \ ## FAQ -
    -
  • -
    -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)? - + You can use JWKS (JSON Web Key Sets) by configuring `JWTJwksURIs` with the URLs of your JWKS endpoints. Tyk will automatically fetch and use the appropriate key based on the kid (Key ID) in the token header. + -
    -
    • - -
  • -
    -What happens if the JWKS endpoint is temporarily unavailable? - + Tyk caches JWKS responses. You can configure the cache timeout using the CacheTimeout parameter in the `JWTJwksURIs` configuration. This ensures that temporary JWKS endpoint outages don't affect API availability. + -
    -
    • - -
  • -
    -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? - + By default, Tyk refreshes the JWKS cache every 240 seconds. However, you can customize the cache timeout for each JWKS endpoint in Tyk OAS APIs using the `cacheTimeout` field in the API definition. + -
    -
    • - -
  • -
    -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 will automatically pre-fetch the keys when the API loads. + -
    -
    • - -
\ No newline at end of file + \ No newline at end of file From 13e76add7ed1fe24b3da4685c0e63c72537dbdae Mon Sep 17 00:00:00 2001 From: Sharad Regoti Date: Thu, 20 Nov 2025 16:31:40 +0530 Subject: [PATCH 5/6] Updated Overview --- .../authentication/jwt-quick-start.mdx | 95 +++++++++ .../json-web-tokens.mdx | 198 +++++------------- docs.json | 8 +- 3 files changed, 153 insertions(+), 148 deletions(-) create mode 100644 api-management/authentication/jwt-quick-start.mdx diff --git a/api-management/authentication/jwt-quick-start.mdx b/api-management/authentication/jwt-quick-start.mdx new file mode 100644 index 000000000..5afd1473a --- /dev/null +++ b/api-management/authentication/jwt-quick-start.mdx @@ -0,0 +1,95 @@ +--- +title: "JWT Quick Start: Securing APIs with Auth0 or Keycloak" +description: "Learn how to secure your Tyk OAS APIs using JWT authentication with Auth0 or Keycloak as identity providers." +keywords: "Authentication, JWT, JSON Web Tokens, Quick Start" +sidebarTitle: "Quick Start" +--- + +In this tutorial, we'll secure a Tyk OAS API using JWT authentication with either Auth0 or Keycloak as the identity provider. + + +If you want to try out JWT Auth without linking up to a third-party IdP then you can skip step 1 and provide the base64 encoded public key for your JWT (in the `source` field rather than configuring `jwksURIs`) in step 3. You'll need to generate a JWT for the request, but otherwise everything stays the same. + +Now back to the tutorial... + + +We'll start by configuring the identity provider, then set up JWT validation in Tyk, create a security policy, configure the API to use the policy, and finally test the secured API with a valid token. + +### Prerequisites + +- A Tyk installation (Cloud or Self-Managed) with Tyk Dashboard license +- An Auth0 account or Keycloak installation +- An existing Tyk OAS API (see [this tutorial](/api-management/gateway-config-managing-oas#using-tyk-dashboard-api-designer-to-create-an-api)) +- Postman, cURL, or another API testing tool + +### Step-by-Step Guide + +1. **Configure Your Identity Provider to obtain your JWKS URI** + + The first step is to configure your Identity Provider (IdP) to issue JWTs and provide a JWKS URI that Tyk can use to validate the tokens. Below are instructions for both Auth0 and Keycloak. + + + + + 1. Log in to your Auth0 dashboard + 2. Navigate to Applications > APIs and click Create API + 3. Enter a name and identifier (audience) for your API + 4. Note your Auth0 domain (e.g. `your-tenant.auth0.com`) + 5. Your JWKS URI will be: `https://your-tenant.auth0.com/.well-known/jwks.json` + + + + + + 1. Log in to your Keycloak admin console + 2. Create or select a realm (e.g. `tyk-demo`) + 3. Navigate to Clients and create a new client with: + - Client ID: `tyk-api-client` + - Client Protocol: `openid-connect` + - Access Type: `confidential` + 4. After saving, go to the Installation tab and select "OIDC JSON" format + 5. Your JWKS URI will be: `http://your-keycloak-host/realms/tyk-demo/protocol/openid-connect/certs` + + + + + +2. **Create a Security Policy** + + 1. In the Tyk Dashboard, navigate to **Policies** + 2. Click **Add Policy** + 3. Configure the policy: + - Name: `JWT Auth Policy` + - APIs: Select your Tyk OAS API + - Access Rights: Configure appropriate paths and methods + - Authentication: Select JWT + - JWT Scope Claim Name: Enter the JWT claim that contains scopes (e.g. `scope` or `permissions`) + - Required Scopes: Add any required scopes for access (optional) + 4. Click Create to save your policy + +3. **Configure JWT Authentication in Tyk OAS API** + + 1. Navigate to APIs and select your API + 2. Click **Edit** + 3. Enable **Authentication** in the **Server** section, select **JSON Web Token (JWT)** as the authentication method + 4. Configure the JWT settings: + - Token Signing Method: Select `RSA Public Key` + - Subject identity claim: Set to `sub` + - JWKS Endpoint: Enter your JWKS URI for your IdP obtained in step 1 + - Policy claim: Set to `pol` + - Default policy: Select `JWT Auth Policy` (the policy you created previously) + - Clock Skew (optional): Set to accommodate time differences (e.g. `10`) + - Authentication Token Location: `header` + - Header Name: `Authorization` + - Strip Authorization Data: `Enabled` + 5. Click **Save API** + +4. **Test your API** + + 1. Obtain a JWT from your IdP + 2. Make a request to your API providing the JWT as a Bearer token in the `Authorization` header; Tyk will validate the JWT using the JWKS that it retrieves from your JWKS URI + 3. Observe that the request is successful + + ```bash + curl -X GET {API URL} -H "Accept: application/json" -H "Authorization: Bearer {token}" + ``` \ No newline at end of file diff --git a/basic-config-and-security/security/authentication-authorization/json-web-tokens.mdx b/basic-config-and-security/security/authentication-authorization/json-web-tokens.mdx index 8d27255a8..da66397d4 100644 --- a/basic-config-and-security/security/authentication-authorization/json-web-tokens.mdx +++ b/basic-config-and-security/security/authentication-authorization/json-web-tokens.mdx @@ -7,184 +7,88 @@ sidebarTitle: "Overview" ## Introduction -JSON Web Token (JWT) is an open standard ([RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519)) that defines a compact and self-contained way for securely transmitting claims between parties as a JSON object. The information in the JSON object is digitally signed using either a secret (with the HMAC algorithm) or a public/private key pair (using RSA or ECDSA encryption) allowing the JWT to be used for client authentication. +JSON Web Token (JWT) is an open standard ([RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519)) that defines a compact and self-contained way for securely transmitting claims between parties as a JSON object. -### JWT Workflow - -JWTs are commonly used in OAuth 2.0 and OpenID Connect flows to authenticate users and authorize access to APIs. The following diagram illustrates the typical flow of JWT authentication with Tyk Gateway: - -```mermaid -sequenceDiagram - participant User - participant IdP as Identity Provider (IdP) - participant Client as Client Application - participant Tyk as Tyk Gateway - - User->>IdP: Authorizes Client - IdP-->>Client: Issues JWT (with claims) - Client->>Tyk: Sends API request with JWT - Tyk->>IdP: (Optional) Fetch JWKS for validation - Tyk-->>Tyk: Validates JWT Signature - Tyk-->>Tyk: Extracts Claims - Tyk-->>Tyk: Applies Security Policies based on Claims - Tyk-->>Client: Forwards request or responds -``` - -1. **Token Issuance by Identity Provider (IdP):** - The Identity Provider (IdP) issues a JWT with the appropriate claims. These claims represent the permissions granted by the user to the client application. - -2. **Client as Token Bearer:** - The Client Application acts as the *bearer* of the JWT (access token). Although the client may have access to multiple APIs, the user's delegated scopes restrict actual access. For example, a client with access to 5 APIs might only get a token allowing access to 2, depending on the user's delegation. - -3. **JWT Presented to Tyk Gateway:** - The client includes the JWT in its API requests to the Tyk Gateway as an access token. - -4. **JWT Validation via JWK/JWKS:** - Tyk validates the JWT's signature using a JSON Web Key (JWK). This key can be statically configured or dynamically fetched from the IdP via a JSON Web Key Set (JWKS) endpoint, supporting key rotation and multiple keys. - -5. **Authorization via Claims and Policies:** - Claims within the JWT can be used by Tyk Gateway's authorization process to configure rate and quota limits via Tyk's [Security Policy](/api-management/policies) system. Within the API definition, JWT claims can be "mapped" onto security policies which will then be applied to the request. - -6. **Stateless Authentication:** - A key advantage of JWT authentication is that Tyk does not store any user credentials or session data. It never sees the user directly - it trusts the authorization server to have authenticated the user and issued a valid token. +The information in the JSON object is digitally signed using either a secret (with the HMAC algorithm) or a public/private key pair (using RSA or ECDSA encryption) allowing the JWT to be used for client authentication. ### Key Benefits -This documentation is focused on how to use Tyk's JWT Auth and there are many excellent sources online where you can learn more about JWTs so we won't deep-dive into that topic, but to whet your appetite, here are some of the benefits from using JWT with Tyk: - - **Stateless Authentication**: Eliminates the need for server-side session storage, improving scalability. - **Flexible Integration**: Works with multiple identity providers including Auth0, Okta, and custom JWT issuers. - **Enhanced Security**: Supports multiple signature validation methods (RSA, ECDSA, HMAC) and claim verification. - **Granular Access Control**: Leverage JWT claims for policy enforcement and scope-based permissions. - **Performance Optimized**: Efficient token validation with minimal overhead and support for JWKS caching. -## Quick Start: Securing APIs with Auth0 or Keycloak - -In this tutorial, we'll secure a Tyk OAS API using JWT authentication with either Auth0 or Keycloak as the identity provider. - - - -If you want to try out JWT Auth without linking up to a third-party IdP then you can skip step 1 and provide the base64 encoded public key for your JWT (in the `source` field rather than configuring `jwksURIs`) in step 3. You'll need to generate a JWT for the request, but otherwise everything stays the same. - -Now back to the tutorial... - - - -We'll start by configuring the identity provider, then set up JWT validation in Tyk, create a security policy, configure the API to use the policy, and finally test the secured API with a valid token. - -### Prerequisites - -- A Tyk installation (Cloud or Self-Managed) with Tyk Dashboard license -- An Auth0 account or Keycloak installation -- An existing Tyk OAS API (see [this tutorial](/api-management/gateway-config-managing-oas#using-tyk-dashboard-api-designer-to-create-an-api)) -- Postman, cURL, or another API testing tool - -### Step-by-Step Guide - -1. **Configure Your Identity Provider to obtain your JWKS URI** - - The first step is to configure your Identity Provider (IdP) to issue JWTs and provide a JWKS URI that Tyk can use to validate the tokens. Below are instructions for both Auth0 and Keycloak. - - - - - 1. Log in to your Auth0 dashboard - 2. Navigate to Applications > APIs and click Create API - 3. Enter a name and identifier (audience) for your API - 4. Note your Auth0 domain (e.g. `your-tenant.auth0.com`) - 5. Your JWKS URI will be: `https://your-tenant.auth0.com/.well-known/jwks.json` +## How JWT Authentication works with Tyk - +JWTs are commonly used in OAuth 2.0 and OpenID Connect flows to authenticate users and authorize access to APIs. The following diagram and steps outline the flow when using JWT Auth to secure access to your API through Tyk. - +JSON Web Tokens Flow - 1. Log in to your Keycloak admin console - 2. Create or select a realm (e.g. `tyk-demo`) - 3. Navigate to Clients and create a new client with: - - Client ID: `tyk-api-client` - - Client Protocol: `openid-connect` - - Access Type: `confidential` - 4. After saving, go to the Installation tab and select "OIDC JSON" format - 5. Your JWKS URI will be: `http://your-keycloak-host/realms/tyk-demo/protocol/openid-connect/certs` +1. **Authentication and Token Issuance** - + Alice (the *user* or *resource owner*) authenticates with an Identity Provider (IdP) via the client application (steps 1 and 2). + - The IdP issues a JWT containing specific **claims** (permissions delegated by the user). + - The client application receives this authorization code and exchanges it for an access token (step 3). + - The client acts as the **Token Bearer**, holding the token to access protected resources on Alice's behalf. - +2. **Request to Gateway** + + When the client sends a request to the API gateway, it includes the access token (JWT) in the request, usually in the `Authorization` header as a Bearer token (step 4). -2. **Create a Security Policy** +3. **Token Validation** - 1. In the Tyk Dashboard, navigate to **Policies** - 2. Click **Add Policy** - 3. Configure the policy: - - Name: `JWT Auth Policy` - - APIs: Select your Tyk OAS API - - Access Rights: Configure appropriate paths and methods - - Authentication: Select JWT - - JWT Scope Claim Name: Enter the JWT claim that contains scopes (e.g. `scope` or `permissions`) - - Required Scopes: Add any required scopes for access (optional) - 4. Click Create to save your policy + Tyk validates the token's signature using the shared secret or public key(s) of the trusted issuer (IdP). This process typically involves: + - Locating the JWT in the request (header, cookie, or query parameter). + - Decoding the JWT header to extract the `kid` (Key ID). + - Fetching public keys from configured JWKS URIs (or using a local static key). + - Searching the retrieved keys for a match to the `kid`. + - Validating the signature using the matching JWK. + - Ensuring the token is valid and not expired. + - *If any validation step fails, the request is rejected immediately.* -3. **Configure JWT Authentication in Tyk OAS API** + To know more about how Tyk validates JWT signatures and claims, see [JWT Signature Validation](/api-management/authentication/jwt-signature-validation) and [JWT Claim Validation](/api-management/authentication/jwt-claim-validation). - 1. Navigate to APIs and select your API - 2. Click **Edit** - 3. Enable **Authentication** in the **Server** section, select **JSON Web Token (JWT)** as the authentication method - 4. Configure the JWT settings: - - Token Signing Method: Select `RSA Public Key` - - Subject identity claim: Set to `sub` - - JWKS Endpoint: Enter your JWKS URI for your IdP obtained in step 1 - - Policy claim: Set to `pol` - - Default policy: Select `JWT Auth Policy` (the policy you created previously) - - Clock Skew (optional): Set to accommodate time differences (e.g. `10`) - - Authentication Token Location: `header` - - Header Name: `Authorization` - - Strip Authorization Data: `Enabled` - 5. Click **Save API** +4. **Internal Identity Creation** -4. **Test your API** + Once validated, Tyk creates an internal session for the request (step 5). This session is used to control access rights, consumption limits, and analytics. Tyk does not store user credentials; instead, it links the session to Alice using an identity [extracted from the JWT claims](/api-management/authentication/jwt-authorization#identifying-the-session-owner). - 1. Obtain a JWT from your IdP - 2. Make a request to your API providing the JWT as a Bearer token in the `Authorization` header; Tyk will validate the JWT using the JWKS that it retrieves from your JWKS URI - 3. Observe that the request is successful + To know more about how Tyk authorizes requests using JWT claims, see [JWT Authorization](/api-management/authentication/jwt-authorization). - ```bash - curl -X GET {API URL} -H "Accept: application/json" -H "Authorization: Bearer {token}" - ``` +5. **Policy Enforcement** -## How JWT Authentication works with Tyk + Tyk enforces authorization by inspecting specific claims to determine which Security Policies apply (step 6): + - Tyk checks the **Policy Claim** (identified by the value stored in `basePolicyClaims`). + - It maps this claim to a configured Tyk Security Policy. If no direct map exists, a `defaultPolicy` may be applied. + - The applied policy configures the specific Access Rights (ACLs), rate limits, and usage quotas for that specific session. -This diagram outlines the flow when using JWT Auth to secure access to your API. + To know more about how Tyk identifies the policies to be applied, see [Identifying the Tyk Policies to be Applied](/api-management/authentication/jwt-authorization#identifying-the-tyk-policies-to-be-applied). -JSON Web Tokens Flow +6. **Proxy to Upstream** -1. Alice (the *user* or *resource owner*) authenticates with the Identity Provider (IdP) and consents to delegate specific permissions to a client application (steps 1 and 2). + If the token is valid and the policy allows the request, Tyk proxies the traffic to your upstream target service (step 7). -2. The client application receives an authorization code, which it then exchanges for an access token (step 3). This is a bearer token, meaning that the client can present it to access protected resources on behalf of the user (resource owner / Alice). -3. When the client sends a request to the API gateway , it includes the access token (JWT) in the request - usually in the Authorization header as a Bearer token (step 4). - -4. Tyk validates the token's signature, using the public key(s) of the trusted issuer (IdP): - - locate the JWT in the request (header, cookie or query parameter) - - decode the JWT - - extract the `kid` (Key ID) from the token header - - fetch the public keys from all configured JWKS URIs (or use locally declared static public key) - - merge all the retrieved public keys into a single list - - search this list for a public key matching the extracted `kid` - - if no match is found, the validation fails, and the request is rejected - - if a matching key is found, the JWT signature is validated using the parameters in the JWK - - if signature validation fails, the request is rejected - - if the token is valid and not expired, the request is authenticated as coming from the client, and is accepted - -5. Next, Tyk will create an internal session for the request which will be used to control access rights, consumption limits and to identify the request in tracking logs (step 5). The session is linked to Alice using an identity that is [extracted from the JWT claims](/api-management/authentication/jwt-authorization#identifying-the-session-owner). +### JWT Workflow -6. In step 6 Tyk will proceed to enforce authorization by checking other claims to determine which Security Policies should be applied to the session: - - check for the value in the policy claim within the JWT (identified by the value stored in `basePolicyClaims`) - - use this to identify the Tyk Security Policy (or policies) to be applied to the request - - if there is no direct policy mapping, then the `defaultPolicy` will be used - - apply the identified policies to the session, configuring access rights, rate limits and usage quota +```mermaid +sequenceDiagram + participant User + participant IdP as Identity Provider (IdP) + participant Client as Client Application + participant Tyk as Tyk Gateway + User->>IdP: Authorizes Client + IdP-->>Client: Issues JWT (with claims) + Client->>Tyk: Sends API request with JWT + Tyk->>IdP: (Optional) Fetch JWKS for validation + Tyk-->>Tyk: Validates JWT Signature + Tyk-->>Tyk: Extracts Claims + Tyk-->>Tyk: Applies Security Policies based on Claims + Tyk-->>Client: Forwards request or responds +``` -## Configuring your API to use JWT authentication +## Configuration Options The OpenAPI Specification treats JWT authentication as a variant of [bearer authentication](https://swagger.io/docs/specification/v3_0/authentication/bearer-authentication/) in the `components.securitySchemes` object using the `type: http`, `scheme: bearer` and `bearerFormat: jwt`: diff --git a/docs.json b/docs.json index c367025da..35d0d0e9c 100644 --- a/docs.json +++ b/docs.json @@ -333,10 +333,16 @@ "group": "JSON Web Tokens", "pages": [ "basic-config-and-security/security/authentication-authorization/json-web-tokens", + "api-management/authentication/jwt-quick-start", "api-management/authentication/jwt-signature-validation", "api-management/authentication/jwt-claim-validation", "api-management/authentication/jwt-authorization", - "api-management/authentication/jwt-split-token" + { + "group": "Guides", + "pages": [ + "api-management/authentication/jwt-split-token" + ] + } ] }, "basic-config-and-security/security/authentication-authorization/hmac-signatures", From 03f7b46820b7d726bacc86f39b25e6a6767144ac Mon Sep 17 00:00:00 2001 From: Sharad Regoti Date: Thu, 20 Nov 2025 17:00:49 +0530 Subject: [PATCH 6/6] Fixes --- api-management/authentication/jwt-signature-validation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-management/authentication/jwt-signature-validation.mdx b/api-management/authentication/jwt-signature-validation.mdx index ddb98d782..e344cbf32 100644 --- a/api-management/authentication/jwt-signature-validation.mdx +++ b/api-management/authentication/jwt-signature-validation.mdx @@ -122,7 +122,7 @@ x-tyk-api-gateway: ### Remotely Stored Keys (JWKS endpoint) -Tyk can retrieve public keys from JSON Web Key Sets (JWKS) endpoints to validate the signature of incoming JWTs. Tyk supports configuring [single](/api-management/authentication#single-jwks-endpoint) or [multiple](/api-management/authentication#multiple-jwks-endpoints) JWKS endpoints with [caching](/api-management/authentication#jwks-caching) capabilities. +Tyk can retrieve public keys from JSON Web Key Sets (JWKS) endpoints to validate the signature of incoming JWTs. Tyk supports configuring [single](#single-jwks-endpoint) or [multiple](#multiple-jwks-endpoints) JWKS endpoints with [caching](#jwks-caching) capabilities. #### Feature Compatibility Summary