Skip to content

Files

Latest commit

dlepowdlepow
[APIM] Update/refresh managed identity article
Apr 6, 2022
748567f · Apr 6, 2022

History

History
159 lines (110 loc) · 9.81 KB

api-management-howto-mutual-certificates.md

File metadata and controls

159 lines (110 loc) · 9.81 KB
title titleSuffix description services documentationcenter author ms.service ms.topic ms.date ms.author ms.custom
Secure API Management backend using client certificate authentication
Azure API Management
Learn how to manage client certificates and secure backend services using client certificate authentication in Azure API Management.
api-management
dlepow
api-management
article
01/26/2021
danlep
devx-track-azurepowershell

Secure backend services using client certificate authentication in Azure API Management

API Management allows you to secure access to the backend service of an API using client certificates. 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

[!INCLUDE updated-for-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.

Prerequisites for key vault integration

  1. For steps to create a key vault, see Quickstart: Create a key vault using the Azure portal.
  2. Enable a system-assigned or user-assigned managed identity in the API Management instance.
  3. Assign a key vault access policy to the managed identity with permissions to get and list certificates from the vault. To add the policy:
    1. In the portal, navigate to your key vault.
    2. Select Settings > Access policies > + Add Access Policy.
    3. Select Secret permissions, then select Get and List.
    4. In Select principal, select the resource name of your managed identity. If you're using a system-assigned identity, the principal is the name of your API Management instance.
  4. Create or import a certificate to the key vault. See Quickstart: Set and retrieve a certificate from Azure Key Vault using the Azure portal.

[!INCLUDE api-management-key-vault-network]

Add a key vault certificate

See Prerequisites for key vault integration.

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.

    :::image type="content" source="media/api-management-howto-mutual-certificates/apim-client-cert-kv.png" alt-text="Add key vault certificate":::

  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.

    :::image type="content" source="media/api-management-howto-mutual-certificates/apim-client-cert-add.png" alt-text="Upload client certificate":::

  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.

Note

To turn off certificate chain validation when using, for example, a self-signed certificate, follow the steps described in Self-signed certificates, later in this article.

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.

    :::image type="content" source="media/api-management-howto-mutual-certificates/apim-client-cert-enable-select.png" alt-text="Use client certificate for gateway authentication":::

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.

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

Delete a client certificate

To delete a certificate, select it and then select Delete from the context menu (...).

:::image type="content" source="media/api-management-howto-mutual-certificates/apim-client-cert-delete-new.png" alt-text="Delete a certificate":::

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