Secure backend services 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 using client certificates and mutual TLS authentication. This guide shows how to manage certificates in an Azure API Management service instance 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 using the API Management REST API.

Certificate options

API Management provides two options to manage certificates used to secure access to backend services:

• 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

Note

We recommend that you use the Azure Az PowerShell module to interact with Azure. To get started, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.

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

• You should have your backend service configured for client certificate authentication. To configure certificate authentication in the Azure App Service, refer to this article.

• 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 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 are not supported in the Consumption tier.

  • Disable certificate chain validation

Prerequisites for key vault integration

Note

Currently, this feature isn't available in workspaces.

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 Certificate 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.

   

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.

   

8. Select Save.

After the certificate is uploaded, it shows in the Certificates window. If you have many certificates, make a note of the thumbprint of the desired certificate in order to configure an API to use a client certificate for gateway authentication.

Configure an API to use client certificate for gateway authentication

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

2. Under APIs, select APIs.

3. Select an API from the list.

4. In the Design tab, select the editor icon in the Backend section.

5. In Gateway credentials, select Client cert and select your certificate from the dropdown.

6. Select Save.

   

Caution

This change is effective immediately, and calls to operations of that API will use the certificate to authenticate on the backend server.

Tip

When a certificate is specified for gateway authentication for the backend service of an API, it becomes part of the policy for that API, and can be viewed in the policy editor.

Disable certificate chain validation for self-signed certificates

If you are using self-signed certificates, you will need to disable certificate chain validation for API Management to communicate with the backend system. Otherwise it will return a 500 error code. To configure this, you can use the New-AzApiManagementBackend (for new backend) or Set-AzApiManagementBackend (for existing backend) PowerShell cmdlets and set the -SkipCertificateChainValidation parameter to True.

$context = New-AzApiManagementContext -resourcegroup '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 it and then select Delete from the context menu (...).

Important

If the certificate is referenced by any policies, then a warning screen is displayed. To delete the certificate, you must first remove the certificate from any policies that are configured to use it.

Next steps

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