mTLS Authentication

You can provide secure mutual authentication by verifying client TLS certificates

This document explains the detailed usage of a specific policy. If you are using Apinizer policies for the first time or want to learn the general working principles of policies, we recommend reading the What is Policy? page first.

Overview

What is its Purpose?

• Perform authentication by making client certificate mandatory in corporate API Proxy traffic and ensure only authorized clients have access.
• Eliminate fake certificate risk by verifying that certificate hierarchy matches trusted Certificate Authority (CA) chains.
• Create access strategy specific to certain organizations or devices by matching client certificate with predefined Issuer ACL lists.
• Strengthen identity obtained from certificate with policy-dependent role controls by working together with authorization module.

Working Principle

1. Request Arrival: For each HTTP/HTTPS request arriving at the API Gateway, the source IP address of the request is identified.
2. Policy Check: If the mTLS Authentication policy is active, the system checks in the following order:
   • Is a Condition defined? If so, is the condition met?
   • Is the policy active (active=true)?
   • Is a Variable being used or is Apinizer default?
3. Certificate and Issuer Verification: After mTLS handshake is completed, validity dates, signature, and defined issuer list of client certificate are verified; optionally, matching is sought with Issuer ACL records.
4. Decision Making:
   • Match Found: Certificate is accepted, identity information and roles are added to header fields if needed, request routing is allowed.
   • No Match: Certificate or issuer verification fails, request routing is stopped and configured error response is returned.
5. Error Handling: Customizable HTTP status code and error message are returned for requests that do not comply with the policy rule.

Features and Capabilities

Basic Features

• Certificate Issuer Verification: Compares issuer information of incoming client certificate with registered CA chains and Issuer ACL lists.
• Dynamic Certificate Validity Check: Instantly rejects invalid certificates by checking certificate date and signature integrity for each request.
• ACL-Based Access: Defines permissions specific to certain network segments by expanding issuer-based access controls with IP verification.
• Active/Passive Status Control: Easily change the active or passive status of the policy (active/passive toggle). In passive mode, the policy is not applied but its configuration is preserved.
• Condition-Based Application: Determine when the policy will be applied by creating complex conditions with Query Builder (e.g., only for specific endpoints or header values).

Advanced Features

• Header Injection Management: Transfers to downstream services by writing user identity and roles extracted from certificate subject to custom header fields.
• Authorization Service Integration: Combines mTLS authentication with role-based access by activating authorization flows from API, database, or Secret Manager sources.
• Method-Based Permission Restrictions: Controls sensitive operations at granular level by defining access rules according to HTTP method.
• Export/Import Feature: Export policy configuration as a ZIP file. Import to different environments (Development, Test, Production). Version control and backup capability.
• Policy Group and Proxy Group Support: Manage multiple policies within Policy Group. Bulk policy assignment to Proxy Groups. Centralized update and deploy operations.
• Deploy and Versioning: Deploy policy changes to live environment. See which API Proxies use it (Policy Usage). Proxy Group and Policy Group usage reports.

Usage Scenarios

Scenario	Status	Solution (Policy Application)	Expected Behavior / Result
Financial Corporate Access	Financial services are only called from company laptops	Corporate CA certificate is added to Issuer ACL, validateCertificatesIssuer and validateACLForIssuer are activated	Requests from corporate devices are accepted, others return 403
IoT Device Identity	Edge gateways connect with certificate	validateCertificate open, device certificates are listed in ACL	Authorized device certificates are routed, expired certificates receive 401
Partner API Access	Limited endpoint access for external partners	Path condition in Query Builder, partner issuer certificate in ACL	If partner certificate matches, only defined endpoint access is provided
Multiple Environment Management	Loose control for test environment, strict control in live	validateACLForIssuer passive in development environment, active in live	Development environment remains flexible, only defined certificates are accepted in Production environment
Role-Based Authorization	Different service roles will be applied with same certificate	enableAuthorization active, roles are written to header	Downstream service grants authorization by reading role header
IP Restriction	IP matching against certificate sharing risk	checkClientIpAddress enabled, IP matching is sought in ACL	Requests with non-matching certificate-IP are rejected
Optional Scenario	(optional)

Configuring Policy Parameters

In this step, users can create a new policy or configure existing policy parameters to define access rules. The defined parameters directly affect how the policy works (e.g., which IPs will be allowed, geographical restrictions, conditional activations, etc.). This allows the policy to be customized according to organization-specific requirements while being centrally manageable.

Creating a New mTLS Authentication Policy

Configuration Steps

Step	Description / Operation
Step 1: Go to Creation Page	- Go to Development → Global Settings → Global Policies → mTLS Authentication Policy from the left menu. - Click the [+ Create] button at the top right.
Step 2: Enter Basic Information	Policy Status: Shows Active/Passive status. New policies are active by default. Name (Required): Example: Production_mTLSAuth - Enter a unique name, does not start with space. - System automatically checks. Green checkmark: available. Red X: existing name. Description: Example: “mTLS authentication for corporate clients” - Max. 1000 characters. - Explain the purpose of the policy.
Step 3: Variable Usage	- In the action button area at the top of the page, you can use the [<> Variable] button to select dynamic values. - Using context/global variable expressions, you can manage policy parameters with variable-based values instead of fixed values. - This reduces manual update effort when values change and provides operational convenience. - For detailed information, review Dynamic Variables.
Step 4: Certificate Verification Parameters	- Validate Certificates Issuer: Makes matching of CA chain with defined issuer records mandatory. - Validate Certificate: Checks validity dates and signature of certificate. - Validate ACL For Issuer: Activates issuer-based ACL table; Warning: Policy may return 401 if Issuer list is empty.
Step 5: ACL and IP Matching	- Check Client IP Address: Seeks matching of client IP registered with certificate. - Define authorized IP blocks from Issuer ACL management screen. - Keep IP control active against certificate sharing risk.
Step 6: Header and Authorization Settings	- Add User To Header: Writes user identity extracted from certificate subject to User Header Name field. - User Header Name: Default X-Authenticated-UserId, customize if needed. - Enable Authorization: Activates role and method-based controls; resources and roles in Authorization tab must be defined.
Step 7: Define Condition (Optional)	- Go to Condition tab. - Conditions determine when the policy will be active. Examples: - Environment-based: Header = X-Environment, Operator = Equals, Value = production - API Key-based: Header = X-API-Key, Starts With = PROD- - Endpoint-based: Path = /api/admin/* If you do not define condition, policy is always active
Step 8: Customize Error Message (Optional)	- Go to Error Message Customization tab. - Customize the message to be returned when access is denied. Default: { "statusCode": 403, "message": "[Default error message]" } Custom: { "statusCode": 403, "errorCode": "[CUSTOM_ERROR_CODE]", "message": "[Custom message]" }
Step 9: Save	- Click the [Save] button at the top right. Checklist: Unique name. Required fields filled. At least one issuer or ACL entry exists. Result: - Policy is added to the list. - Can be connected to APIs. - If global policy, automatically applied.

For descriptions of Conditions and Error Message Customization panels, you can review the Conditions and Error Message Customization sections on the What is Policy? page.

For a complete guide on all layers, priority order and scenario examples of the error message configuration system, see the Error Message Configuration Guide page.

Deleting the Policy

For deletion steps of this policy and operations to be applied when in use, you can refer to the Remove Policy from Flow section on the Policy Management page.

Exporting/Importing the Policy

For export (Export) and import (Import) steps of this policy, you can refer to the Export/Import page.

Connecting the Policy to API

For the process of how this policy will be connected to APIs, you can refer to the Connect Policy to API section on the Policy Management page.

Advanced Features

Feature	Description and Steps
Issuer ACL Management	- Multiple Subject Alternative Name records can be made per issuer. - Filter ACL records environment-based. - Recommendation: Make test API call after ACL changes.
Authorization with Secret Manager	- When useSecretManagerForAuthorization is selected, identity information is stored securely. - Redeploy policy when Secret is updated. - Delete old secrets after rotation.
Method-Based Authorization Policies	- Define allow/deny rules according to HTTP method. - Enter endpoint + method matching in policyAuthorizationMethodDefList. - Postman collection validation is recommended after all changes.

Best Practices

Things to Do and Best Practices

Category	Description / Recommendations
Certificate Management	Bad: Forgetting to manually update CA lists Good: Updating Issuer ACL when CA is renewed Best: Setting up automatic CA synchronization pipeline
Authorization Integration	Bad: Leaving role lists empty when enableAuthorization is open Good: Applying minimum privilege principle for roles Best: Running automatic tests in CI/CD when roles are changed
Header Usage	Bad: Downstream services not validating X-Authenticated-UserId header Good: Implementing header validation in services behind gateway Best: Adding header signature mechanism
Condition Management	Bad: Applying policy unconditionally to all endpoints Good: Targeting sensitive endpoints with Query Builder Best: Configuring conditions environment and version-based
Deployment Process	Bad: Making direct changes in production environment Good: Trying certificate scenarios in test environment Best: Creating Blue/Green deployment plan.

Security Best Practices

Security Area	Description / Warnings
Certificate Revocation List	Update periodically if CRL/OCSP checks are done outside gateway.
Issuer ACL Hardness	Leaving Issuer ACL empty weakens client verification. Definitely add authorized issuer.
Header Protection	Use signature or secure communication after mTLS termination against header spoofing in downstream services.
IP Matching	Keep whitelist current for clients using dynamic IP if checkClientIpAddress is active.
Logging	Store certificate verification errors masked in secure logs, anonymize personal data.

Things to Avoid

Category	Description / Warnings
Missing Issuer ACL	Why to avoid: All certificates become acceptable. Alternative: Add minimum trusted CA set to Issuer ACL.
Unauthorized Header Usage	Why to avoid: Identity spoofing occurs in downstream services. Alternative: Fix header names according to corporate standards.
Skipping Test Environment	Why to avoid: Errors in certificate chain create interruption in live. Alternative: Validate every change with automatic tests.
Unnecessarily Closing IP Control	Why to avoid: Leaves door open to certificate sharing. Alternative: Create separate ACL groups for dynamic IP management.

Performance Tips

Criterion	Recommendation / Impact
Handshake Optimization	Recommendation: Enable TLS session resumption. Impact: Handshake time decreases, latency drops.
Certificate Cache	Recommendation: Keep verified certificates in short-term memory. Impact: CPU load decreases in repeated calls.
Issuer ACL Lookup	Recommendation: Manage ACL queries with in-memory data structures. Impact: Query speed increases in large ACL lists.
Logging Level	Recommendation: Activate debug logs only in Development environment. Impact: I/O load and disk usage decrease in Production environment.
Authorization Calls	Recommendation: Add timeout and Circuit Breaker to authorization service calls. Impact: External service slowdowns do not affect API response time.

Frequently Asked Questions (FAQ)

Category	Question	Answer
General	What is mTLS authentication?	Mutual TLS (mTLS) is a bidirectional authentication mechanism where both client and server verify each other’s certificates.
General	What is Issuer ACL?	Issuer ACL is an access control list defining which Certificate Authority (CA) certificates will be accepted.
Technical	How does certificate verification work?	Gateway receives client certificate during TLS handshake, checks validity dates, signature, and issuer information.
Technical	Is IP control mandatory?	No, but recommended especially in production environments against certificate sharing risk.
Usage	How are different certificate policies defined for different endpoints?	Create endpoint-based conditions in Query Builder and assign separate policy for each condition.
Usage	How can I change default error message?	You can edit status code, error code, and message fields from Error Message Customization tab.
General	When should mTLS Authentication Policy be used?	Should be used in all scenarios requiring certificate-based client verification (partner integrations, corporate device access, high-security APIs).
General	What happens if I don’t define Issuer ACL?	If Issuer ACL is closed, policy accepts all valid certificates; if ACL is open but empty, all requests are rejected. Therefore, manage ACL according to requirements.
Technical	What does Enable Authorization provide?	Triggers role and method-based authorization controls after certificate verification; works integrated with Authorization services or Secret Manager.
Technical	How does IP control work?	If checkClientIpAddress is enabled, client’s connection IP is matched with ACL records; non-matching requests return 403.
Usage	How should I test policy changes?	Try mTLS handshakes using same certificate chain in test environment, validate Query Builder conditions with Postman or automation tests.
Usage	What information is in exported ZIP file?	Contains policy JSON content, dependent Issuer ACL and error message configurations, and metadata files; integrity check is performed during import.