Split json page

[sharadregoti]

PR Type

Documentation

---

Description

• Add JWT signature validation documentation

• Introduce JWT Split Token guide

• Enhance JWT claim validation with FAQ

• Refine JWT authorization description

---

Diagram Walkthrough

flowchart LR
  docs["Docs structure"] -- "add" --> sig["JWT Signature Validation page"]
  docs -- "add" --> split["JWT Split Token page"]
  claim["Claim Validation page"] -- "add" --> faq1["FAQ section"]
  auth["Authorization page"] -- "update" --> desc["Improved description"]
  nav["docs.json navigation"] -- "link" --> sig
  nav -- "link" --> split

Loading

File Walkthrough

Relevant files

Documentation

jwt-authorization.mdx Clarify JWT authorization description                                        api-management/authentication/jwt-authorization.mdx Expanded page description for clarity. Emphasized identity extraction and policy application. +1/-1      jwt-claim-validation.mdx Add JWT claim validation FAQ                                                          api-management/authentication/jwt-claim-validation.mdx Added FAQ section with issuer restriction. Documented custom claim validation options. Minor trailing newline fix. +26/-2    jwt-signature-validation.mdx Add JWT signature validation guide                                              api-management/authentication/jwt-signature-validation.mdx New page detailing signature validation. Covered algorithms, key sourcing, JWKS, caching. Added config snippets and cache management API. Included comprehensive FAQ. +308/-0  jwt-split-token.mdx Introduce JWT Split Token documentation                                    api-management/authentication/jwt-split-token.mdx New guide for Split Token Flow. Explained flow with sequence diagram. Provided implementation outline and testing steps. +210/-0  json-web-tokens.mdx Extract signature/split-token into dedicated pages              basic-config-and-security/security/authentication-authorization/json-web-tokens.mdx Removed signature validation and split token sections. Consolidated to dedicated pages to reduce duplication. +0/-309  docs.json Update docs navigation for new JWT pages                                  docs.json Updated navigation to include new pages. Inserted signature validation before claim validation. Added split token page under JWT group. +3/-1

---

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 Security concerns Potential misguidance: The JWKS examples include an HTTP URL and the Split Token flow implies storing sensitive data in Redis without explicit guidance on TTL, eviction, encryption, and access controls. Recommend adding notes to use HTTPS for JWKS endpoints and to configure Redis security (TLS, auth, restricted ACLs) and appropriate expirations for stored JWT components.

⚡ Recommended focus areas for review Inconsistent Field Names In the FAQ, references to JWTJwksURIs and CacheTimeout differ from the main doc's <jwtAuthScheme>.jwksURIs and cacheTimeout. Align naming to avoid confusion. <li> <details> <summary>How do I handle JWTs signed with different keys (e.g., from different issuers)?</summary> 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. </details> </li> <li> <details> <summary>What happens if the JWKS endpoint is temporarily unavailable?</summary> 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. </details> </li> <li> <details> <summary>Can I use JWKS endpoints with symmetric cryptography (HMAC)?</summary> 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. </details> </li> <li> <details> <summary>How often does Tyk refresh the JWKS cache?</summary> 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. </details> </li> Storage Security Clarification The Split Token guide mentions storing JWT components in Redis but doesn’t discuss TTL/expiration, key namespace, or encryption at rest. Add guidance to mitigate persistence and leakage risks. // 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", Mixed Protocols in Examples JWKS example uses HTTP for Keycloak while advocating security; prefer HTTPS or clearly state it’s for demo only to avoid insecure copy-paste. ```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 </details> </td></tr> </table>

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	Fix broken internal links The intra-doc links point to generic anchors under /api-management/authentication, which may not exist after the split. Update links to the new dedicated page sections within this file to prevent broken navigation. api-management/authentication/jwt-signature-validation.mdx [125] -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. Suggestion importance[1-10]: 8 __ Why: After splitting docs, the original links to /api-management/authentication#... would likely break; switching to local anchors matches section headers present in this file and preserves navigation.	Medium
	Correct configuration key casing The property name AllowedIssuers does not match earlier naming conventions used in OAS fragments (lower camel or snake). Replace with the correct configuration key used elsewhere (e.g., allowedIssuers) to avoid misconfiguration. api-management/authentication/jwt-claim-validation.mdx [809-811] ## FAQ <ul> <li> <details> <summary>Can I restrict which issuers' tokens are accepted?</summary> -Yes, you can configure `AllowedIssuers` to specify which iss (issuer) claim values are accepted. Tokens from other issuers will be rejected. +Yes, you can configure `allowedIssuers` to specify which iss (issuer) claim values are accepted. Tokens from other issuers will be rejected. </details> </li> Suggestion importance[1-10]: 5 __ Why: The change from AllowedIssuers to allowedIssuers improves consistency, but the correct key is not definitively established in this diff; it's a reasonable style fix with moderate impact.	Low
Possible issue	Fix inconsistent field name The field name JWTJwksURIs is inconsistent with earlier examples that use .jwksURIs. Align terminology to avoid configuration errors. Update the reference to jwksURIs to match the API definition and examples. api-management/authentication/jwt-signature-validation.mdx [265-268] -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. +You can use JWKS (JSON Web Key Sets) by configuring `jwksURIs` 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. Suggestion importance[1-10]: 7 __ Why: The doc elsewhere consistently uses jwksURIs; correcting JWTJwksURIs prevents configuration confusion and aligns with prior examples. The change is accurate and improves clarity, though not a critical bug fix.	Medium

[buger]

/release to release-5.10

[github-actions]

✅ Cherry-pick successful. A PR was created and auto-merged (if allowed): #1015