Secure backend services by using client certificate authentication in Azure API Management

APPLIES TO: All API Management tiers

API Management allows you to secure access to the backend service of an API by using client certificates and mutual TLS authentication. This article shows how to manage certificates in API Management by using the Azure portal. It also explains how to configure an API to use a certificate to access a backend service.

You can also manage API Management certificates by using the API Management REST API.

Certificate options

API Management provides two options for managing certificates that are used to secure access to backend services:

• Reference a certificate that's managed in Azure Key Vault.
• Add a certificate file directly in API Management.

We recommend that you use key vault certificates because doing so improves 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 an update in the key vault, a certificate in API Management is updated within four hours. You can also manually refresh the certificate by using the Azure portal or via the management REST API.

Prerequisites

• If you haven't created an API Management instance yet, see Create an API Management service instance.

• Configure your backend service client certificate authentication. For information about configuring certificate authentication in Azure App Service, see Configure TLS mutual authentication in App Service.

• Ensure that you have access to the certificate and the password for management in an Azure key vault, or a certificate to upload to the API Management service. The certificate must be in PFX format. Self-signed certificates are allowed.

  If you use a self-signed certificate:

  • Install trusted root and intermediate CA certificates in your API Management instance.

    Note

    CA certificates for certificate validation aren't supported in the Consumption tier.

  • Disable certificate chain validation. See Disable certificate chain validation for self-signed certificates later in this article.

Prerequisites for key vault integration

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

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

Configure access to key vault

1. In the portal, go to your key vault.
2. In the left menu, select Access configuration. Note the Permission model that's 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, and 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 create a certificate in the key vault or import a certificate to the key vault, see Quickstart: Set and retrieve a certificate from Azure Key Vault using the Azure portal.

Requirements for Key Vault firewall

If Key Vault firewall is enabled on your key vault, you must meet these 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 can 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 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 API Management in a virtual network.

Add a key vault certificate

See Prerequisites for key vault integration.

To add a key vault certificate to API Management:

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

2. Under Security, select Certificates.

3. Select Certificates > + Add.

4. In Id, enter a name.

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, be sure 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 identity or an existing user-assigned managed identity. For more information, see Use managed identities in Azure API Management.

   Note

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

8. Select Add.

   

9. Select Save.

Upload a certificate

To upload a client certificate to API Management:

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

2. Under Security, select Certificates.

3. Select Certificates > + Add.

4. In Id, enter a name.

5. In Certificate, select Custom.

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

7. Select Add.

   

8. Select Save.

After the certificate is uploaded, it shows in the Certificates window. If you have many certificates, note the thumbprint of the certificate that you just uploaded. You'll need it to configure an API to use the client certificate for gateway authentication.

Configure an API to use client certificate for gateway authentication

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

2. Under APIs, select APIs.

3. Select an API from the list.

4. On the Design tab, select the pencil icon in the Backend section.

5. In Gateway credentials, select Client cert and then select your certificate in the Client certificate list.

6. Select Save.

   

Disable certificate chain validation for self-signed certificates

If you're using self-signed certificates, you need to disable certificate chain validation to enable API Management to communicate with the backend system. Otherwise you'll get a 500 error code. To disable this validation, you can use the New-AzApiManagementBackend (for a new backend) or Set-AzApiManagementBackend (for an existing backend) PowerShell cmdlets and set the -SkipCertificateChainValidation parameter to True:

$context = New-AzApiManagementContext -ResourceGroupName 'ContosoResourceGroup' -ServiceName 'ContosoAPIMService'
New-AzApiManagementBackend -Context  $context -Url 'https://contoso.com/myapi' -Protocol http -SkipCertificateChainValidation $true

You can also disable certificate chain validation by using the Backend REST API.

Delete a client certificate

To delete a certificate, select Delete on the ellipsis (...) menu:

Related content

• How to secure APIs using client certificate authentication in API Management
• How to add a custom CA certificate in Azure API Management
• Policies in API Management