How to secure APIs using client certificate authentication in API Management

  • Article

API Management provides the capability to secure access to APIs (that is, client to API Management) using client certificates and mutual TLS authentication. You can validate certificates presented by the connecting client and check certificate properties against desired values using policy expressions.

For information about securing access to the backend service of an API using client certificates (that is, API Management to backend), see How to secure back-end services using client certificate authentication.

For a conceptual overview of API authorization, see Authentication and authorization to APIs in API Management.

Certificate options

For certificate validation, API Management can check against certificates managed in your API Management instance. If you choose to use API Management to manage client certificates, you have the following options:

  • Reference a certificate managed in Azure Key Vault
  • Add a certificate file directly in API Management

Using key vault certificates is recommended because it helps improve API Management security:

  • Certificates stored in key vaults can be reused across services
  • Granular access policies can be applied to certificates stored in key vaults
  • Certificates updated in the key vault are automatically rotated in API Management. After update in the key vault, a certificate in API Management is updated within 4 hours. You can also manually refresh the certificate using the Azure portal or via the management REST API.

Prerequisites

  • If you have not created an API Management service instance yet, see Create an API Management service instance.

  • You need access to the certificate and the password for management in an Azure key vault or upload to the API Management service. The certificate must be in either CER or PFX format. Self-signed certificates are allowed.

    If you use a self-signed certificate, also install trusted root and intermediate CA certificates in your API Management instance.

    Note

    CA certificates for certificate validation are not supported in the Consumption tier.

Prerequisites for key vault integration

  1. If you don't already have a key vault, create one. For steps to create a key vault, see Quickstart: Create a key vault using the Azure portal.

    To create or import a certificate to the key vault, see Quickstart: Set and retrieve a certificate from Azure Key Vault using the Azure portal.

  2. Enable a system-assigned or user-assigned managed identity in the API Management instance.

Configure access to key vault

  1. In the portal, navigate to your key vault.

  2. In the left menu, select Access configuration, and note the Permission model that is configured.

  3. Depending on the permission model, configure either a key vault access policy or Azure RBAC access for an API Management managed identity.

    To add a key vault access policy:

    1. In the left menu, select Access policies.
    2. On the Access policies page,select + Create.
    3. On the Permissions tab, under Secret permissions, select Get and List, then select Next.
    4. On the Principal tab, Select principal, search for the resource name of your managed identity, and then select Next. If you're using a system-assigned identity, the principal is the name of your API Management instance.
    5. Select Next again. On the Review + create tab, select Create.

    To configure Azure RBAC access:

    1. In the left menu, select Access control (IAM).
    2. On the Access control (IAM) page, select Add role assignment.
    3. On the Role tab, select Key Vault Secrets User.
    4. On the Members tab, select Managed identity > + Select members.
    5. On the Select managed identity page, select the system-assigned managed identity or a user-assigned managed identity associated with your API Management instance, and then select Select.
    6. Select Review + assign.

Requirements for Key Vault firewall

If Key Vault firewall is enabled on your key vault, the following are additional requirements:

  • You must use the API Management instance's system-assigned managed identity to access the key vault.

  • In Key Vault firewall, enable the Allow Trusted Microsoft Services to bypass this firewall option.

  • Ensure that your local client IP address is allowed to access the key vault temporarily while you select a certificate or secret to add to Azure API Management. For more information, see Configure Azure Key Vault networking settings.

    After completing the configuration, you may block your client address in the key vault firewall.

Virtual network requirements

If the API Management instance is deployed in a virtual network, also configure the following network settings:

  • Enable a service endpoint to Azure Key Vault on the API Management subnet.
  • Configure a network security group (NSG) rule to allow outbound traffic to the AzureKeyVault and AzureActiveDirectory service tags.

For details, see Network configuration when setting up Azure API Management in a VNet.

Add a key vault certificate

See Prerequisites for key vault integration.

Important

When adding a key vault certificate to your API Management instance, you must have permissions to list secrets from the key vault.

Caution

When using a key vault certificate in API Management, be careful not to delete the certificate, key vault, or managed identity used to access the key vault.

To add a key vault certificate to API Management:

  1. In the Azure portal, navigate to your API Management instance.

  2. Under Security, select Certificates.

  3. Select Certificates > + Add.

  4. In Id, enter a name of your choice.

  5. In Certificate, select Key vault.

  6. Enter the identifier of a key vault certificate, or choose Select to select a certificate from a key vault.

    Important

    If you enter a key vault certificate identifier yourself, ensure that it doesn't have version information. Otherwise, the certificate won't rotate automatically in API Management after an update in the key vault.

  7. In Client identity, select a system-assigned or an existing user-assigned managed identity. Learn how to add or modify managed identities in your API Management service.

    Note

    The identity needs permissions to get and list certificate from the key vault. If you haven't already configured access to the key vault, API Management prompts you so it can automatically configure the identity with the necessary permissions.

  8. Select Add.

    Screenshot of adding a key vault certificate to API Management in the portal.

  9. Select Save.

Upload a certificate

To upload a client certificate to API Management:

  1. In the Azure portal, navigate to your API Management instance.

  2. Under Security, select Certificates.

  3. Select Certificates > + Add.

  4. In Id, enter a name of your choice.

  5. In Certificate, select Custom.

  6. Browse to select the certificate .pfx file, and enter its password.

  7. Select Add.

    Screenshot of uploading a client certificate to API Management in the portal.

  8. Select Save.

Note

If you only wish to use the certificate to authenticate the client with API Management, you can upload a CER file.

Enable API Management instance to receive and verify client certificates

Developer, Basic, Standard, or Premium tier

To receive and verify client certificates over HTTP/2 in the Developer, Basic, Standard, or Premium tiers, you must enable the Negotiate client certificate setting on the Custom domain blade as shown below.

Negotiate client certificate

Consumption tier

To receive and verify client certificates in the Consumption tier, you must enable the Request client certificate setting on the Custom domains blade as shown below.

Request client certificate

Policy to validate client certificates

Use the validate-client-certificate policy to validate one or more attributes of a client certificate used to access APIs hosted in your API Management instance.

Configure the policy to validate one or more attributes including certificate issuer, subject, thumbprint, whether the certificate is validated against online revocation list, and others.

Certificate validation with context variables

You can also create policy expressions with the context variable to check client certificates. Examples in the following sections show expressions using the context.Request.Certificate property and other context properties.

Note

Mutual certificate authentication might not function correctly when the API Management gateway endpoint is exposed through the Application Gateway. This is because Application Gateway functions as a Layer 7 load balancer, establishing a distinct SSL connection with the backend API Management service. Consequently, the certificate attached by the client in the initial HTTP request will not be forwarded to APIM. However, as a workaround, you can transmit the certificate using the server variables option. For detailed instructions, refer to Mutual Authentication Server Variables.

Important

  • Starting May 2021, the context.Request.Certificate property only requests the certificate when the API Management instance's hostnameConfiguration sets the negotiateClientCertificate property to True. By default, negotiateClientCertificate is set to False.
  • If TLS renegotiation is disabled in your client, you may see TLS errors when requesting the certificate using the context.Request.Certificate property. If this occurs, enable TLS renegotiation settings in the client.

Checking the issuer and subject

Below policies can be configured to check the issuer and subject of a client certificate:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Issuer != "trusted-issuer" || context.Request.Certificate.SubjectName.Name != "expected-subject-name")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Note

To disable checking certificate revocation list, use context.Request.Certificate.VerifyNoRevocation() instead of context.Request.Certificate.Verify(). If client certificate is self-signed, root (or intermediate) CA certificate(s) must be uploaded to API Management for context.Request.Certificate.Verify() and context.Request.Certificate.VerifyNoRevocation() to work.

Checking the thumbprint

Below policies can be configured to check the thumbprint of a client certificate:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Thumbprint != "DESIRED-THUMBPRINT-IN-UPPER-CASE")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Note

To disable checking certificate revocation list, use context.Request.Certificate.VerifyNoRevocation() instead of context.Request.Certificate.Verify(). If client certificate is self-signed, root (or intermediate) CA certificate(s) must be uploaded to API Management for context.Request.Certificate.Verify() and context.Request.Certificate.VerifyNoRevocation() to work.

Checking a thumbprint against certificates uploaded to API Management

The following example shows how to check the thumbprint of a client certificate against certificates uploaded to API Management:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify()  || !context.Deployment.Certificates.Any(c => c.Value.Thumbprint == context.Request.Certificate.Thumbprint))" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Note

To disable checking certificate revocation list, use context.Request.Certificate.VerifyNoRevocation() instead of context.Request.Certificate.Verify(). If client certificate is self-signed, root (or intermediate) CA certificate(s) must be uploaded to API Management for context.Request.Certificate.Verify() and context.Request.Certificate.VerifyNoRevocation() to work.

Tip

Client certificate deadlock issue described in this article can manifest itself in several ways, e.g. requests freeze, requests result in 403 Forbidden status code after timing out, context.Request.Certificate is null. This problem usually affects POST and PUT requests with content length of approximately 60KB or larger. To prevent this issue from occurring turn on "Negotiate client certificate" setting for desired hostnames on the "Custom domains" blade as shown in the first image of this document. This feature is not available in the Consumption tier.

Next steps