You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/api-management/api-management-howto-mutual-certificates-for-clients.md
+27-11Lines changed: 27 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,12 +5,8 @@ description: Learn how to secure access to APIs by using client certificates. Yo
5
5
services: api-management
6
6
documentationcenter: ''
7
7
author: dlepow
8
-
manager: erikre
9
-
editor: ''
10
8
11
9
ms.service: api-management
12
-
ms.workload: mobile
13
-
ms.tgt_pltfrm: na
14
10
ms.topic: article
15
11
ms.date: 06/01/2021
16
12
ms.author: danlep
@@ -24,14 +20,36 @@ For information about securing access to the back-end service of an API using cl
24
20
25
21
For a conceptual overview of API authorization, see [Authentication and authorization in API Management](authentication-authorization-overview.md#gateway-data-plane).
26
22
23
+
## Certificate options
24
+
25
+
If you choose to use API Management to manage client certificates, you have the following options:
26
+
27
+
* Reference a certificate managed in [Azure Key Vault](../key-vault/general/overview.md)
28
+
* Add a certificate file directly in API Management
29
+
30
+
Using key vault certificates is recommended because it helps improve API Management security:
31
+
32
+
* Certificates stored in key vaults can be reused across services
33
+
* Granular [access policies](../key-vault/general/security-features.md#privileged-access) can be applied to certificates stored in key vaults
34
+
* 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.
35
+
36
+
## Prerequisites
37
+
38
+
* If you have not created an API Management service instance yet, see [Create an API Management service instance][Create an API Management service instance].
39
+
* 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.
## Enable API Management instance to negotiate client certificates
27
45
28
46
> [!IMPORTANT]
29
-
> To receive and verify client certificates over HTTP/2 in the Developer, Basic, Standard, or Premium tiers you must turn on the "Negotiate client certificate" setting on the "Custom domains" blade as shown below.
47
+
> 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.
> To receive and verify client certificates in the Consumption tier you must turn on the "Request client certificate" setting on the "Custom domains" blade as shown below.
52
+
> 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.
@@ -41,8 +59,6 @@ Use the [validate-client-certificate](validate-client-certificate-policy.md) pol
41
59
42
60
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.
43
61
44
-
For more information, see [API Management access restriction policies](api-management-access-restriction-policies.md).
45
-
46
62
## Certificate validation with context variables
47
63
48
64
You can also create policy expressions with the [`context` variable](api-management-policy-expressions.md#ContextVariables) to check client certificates. Examples in the following sections show expressions using the `context.Request.Certificate` property and other `context` properties.
@@ -66,7 +82,7 @@ Below policies can be configured to check the issuer and subject of a client cer
66
82
```
67
83
68
84
> [!NOTE]
69
-
> To disable checking certificate revocation list use `context.Request.Certificate.VerifyNoRevocation()` instead of `context.Request.Certificate.Verify()`.
85
+
> To disable checking certificate revocation list, use `context.Request.Certificate.VerifyNoRevocation()` instead of `context.Request.Certificate.Verify()`.
70
86
> If client certificate is self-signed, root (or intermediate) CA certificate(s) must be [uploaded](api-management-howto-ca-certificates.md) to API Management for `context.Request.Certificate.Verify()` and `context.Request.Certificate.VerifyNoRevocation()` to work.
71
87
72
88
### Checking the thumbprint
@@ -84,7 +100,7 @@ Below policies can be configured to check the thumbprint of a client certificate
84
100
```
85
101
86
102
> [!NOTE]
87
-
> To disable checking certificate revocation list use `context.Request.Certificate.VerifyNoRevocation()` instead of `context.Request.Certificate.Verify()`.
103
+
> To disable checking certificate revocation list, use `context.Request.Certificate.VerifyNoRevocation()` instead of `context.Request.Certificate.Verify()`.
88
104
> If client certificate is self-signed, root (or intermediate) CA certificate(s) must be [uploaded](api-management-howto-ca-certificates.md) to API Management for `context.Request.Certificate.Verify()` and `context.Request.Certificate.VerifyNoRevocation()` to work.
89
105
90
106
### Checking a thumbprint against certificates uploaded to API Management
@@ -103,7 +119,7 @@ The following example shows how to check the thumbprint of a client certificate
103
119
```
104
120
105
121
> [!NOTE]
106
-
> To disable checking certificate revocation list use `context.Request.Certificate.VerifyNoRevocation()` instead of `context.Request.Certificate.Verify()`.
122
+
> To disable checking certificate revocation list, use `context.Request.Certificate.VerifyNoRevocation()` instead of `context.Request.Certificate.Verify()`.
107
123
> If client certificate is self-signed, root (or intermediate) CA certificate(s) must be [uploaded](api-management-howto-ca-certificates.md) to API Management for `context.Request.Certificate.Verify()` and `context.Request.Certificate.VerifyNoRevocation()` to work.
Copy file name to clipboardExpand all lines: articles/api-management/api-management-howto-mutual-certificates.md
+1-59Lines changed: 1 addition & 59 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -40,65 +40,7 @@ Using key vault certificates is recommended because it helps improve API Managem
40
40
* You should have your backend service configured for client certificate authentication. To configure certificate authentication in the Azure App Service, refer to [this article][to configure certificate authentication in Azure WebSites refer to this article].
41
41
* 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.
42
42
43
-
### Prerequisites for key vault integration
44
-
45
-
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](../key-vault/general/quick-create-portal.md).
46
-
47
-
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](../key-vault/certificates/quick-create-portal.md).
48
-
49
-
* Enable a system-assigned or user-assigned [managed identity](api-management-howto-use-managed-service-identity.md) in the API Management instance.
See [Prerequisites for key vault integration](#prerequisites-for-key-vault-integration).
58
-
59
-
> [!IMPORTANT]
60
-
> When adding a key vault certificate to your API Management instance, you must have permissions to list secrets from the key vault.
61
-
62
-
> [!CAUTION]
63
-
> 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.
64
-
65
-
To add a key vault certificate to API Management:
66
-
67
-
1. In the [Azure portal](https://portal.azure.com), navigate to your API Management instance.
68
-
1. Under **Security**, select **Certificates**.
69
-
1. Select **Certificates** > **+ Add**.
70
-
1. In **Id**, enter a name of your choice.
71
-
1. In **Certificate**, select **Key vault**.
72
-
1. Enter the identifier of a key vault certificate, or choose **Select** to select a certificate from a key vault.
73
-
> [!IMPORTANT]
74
-
> 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.
75
-
1. 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](api-management-howto-use-managed-service-identity.md).
76
-
> [!NOTE]
77
-
> 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.
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. 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](../articles/key-vault/general/quick-create-portal.md).
12
+
13
+
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](../articles/key-vault/certificates/quick-create-portal.md).
14
+
15
+
* Enable a system-assigned or user-assigned [managed identity](../articles/api-management-howto-use-managed-service-identity.md) in the API Management instance.
See [Prerequisites for key vault integration](#prerequisites-for-key-vault-integration).
24
+
25
+
> [!IMPORTANT]
26
+
> When adding a key vault certificate to your API Management instance, you must have permissions to list secrets from the key vault.
27
+
28
+
> [!CAUTION]
29
+
> 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.
30
+
31
+
To add a key vault certificate to API Management:
32
+
33
+
1. In the [Azure portal](https://portal.azure.com), navigate to your API Management instance.
34
+
1. Under **Security**, select **Certificates**.
35
+
1. Select **Certificates** > **+ Add**.
36
+
1. In **Id**, enter a name of your choice.
37
+
1. In **Certificate**, select **Key vault**.
38
+
1. Enter the identifier of a key vault certificate, or choose **Select** to select a certificate from a key vault.
39
+
> [!IMPORTANT]
40
+
> 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.
41
+
1. 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](../articles/api-management/api-management-howto-use-managed-service-identity.md).
42
+
> [!NOTE]
43
+
> 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.
0 commit comments