Compartilhar via

如何在 API Management 中使用客户端证书身份验证保护 API

适用于：API 管理的所有层级

API Management 提供了使用客户端证书和双向 TLS 身份验证来保护 API（即从客户端到 API Management）访问的功能。 你可以验证连接客户端提供的证书，并使用策略表达式，对照所需的值检查证书属性。

有关通过使用客户端证书或 API 管理来保护 API 后端服务访问的信息，请参阅 保护后端服务。

有关 API 授权的概念性概述，请参阅 身份验证和授权。

证书选项

对于证书验证，API Management可以检查API Management实例中托管的证书。 如果选择使用API Management来管理客户端证书，则可以使用以下选项：

  • 引用在 Azure Key Vault 中管理的证书
  • 直接在API Management中添加证书文件

建议使用密钥保管库证书，因为这种方法有助于提高API Management的安全性。

  • 密钥保管库中存储的证书可以在服务上重复使用
  • 可以将精细的访问策略应用于存储在密钥保管库中的证书
  • 在密钥保管库中更新的证书会在 API 管理中自动轮换。 在key vault更新后，API Management中的证书在 4 小时内更新。 还可以使用Azure portal或使用管理 REST API 手动刷新证书。

先决条件

  • 如果尚未创建API Management服务实例，请参阅 创建API Management服务实例。

  • 需要访问证书和密码才能管理Azure密钥保管库，或将其上传到API管理服务。 证书必须采用 CER 或 PFX 格式。 允许使用自签名证书。

    如果使用自签名证书，请在 API Management 实例中安装受信任的根证书和中间 CA 证书。

    注意事项

    消耗层不支持用于证书验证的 CA 证书。

Key Vault 集成的先决条件

  1. 如果您还没有密钥保管库，请创建一个。 有关创建密钥库的信息，请参阅 快速入门：使用 Azure 门户创建密钥库。

  2. 在API Management中启用系统分配的或用户分配的托管标识。

配置访问权限到密钥保管库

  1. 在门户中，访问您的密钥保管库。
  2. 在左侧菜单中，选择设置>访问配置。 请注意配置的权限模型。
  3. 根据权限模型，为 API Management 托管标识配置 密钥库访问策略或 Azure RBAC 访问。

添加密钥保管库的访问策略：

  1. 在左侧菜单中，选择访问策略。
  2. 在访问策略页上，选择+ 创建。
  3. 在“ 权限 ”选项卡上的“ 机密权限”下，选择“ 获取 和 列出”，然后选择“ 下一步”。
  4. 在“主体”选项卡上搜索托管标识的资源名称，然后选择“下一步”。 如果您使用的是系统自动分配的身份，则主体是您的 API Management 实例的名称。
  5. 再次选择“下一步”。 在“查看 + 创建”选项卡上，选择“创建”。

若要在key vault中创建证书或将证书导入key vault，请参阅 Quickstart：使用 Azure portal 设置证书并从Azure Key Vault检索证书。

关于Key Vault防火墙的要求

如果在key vault上启用了 Key Vault 防火墙，则必须满足以下要求：

  • 必须使用API Management实例的系统分配托管标识以访问密钥保管库。

  • 在Key Vault防火墙中，启用 Allow Trusted Microsoft Services 以绕过此防火墙选项。 API Management支持信任服务连接，以访问控制平面选项的密钥保管库。

  • 确保在选择要添加到 Azure API Management 的证书或机密时，允许本地客户端 IP 地址临时访问密钥保管库。 有关详细信息，请参阅 配置Azure Key Vault网络设置。

    完成配置后，可以在key vault防火墙中阻止客户端地址。

重要

自 2026 年 3 月起，允许受信任的 Microsoft 服务通过 API Management 网关连接到 Azure 服务的防火墙设置将不再受支持。 若要在此更改后继续从 API Management 网关访问这些服务，请确保选择其他受支持的网络访问选项。 对于控制平面操作，您可以继续使用受信任的服务连接。 了解详细信息。

虚拟网络要求

如果API Management实例部署在virtual network中，还配置以下网络设置：

  • 启用service endpoint以便在 API Management 子网中使用 Key Vault。
  • 配置一个网络安全组 (NSG) 规则，以允许指向 AzureKeyVault 和 AzureActiveDirectory 服务标记的出站流量。

有关详细信息，请参阅在虚拟网络中设置 API Management 时的网络配置。

添加密钥库证书

请参阅 密钥保管库集成的先决条件。

重要

若要将 Key Vault 证书添加到 API Management 实例，必须拥有从 Key Vault 中列出机密的权限。

注意

在 API Management 中使用 key vault 证书时，请注意不要删除用于访问 key vault 的证书、key vault 或托管标识。

若要将密钥保管库证书添加到 API 管理，请执行以下操作：

  1. 在 Azure portal 中，转到API Management实例。

  2. 在“安全性”下，选择“证书”。

  3. 选择证书>+ 添加。

  4. 在 ID 中，输入名称。

  5. 在 Certificate 中，选择 Key vault。

  6. 输入key vault证书的标识符，或选择 Select 从key vault中选择证书。

    重要

    如果自行输入 Key Vault 证书标识符，请确保它不包含版本信息。 否则，在key vault更新后，证书不会在API Management中自动轮换。

  7. 在 客户端标识中，选择系统分配的标识或现有的用户分配托管标识。 有关详细信息，请参阅 在 Azure API 管理中使用托管标识。

    注意事项

    标识需要具有从“key vault”中获取和列出证书的权限。 如果尚未配置密钥保管库的访问权限，API Management会提示您，以便它可以自动配置具有所需权限的标识。

  8. 选择 添加。

    截图，显示如何在门户中将密钥保管库证书添加到 API 管理中。

  9. 选择“保存”。

上传证书

将客户端证书上传到API Management：

  1. 在 Azure portal 中，转到API Management实例。

  2. 在“安全性”下，选择“证书”。

  3. 选择证书>+ 添加。

  4. 在 ID 中，输入名称。

  5. 在“证书”下，选择“自定义”。

  6. 浏览以选择证书 .pfx 文件并输入其密码。

  7. 选择 添加。

    上传客户端证书到 API 管理门户的截图。

  8. 选择“保存”。

注意事项

如果只想使用证书通过 API Management 对客户端进行身份验证，则可以上传 CER 文件。

启用API Management实例以接收和验证客户端证书

开发人员、基本、标准和高级层

若要在开发人员层、基本层、标准层或高级层中通过 HTTP/2 接收和验证客户端证书，必须启用 协商客户端证书。

  1. 选择 “部署 + 基础结构”，然后选择 “自定义域”。

  2. 选择网关主机名。

  3. 在 “网关 ”页中，选择 “协商客户端证书”，然后选择 “更新”。

    截图显示了自定义域的协商客户端证书选项。

消费层级

若要在消耗层中接收和验证客户端证书，必须启用 请求客户端证书。

  1. 选择 “部署 + 基础结构”，然后选择 “自定义域”。

  2. 在 客户端证书下，启用 请求客户端证书。

    屏幕截图显示用于请求自定义域的客户端证书的选项。

验证客户端证书的策略

使用 validate-client-certificate 策略来验证用于访问您的 API 管理实例中托管的 API 的客户端证书的一个或多个属性。

配置策略以验证一个或多个属性，包括证书颁发者、主题、指纹、是否根据联机吊销列表验证证书等。

使用上下文变量的证书验证

还可使用 context 变量创建策略表达式以检查客户端证书。 以下各节中的示例显示了使用 context.Request.Certificate 属性和其他 context 属性的表达式。

注意事项

当API Management网关终结点通过Application Gateway公开时，相互证书身份验证可能无法正常工作。 应用程序网关充当第 7 层负载均衡器，与后端的 API 管理服务建立独立的 TLS 连接。 初始 HTTP 请求中客户端附加的证书不会转发到 APIM。

解决方法是，可以使用服务器变量选项传输证书。 有关详细信息，请参阅 相互身份验证服务器变量。

重要

  • 从 2021 年 5 月开始，context.Request.Certificate 属性仅在API Management实例的 hostnameConfiguration 将 negotiateClientCertificate 属性设置为 True 时请求证书。 negotiateClientCertificate 默认设置为 false。
  • 如果在客户端中禁用了 TLS 重新协商，可能会导致在使用属性 context.Request.Certificate 请求证书时看到 TLS 错误。 如果出现错误，请启用客户端中的 TLS 重新协商设置。

检查颁发者和主题

可以将以下策略配置为检查客户端证书的颁发者和使用者：

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

注意事项

若要禁止检查证书吊销列表，请使用 context.Request.Certificate.VerifyNoRevocation() 而不是 context.Request.Certificate.Verify()。

如果客户端证书是自签名的，则必须将根（或中间）CA 证书上传到 API 管理，以保证 context.Request.Certificate.Verify() 和 context.Request.Certificate.VerifyNoRevocation() 的正常运作。

检查拇指指纹

可以将以下策略配置为检查客户端证书的指纹：

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

注意事项

若要禁止检查证书吊销列表，请使用 context.Request.Certificate.VerifyNoRevocation() 而不是 context.Request.Certificate.Verify()。

如果客户端证书是自签名证书，则必须将根（或中间）CA 证书上传到API Management，以确保 context.Request.Certificate.Verify() 和 context.Request.Certificate.VerifyNoRevocation() 正常工作。

检测与上传到 API Management 的证书对应的指纹

以下示例演示如何将客户端证书的指纹与上传到 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>

注意事项

若要禁止检查证书吊销列表，请使用 context.Request.Certificate.VerifyNoRevocation() 而不是 context.Request.Certificate.Verify()。

如果客户端证书是自签名证书，则必须将根（或中间）CA 证书上传到 API Management，API 管理的 context.Request.Certificate.Verify() 和 context.Request.Certificate.VerifyNoRevocation() 功能才能正常工作。

提示

本文中所述的客户端证书死锁问题可以通过多种方式自行显示。 例如，你可能会遇到请求无响应或请求在超时时返回403 Forbidden状态代码，或者context.Request.Certificate是null。 此问题通常会影响内容长度约为 60KB 或更大的 POST 和 PUT 请求。

若要防止出现此问题，请为自定义域的所需主机名启用 Negotiate 客户端证书设置，如本文前面所示。 此功能在消费层中不可用。

相关内容

  • Last updated on