[DX-2107, TT-2378] Update Multi Auth Page

[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

• Revamp multi-auth documentation structure

• Add diagrams for auth flows

• Clarify legacy vs compliant modes

• Update menu and page titles

---

Diagram Walkthrough

flowchart LR
  Docs["Multi-auth page"] -- "Rewrite and expand" --> Modes["Legacy vs Compliant"]
  Modes -- "Concepts and behavior" --> Sessions["Session object handling"]
  Docs -- "Add" --> Diagrams["Mermaid auth flow diagrams"]
  Docs -- "Improve" --> Troubleshooting["Collapsible troubleshooting sections"]
  Menu["Sidebar menu"] -- "Rename item" --> "Multi Auth"

Loading

File Walkthrough

Relevant files

Documentation

multiple-auth.md Comprehensive rewrite of multi-auth concepts and flows      tyk-docs/content/basic-config-and-security/security/authentication-authorization/multiple-auth.md Update page title and intro Add detailed legacy/compliant mode sections Insert multiple Mermaid diagrams explaining flows Refactor troubleshooting into collapsible sections +256/-87 menu.yaml Update sidebar label for multi-auth page                                  tyk-docs/data/menu.yaml Rename menu entry to "Multi Auth" Keep path to multiple-auth page unchanged +1/-1

---

[github-actions]

⚠️ Deploy preview for PR #7050 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 Possible Duplication The note about non-deterministic session provider order in Compliant mode appears both in a callout note and again as an "Important note," which repeats the same message. Consider consolidating to a single, concise explanation to avoid redundancy and potential confusion. {{< note success >}} **Note** Due to the nature of how security requirements are processed, the order in which authentication methods are evaluated within a single requirement object is not guaranteed to be deterministic. This means that if both `api_key` and `basic_auth` pass authentication, either one might end up providing the session object. {{< /note >}} **Important note**: Due to the nature of how security requirements are processed, the order in which authentication methods are evaluated within a single requirement object is not guaranteed to be deterministic. This means that if both `api_key` and `basic_auth` pass authentication, either one might end up providing the session object. Mermaid Validity The Mermaid diagrams use HTML line breaks ( ) and styled classDefs. Verify these render correctly in the docs site build, as some Markdown/Mermaid parsers may not support in node labels or extended styling, potentially causing build or render issues. ```mermaid graph LR Client([Client]) -->|Request| Gateway[Tyk Gateway] subgraph "Multiple Authentication" Gateway --> Auth1[Authentication Method 1<br>e.g., API Key] Auth1 --> Auth2[Authentication Method 2<br>e.g., Basic Auth] Auth2 --> Auth3[Authentication Method N<br>e.g., JWT] Auth3 --> SessionCreation[Create Session<br>& Apply Policies] SessionCreation --> AccessDecision{Access<br>Decision} end AccessDecision -->|Granted| Upstream[(Upstream<br>API)] AccessDecision -->|Denied| Reject[Reject Request] %% Styling classDef client fill:#f9f9f9,stroke:#333,stroke-width:2px classDef gateway fill:#d4edda,stroke:#28a745,stroke-width:2px classDef auth fill:#e2f0fb,stroke:#0275d8,stroke-width:1px classDef session fill:#d1ecf1,stroke:#17a2b8,stroke-width:1px classDef decision fill:#cce5ff,stroke:#0275d8,stroke-width:2px classDef upstream fill:#f8f9fa,stroke:#6c757d,stroke-width:2px classDef reject fill:#f8d7da,stroke:#dc3545,stroke-width:2px class Client client class Gateway gateway class Auth1,Auth2,Auth3 auth class SessionCreation session class AccessDecision decision class Upstream upstream class Reject reject </details> <details><summary><a href='https://github.com/TykTechnologies/tyk-docs/pull/7050/files#diff-f60e793794d19133e7ec8bdc59460405f2e6fcb9e7ff43250e6f4d0561860770R441-R522'><strong>Collapsible Markup</strong></a> The <details> sections include a non-breaking space before closing tags (</details> ). Ensure there are no stray characters that could break the site generator or lint checks and that nested Markdown renders properly within details/summary. </summary> ```markdown - Ensure you're not mixing `baseIdentityProvider` (Legacy) with complex security arrays (Compliant) - Check that `securityProcessingMode` matches your intended configuration </details>  <details> <summary><b>Wrong Policies or Rate Limits Applied</b></summary> **Problem**: Requests are authenticated but get unexpected rate limits or access denials. **Root Cause**: In Compliant mode, the session object comes from whichever authentication method succeeds first. **Solutions**: 1. Review security requirement order - Place most restrictive auth methods first: ```yaml security: - premium_jwt: [] # Premium users (higher limits) - basic_api_key: [] # Basic users (lower limits) ``` 2. Ensure consistent policies across auth methods: - Verify that API keys and JWT tokens for the same user have similar access rights - Check that rate limits align with your business logic 3. Debug session source: ```bash # Enable debug logging to see which auth method succeeded "log_level": "debug" ``` </details>  <details> <summary><b>Performance Issues</b></summary> **Problem**: Slower response times with multiple authentication methods. **Expected Behavior**: Some performance impact is normal due to additional processing. **Optimization**: 1. Order security requirements by likelihood: ```yaml security: - most_common_auth: [] # Try most common first - fallback_auth: [] # Fallback for edge cases ``` 2. Monitor authentication attempts: ```bash # Look for "OR wrapper" log entries showing auth attempts grep "OR wrapper" /var/log/tyk/tyk.log ``` </details>  <details> <summary><b>Debugging Tips</b></summary> Enable detailed logging in your Tyk Gateway to see which authentication methods are being attempted and which one succeeds: ```json { "global": { "log_level": "debug" } } Look for these log entries: Processing multiple security requirements (OR conditions) Confirms Compliant mode is active OR wrapper entries In Compliant mode, this shows which auth methods are being tried BaseIdentityProvider set to In Legacy mode, this shows which auth method succeeded   ```

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Fix session source inconsistency The two notes about non-deterministic session source contradict the earlier statement that the "last" method will provide the session. Remove the "last" claim and keep a single, clear note on non-determinism to avoid misleading behavior expectations. This prevents incorrect assumptions that can cause inconsistent policy application in production. tyk-docs/content/basic-config-and-security/security/authentication-authorization/multiple-auth.md [231-253] The [session object]({{< ref "api-management/policies#what-is-a-session-object" >}}) (determining rate limits, quotas, and access rights) comes from the successful authentication method. This allows different auth methods to have different associated policies and permissions. -When using **Compliant** mode, the session object handling is more dynamic: +When using **Compliant** mode, the session object handling is dynamic: 1. Between different security requirement objects (OR logic): The first security requirement that successfully authenticates will provide the session object. -2. Within a single security requirement object (AND logic): When multiple authentication methods are specified in the same requirement object (as in your example below), all methods must pass, and the **last** successfully processed authentication method will provide the session object. +2. Within a single security requirement object (AND logic): All listed authentication methods must pass. The authentication method that ultimately provides the session object is not guaranteed to be deterministic. security: api_key: [] basic_auth: [] {{< note success >}} **Note** -Due to the nature of how security requirements are processed, the order in which authentication methods are evaluated within a single requirement object is not guaranteed to be deterministic. This means that if both `api_key` and `basic_auth` pass authentication, either one might end up providing the session object. - +Within a single security requirement object, the evaluation order of authentication methods is not guaranteed. If multiple methods pass, either one might provide the session object. {{< /note >}} -**Important note**: Due to the nature of how security requirements are processed, the order in which authentication methods are evaluated within a single requirement object is not guaranteed to be deterministic. This means that if both `api_key` and `basic_auth` pass authentication, either one might end up providing the session object. - Suggestion importance[1-10]: 8 __ Why: Correctly identifies a contradiction: stating the "last" method provides the session object conflicts with the note about non-deterministic order. The proposed revision removes the misleading claim and consolidates messaging, improving accuracy and preventing misconfiguration.	Medium
General	Clarify version applicability Clarify version scope by stating the minimum Tyk version explicitly applies to OAS APIs, to prevent misinterpretation for Classic APIs. This avoids users enabling Compliant mode on unsupported versions or API types. tyk-docs/content/basic-config-and-security/security/authentication-authorization/multiple-auth.md [134] -- **Compliant Mode**: Introduced in 5.10.0, it provides enhanced flexibility by supporting a combination of AND and OR logic between authentication methods +- **Compliant Mode**: Introduced in Tyk 5.10.0 for Tyk OAS APIs, it provides enhanced flexibility by supporting a combination of AND and OR logic between authentication methods (not available for Tyk Classic APIs). Suggestion importance[1-10]: 6 __ Why: The clarification that Compliant mode applies to Tyk OAS from 5.10.0 and not Classic is accurate and helps prevent misuse. It's a minor but useful documentation improvement.	Low
	Remove non-breaking space artifact Replace non-breaking spaces after closing with standard newlines/spaces to prevent rendering or linter issues in some Markdown processors. Invisible characters can break site builds or cause layout glitches. tyk-docs/content/basic-config-and-security/security/authentication-authorization/multiple-auth.md [402-445] Suggestion importance[1-10]: 5 __ Why: The presence of a non-breaking space after is plausible given the diff shows a trailing special space; normalizing whitespace can avoid rendering/lint issues. Impact is modest but the fix is safe and improves consistency.	Low

[netlify]

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

Name	Link
🔨 Latest commit	d899bfd
🔍 Latest deploy log	https://app.netlify.com/projects/tyk-docs/deploys/68e8e392a4bd4800085a9e74
😎 Deploy Preview	https://deploy-preview-7050--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	5908d87
🔍 Latest deploy log	https://app.netlify.com/projects/tyk-docs/deploys/68ee010a566b9e000870eff3
😎 Deploy Preview	https://deploy-preview-7050--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.

[sharadregoti]

/release to release-5.10

[tykbot]

Working on it! Note that it can take a few minutes.

[tykbot]

@sharadregoti Created merge PRs