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
- Request Arrival: For each HTTP/HTTPS request arriving at the API Gateway, the source IP address of the request is identified.
- 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?
- 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.
- 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.
- 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: 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 4: 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 5: 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 6: 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 7: 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 8: 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. |
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 openGood: 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 headerGood: 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. |