docs: add security.allow_dynamic_mtls_token_auth configuration

[buger]

User description

Summary

Document the new gateway-level configuration flag security.allow_dynamic_mtls_token_auth that controls whether token-based authentication is allowed for APIs using dynamic client mTLS.

Changes

• Add new configuration entry in snippets/gateway-config.mdx describing the flag, its environment variable, and behavior
• Add security note in basic-config-and-security/security/mutual-tls/client-mtls.mdx explaining the new default behavior

Related PR

This documentation change accompanies the gateway code change: TykTechnologies/tyk#7671

🤖 Generated with Claude Code

---

PR Type

Documentation

---

Description

• Add security.allow_dynamic_mtls_token_auth config documentation

• Note default token authentication disabled for dynamic mTLS

• Provide environment variable and behavior details

---

File Walkthrough

Relevant files

Documentation

client-mtls.mdx Add dynamic mTLS token-auth security note                                basic-config-and-security/security/mutual-tls/client-mtls.mdx Insert security note about dynamic mTLS default behavior Reference security.allow_dynamic_mtls_token_auth toggle Explain how to restore legacy token authentication +4/-0      gateway-config.mdx Document allow_dynamic_mtls_token_auth config                        snippets/gateway-config.mdx Add security.allow_dynamic_mtls_token_auth config entry Define type, env var, default false behavior Highlight security implications and legacy option +12/-0

---

[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 Broken Link Anchor The anchor link #securityallow_dynamic_mtls_token_auth likely does not match the generated heading ID, leading to a broken link in the docs. **Security Enhancement:** By default, Tyk requires that APIs using dynamic mTLS authenticate via client certificates only. Token-based authentication is disabled for these APIs to prevent potential security bypasses. If you need to allow token-based authentication for dynamic mTLS APIs (legacy behavior), you can enable the gateway-level configuration option `security.allow_dynamic_mtls_token_auth`. See the [Gateway Configuration Reference](/gateway-config#securityallow_dynamic_mtls_token_auth) for details. Env Var Naming The environment variable name TYK_GW_SECURITY_ALLOWDYNAMICMTLSTOKENAUTH is missing underscores and may not match the actual flag name; consider using TYK_GW_SECURITY_ALLOW_DYNAMIC_MTLS_TOKEN_AUTH for consistency. ENV: <b>TYK_GW_SECURITY_ALLOWDYNAMICMTLSTOKENAUTH</b><br /> Missing Usage Example Consider adding a YAML snippet showing how to set security.allow_dynamic_mtls_token_auth in the gateway config to help users implement the change. ### security.allow_dynamic_mtls_token_auth ENV: <b>TYK_GW_SECURITY_ALLOWDYNAMICMTLSTOKENAUTH</b><br /> Type: `bool`<br /> Controls whether token-based authentication is allowed for APIs using dynamic client mTLS (APIs with `use_certificate` enabled in their auth configuration). When set to `false` (the default), requests to APIs with dynamic mTLS enabled must present a valid client certificate during the TLS handshake. Token-only authentication will be rejected with a "Client certificate required for this API" error. This prevents a security vulnerability where attackers could bypass mTLS by constructing authentication tokens from publicly available information (the organization ID and SHA256 hash of a valid certificate). When set to `true`, the legacy behavior is restored, allowing authentication via either a valid client certificate OR a valid authentication token. **Important**: This is a gateway-wide setting that affects all APIs using dynamic mTLS. For maximum security, leave this set to `false` (the default) unless you have a specific need to allow token-based authentication for dynamic mTLS APIs.

[github-actions]

PR Code Suggestions ✨

No code suggestions found for the PR.