Client Certificate Authentication in Azure API Management

This tutorial guides you through configuring client certificate authentication for your APIs in Azure API Management. This method enhances security by requiring clients to present a valid certificate for authentication, rather than just a shared secret or token.

Note: Client certificate authentication is a powerful security mechanism that ensures only trusted clients can access your API. It's commonly used in scenarios where both the API provider and consumer are managed entities.

Prerequisites

  • An Azure subscription.
  • An existing Azure API Management instance.
  • An API published in your API Management instance.
  • A client certificate (e.g., PFX file) that you want to use for authentication.

Steps to Configure Client Certificate Authentication

1. Upload the Trusted Certificate Authority (CA) Certificate

You need to upload the certificate of the Certificate Authority (CA) that issued the client certificates your clients will use. This allows API Management to validate incoming client certificates.

  1. In the Azure portal, navigate to your API Management instance.
  2. Under the Security section, select Certificates.
  3. Click Add.
  4. In the Add certificate pane:
    • Certificate file: Upload your trusted CA certificate file (usually in .cer or .pem format).
    • Password: Enter the password for the certificate, if applicable.
    • Friendly name: Provide a descriptive name for the certificate (e.g., "MyCompany Root CA").
  5. Click Upload.

2. Configure the API to Require Client Certificates

Next, you need to configure your API to require client certificate authentication.

  1. Navigate to your API within API Management.
  2. Go to the Settings tab.
  3. Under Client certificate mode, select Required.
  4. Click Save.

3. Create a Policy to Validate the Client Certificate

You'll create a policy that checks for the presence and validity of the client certificate presented by the caller.

  1. Navigate to your API and select the Design tab.
  2. Click on the All operations scope, or a specific operation if you want to apply this to a single endpoint.
  3. In the Inbound processing section, click the + button to add a new policy.
  4. Select Advanced.
  5. Add the following policy snippet within the <inbound> section: 
    
<policies>
    <inbound>
        <base />
        <check-header name="X-Client-Certificate" failed-validation-error-message="Client certificate is required." ignore-case="false" />
        <choose>
            <when condition="@(context.Request.Headers.GetValueOrDefault("X-Client-Certificate") != null)">
                <validate-client-certificate thumbprint="YOUR_CA_CERTIFICATE_THUMBPRINT" failed-validation-error-message="Invalid client certificate." />
            </when>
            <otherwise>
                <return-response status-code="401" reason="Unauthorized: Client certificate missing." />
            </otherwise>
        </choose>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>
  6. Important: Replace YOUR_CA_CERTIFICATE_THUMBPRINT with the thumbprint of the CA certificate you uploaded in Step 1. You can find the thumbprint in the certificate details in the Azure portal.
  7. Click Save.

Tip: Instead of a direct thumbprint check, you can use the validate-client-certificate policy with the trusted-ca-certificates attribute to specify multiple trusted CAs if needed.

4. Testing Client Certificate Authentication

To test this configuration, your client application needs to present a valid client certificate when making requests to your API. This is typically done by configuring the HTTP client in your application to include the certificate and its private key.

When a request is made, API Management will:

  • Check for the presence of the X-Client-Certificate header (which is usually populated by the gateway when a client certificate is provided).
  • Validate the presented client certificate against the trusted CA certificate configured.
  • If valid, the request proceeds to the backend.
  • If invalid or missing, a 401 Unauthorized or 403 Forbidden error will be returned.

Client Certificate Requirements

Ensure that the client certificates used:

  • Are issued by a CA that is trusted by your API Management instance.
  • Have an appropriate subject name that might be used for authorization (e.g., in custom policies).
  • Have not expired.

Common Issues and Troubleshooting

  • 401 Unauthorized: Usually indicates that the client certificate is missing, expired, or not trusted by API Management.
  • 403 Forbidden: Might occur if the certificate is valid but doesn't meet other validation criteria (e.g., subject name mismatch in custom policies).
  • Incorrect Thumbprint: Double-check that you have entered the correct thumbprint of the CA certificate.

Important: Securely manage your client certificates and their private keys. Compromised client certificates can lead to unauthorized access.

Further Enhancements

You can extend client certificate authentication with:

  • Custom Policies: Extract information from the client certificate (like Subject Name or Issuer) to implement more granular authorization rules.
  • Certificate Revocation Lists (CRLs): Configure API Management to check against CRLs for revoked certificates.

By implementing client certificate authentication, you significantly strengthen the security posture of your APIs exposed through Azure API Management.