Document MTLS Authenticator policy for API proxy

[Shamly-Shanawaz]

Purpose

This PR introduces documentation with regards to the MTLS Authenticator Policy

[coderabbitai]

📝 Walkthrough

Summary

This PR introduces comprehensive documentation for the MTLS Authenticator policy, a resource-level mediation policy for API proxies. The changes include a new policy guide, updates to the policies reference list, and navigation configuration.

Changes

Documentation Files Added/Modified:

1. policies.md - Updated the resource-level policies list to include a new entry for the MTLS Authenticator policy with descriptive information about its functionality.

2. secure-client-gateway-communication-with-mtls.md - New guide document providing step-by-step instructions for enabling mutual TLS for API proxies, including:

   • Certificate generation procedures
   • Configuration steps for the MTLS Authenticator policy
   • Instructions for deploying to different environments
   • Examples for invoking the proxy with appropriate client credentials
   • Information on custom domain configuration and support requests

3. mkdocs.yml - Updated navigation configuration to include the new mutual TLS documentation page under the "Develop API Proxy" → "Policy" section.

Impact

These documentation additions enable developers to understand and implement the MTLS Authenticator policy for their API proxies, providing both reference information and practical implementation guidance.

Files Changed: 3
Lines Added: 68

Walkthrough

This pull request adds documentation for the MTLS Authenticator inbuilt mediation policy. The changes include adding a new policy entry to the policies reference list, creating a comprehensive guide with step-by-step instructions for enabling mutual TLS authentication between clients and the API gateway, and updating the navigation configuration to include the new guide. The documentation covers certificate generation, policy configuration, deployment, and client invocation procedures.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is incomplete, providing only the Purpose section with minimal detail while omitting all other required template sections (Goals, Approach, User stories, Release note, Documentation, etc.).	Complete the PR description using the template: add Goals explaining what this documentation enables, Approach with links to new docs, Release note, and confirm Documentation section shows the new/updated files.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and specifically describes the main change: adding documentation for the MTLS Authenticator policy for API proxies.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

en/docs/develop-api-proxy/policy/secure-client-gateway-communication-with-mtls.md (1)

11-13: Add security guidance for private key protection.

The OpenSSL command uses the -nodes flag, which creates an unencrypted private key file. While this simplifies development and testing, it poses a security risk if the key file is not properly protected.

Consider adding a note to warn users that the generated private key is unencrypted and should be stored securely with appropriate file permissions (e.g., chmod 600 mykey.pem), or guide them to use encrypted keys for production environments.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@en/docs/develop-api-proxy/policy/secure-client-gateway-communication-with-mtls.md`
around lines 11 - 13, The OpenSSL command shown (openssl req -x509 -newkey
rsa:2048 -keyout mykey.pem -out mycert.pem -days 365 -nodes) generates an
unencrypted private key due to the -nodes flag; update the doc around that
snippet to warn users the private key is unencrypted, instruct them to protect
the key with strict file permissions (e.g., chmod 600 mykey.pem) for local/dev
use, and add guidance to use encrypted keys in production by omitting -nodes and
supplying a passphrase or using a secure key management solution.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@en/docs/develop-api-proxy/policy/policies.md`:
- Line 30: The link to the mTLS guide in the "MTLS Authenticator" paragraph is
using an incorrect relative path
(`../policy/secure-client-gateway-communication-with-mtls.md`) — update the link
in en/docs/develop-api-proxy/policy/policies.md (the "MTLS Authenticator" line)
to point to the sibling page using a correct relative path, e.g.
`./secure-client-gateway-communication-with-mtls/` or
`secure-client-gateway-communication-with-mtls` (omit the ../policy/ prefix and
the .md extension to match MkDocs use_directory_urls conventions).

In
`@en/docs/develop-api-proxy/policy/secure-client-gateway-communication-with-mtls.md`:
- Line 64: The relative link is too deep; replace the href string
"../../../administer/settings/configure-a-custom-domain-for-your-organization/"
with the correct two-level-up path
"../../administer/settings/configure-a-custom-domain-for-your-organization/" in
the markdown line that begins "To configure a custom domain for an API Proxy..."
so the link correctly points from the develop-api-proxy/policy document to the
administer/settings page.
- Line 21: Replace the unhyphenated phrase "Resource wise policies" with the
hyphenated form "Resource-wise policies" in both occurrences within this
document (the instances at the top of the file including the line currently
reading 'Go to Develop -> Policies and click "Resource wise policies" in the
left panel' and the second occurrence referenced in the review), ensuring the
exact quoted label text is updated so it matches other docs like "Resource-wise
Guardrails" and "Resource-level Policies".

---

Nitpick comments:
In
`@en/docs/develop-api-proxy/policy/secure-client-gateway-communication-with-mtls.md`:
- Around line 11-13: The OpenSSL command shown (openssl req -x509 -newkey
rsa:2048 -keyout mykey.pem -out mycert.pem -days 365 -nodes) generates an
unencrypted private key due to the -nodes flag; update the doc around that
snippet to warn users the private key is unencrypted, instruct them to protect
the key with strict file permissions (e.g., chmod 600 mykey.pem) for local/dev
use, and add guidance to use encrypted keys in production by omitting -nodes and
supplying a passphrase or using a secure key management solution.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 576a77fe-4ba1-4d8e-9553-779bdcc2819d

📥 Commits

Reviewing files that changed from the base of the PR and between ae8de10 and 4c35918.

⛔ Files ignored due to path filters (1)

• en/docs/assets/img/develop-api-proxy/policy/mtls-auth-policy.png is excluded by !**/*.png

📒 Files selected for processing (3)

• en/docs/develop-api-proxy/policy/policies.md
• en/docs/develop-api-proxy/policy/secure-client-gateway-communication-with-mtls.md
• en/mkdocs.yml