Improved JWKs Validation PR

[sharadregoti]

User description

Contributor checklist

• Reviewed PR Code suggestions and updated accordingly
• Tyklings: Labled the PR with the relevant releases
• Tyklings: Added Jira DX PR ticket to the subject

---

New Contributors

• Start the PR branch from our latest master
• I have read the repository contribution guidelines
• I have read the repository technical guidelines

---

---

PR Type

Documentation

---

Description

• Add dedicated JWT claim validation guide

• Extract claim validation from JWT overview

• Introduce JWT docs menu restructuring

• Clarify configs, examples, and notes

---

Diagram Walkthrough

flowchart LR
  Overview["JWT Overview (existing)"] -- "remove claim validation section" --> LeanOverview["JWT Overview (leaner)"]
  NewPage["New page: JWT Claim Validation"] -- "detailed guidance, examples" --> DocsSet["JWT Auth Docs"]
  Menu["Docs menu.yaml"] -- "make JWT a directory; add pages" --> Navigation["Updated JWT navigation"]

Loading

File Walkthrough

Relevant files

Documentation

jwt-claim-validation.md New comprehensive JWT claim validation guide                          tyk-docs/content/api-management/authentication/jwt-claim-validation.md Add new page dedicated to JWT claim validation Cover registered and custom claims validation Provide config examples, data types, dot-notation Describe non-blocking validation and clock skew +671/-0  json-web-tokens.md Extract claim validation from JWT overview                              tyk-docs/content/basic-config-and-security/security/authentication-authorization/json-web-tokens.md Remove entire Claim Validation section from JWT overview Keep surrounding JWT content intact Prepare for modular docs structure +0/-893  menu.yaml Restructure JWT navigation menu                                                    tyk-docs/data/menu.yaml Convert JWT menu item to a directory Add sub-entries: Overview, Claim Validation, Authorization Point Claim Validation to new page path +14/-2

---

[github-actions]

⚠️ Deploy preview for PR #7064 did not become live after 3 attempts.
Please check Netlify or try manually: Preview URL

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

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

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Inconsistent YAML/JSON blocks Several configuration examples are fenced as YAML but contain JSON objects (and vice versa). This may confuse readers and break copy-paste usability; ensure code fences and content formats match consistently across examples. { "customClaimValidation": { "user.profile.department": { "type": "exact_match", "allowedValues": ["Engineering", "Sales", "Marketing"] }, "user.profile.level": { "type": "contains", "allowedValues": ["senior", "lead", "principal"] } } } Non-blocking Validation The non-blocking validation feature specifically enables a gradual rollout approach to validation rules by allowing you to monitor validation failures without rejecting requests. How Non-blocking Validation Works When configured, a validation rule can be set to "non-blocking" mode, which means: If validation passes, the request proceeds normally If validation fails, instead of rejecting the request: a warning is logged in the gateway [system logs]({{< ref "api-management/logs-metrics#system-logs" >}}) the request is allowed to proceed to the upstream API This allows you to: Monitor how new validation rules would affect traffic without disrupting users Gradually roll out stricter validation requirements Debug validation issues in production environments Configuring Non-Blocking Mode Non-blocking mode can be configured for any custom claim validation rule with the addition of the boolean nonBlocking flag, for example: { "customClaimValidation": { "user.profile.department": { "type": "exact_match", "allowedValues": ["Engineering", "Sales", "Marketing"] }, "user.profile.level": { "type": "contains", "allowedValues": ["senior", "lead", "principal"] }, "user.preferences.notifications": { "type": "required", "nonBlocking": true } } } Typo/grammar Minor grammar issues (e.g., "Numbers to strings: 42 become "42"") and punctuation could be polished for clarity and professionalism. - Numbers to strings: `42` become `"42"` - Booleans to strings: `true` becomes "`true"` - Objects/arrays to strings: Converted to JSON representation ##### Best Practices Menu restructuring validation Verify the new JWT directory structure renders correctly and that paths exist (Overview, Claim Validation, Authorization). Ensure the removed single-page link is fully replaced without broken links. category: Directory show: True menu: - title: "Overview" path: /basic-config-and-security/security/authentication-authorization/json-web-tokens category: Page show: True - title: "Claim Validation" path: /api-management/authentication/jwt-claim-validation category: Page show: True - title: "Authorization" path: /api-management/authentication/jwt-authorization category: Page show: True

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Fix incorrect claim reference Replace the reference to audience with subject to avoid misleading configuration guidance. This prevents admins from assuming allowedSubjects controls audience checks. tyk-docs/content/api-management/authentication/jwt-claim-validation.md [167] -Useful for restricting API access to specific types of subjects or known entities. If `allowedSubjects` is empty, no audience validation is performed. +Useful for restricting API access to specific types of subjects or known entities. If `allowedSubjects` is empty, no subject validation is performed. Suggestion importance[1-10]: 8 __ Why: The text incorrectly says no audience validation is performed when allowedSubjects is empty; it should say subject validation. This is a clear correctness fix that prevents configuration misunderstandings.	Medium
	Fix YAML indentation nesting Ensure indentation matches the surrounding YAML structure and the menu list is properly nested under the JWT parent item. Mis-indentation can break menu rendering in static site builds. tyk-docs/data/menu.yaml [660-674] - title: "JSON Web Tokens" - category: Directory - show: True - menu: - - title: "Overview" - path: /basic-config-and-security/security/authentication-authorization/json-web-tokens - category: Page - show: True - - title: "Claim Validation" - path: /api-management/authentication/jwt-claim-validation - category: Page - show: True - - title: "Authorization" - path: /api-management/authentication/jwt-authorization - category: Page - show: True + category: Directory + show: True + menu: + - title: "Overview" + path: /basic-config-and-security/security/authentication-authorization/json-web-tokens + category: Page + show: True + - title: "Claim Validation" + path: /api-management/authentication/jwt-claim-validation + category: Page + show: True + - title: "Authorization" + path: /api-management/authentication/jwt-authorization + category: Page + show: True Suggestion importance[1-10]: 3 __ Why: While proper indentation is important in YAML, the existing diff appears consistent with surrounding indentation context. The suggestion is precautionary and low impact without clear evidence of an actual error.	Low
General	Fix malformed inline code formatting Correct the inline code quoting so only the boolean literal is code-formatted. The current nested backticks render incorrectly and can confuse readers. tyk-docs/content/api-management/authentication/jwt-claim-validation.md [566] -- Booleans to strings: `true` becomes "`true`" +- Booleans to strings: `true` becomes "true" Suggestion importance[1-10]: 6 __ Why: The nested backticks around true inside quotes are malformed in Markdown and could render poorly. The change is correct but minor and cosmetic.	Low

[netlify]

✅ PS. Add to the end of url /docs/nightly

Name	Link
🔨 Latest commit	8cda653
🔍 Latest deploy log	https://app.netlify.com/projects/tyk-docs/deploys/68f21ba5c141e70008476f23
😎 Deploy Preview	https://deploy-preview-7064--tyk-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[netlify]

✅ PS. Add to the end of url /docs/nightly

Name	Link
🔨 Latest commit	db67893
🔍 Latest deploy log	https://app.netlify.com/projects/tyk-docs/deploys/68f9d0cb5cde7200070c7e09
😎 Deploy Preview	https://deploy-preview-7064--tyk-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[andyo-tyk]

Some suggested tweaks to the content