您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

如何使用 API 管理中的客户端证书身份验证确保 API 安全How to secure APIs using client certificate authentication in API Management

API 管理提供的功能可确保使用客户端证书安全地访问 API(即,客户端到 API 管理)。API Management provides the capability to secure access to APIs (i.e., client to API Management) using client certificates. 可以使用策略表达式验证传入证书并根据所需值检查证书属性。You can validate incoming certificate and check certificate properties against desired values using policy expressions.

若要了解如何使用客户端证书保护对 API 后端服务的访问(即,从 API 管理到后端),请参阅如何使用客户端证书身份验证保护后端服务For information about securing access to the back-end service of an API using client certificates (i.e., API Management to backend), see How to secure back-end services using client certificate authentication

重要

若要在开发人员层、基本层、标准层或高级层中通过 HTTP/2 接收和验证客户端证书,必须在“自定义域”边栏选项卡上启用“协商客户端证书”设置,如下所示。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.

协商客户端证书

重要

若要在“消耗”层中接收并验证客户端证书,必须在“自定义域”边栏选项卡上启用“请求客户端证书”设置,如下所示。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.

请求客户端证书

检查颁发者和使用者Checking the issuer and subject

可以将以下策略配置为检查客户端证书的颁发者和使用者:Below policies can be configured to check the issuer and subject of a client certificate:

<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()To disable checking certificate revocation list use context.Request.Certificate.VerifyNoRevocation() instead of context.Request.Certificate.Verify(). 如果客户端证书是自签名证书,则必须将根(或中间)CA 证书上传到 API 管理,context.Request.Certificate.Verify()context.Request.Certificate.VerifyNoRevocation() 才能正常工作。If client certificate is self-signed, root (or intermediate) CA certificate(s) must be uploaded to API Management for context.Request.Certificate.Verify() and context.Request.Certificate.VerifyNoRevocation() to work.

检查指纹Checking the thumbprint

可以将以下策略配置为检查客户端证书的指纹:Below policies can be configured to check the thumbprint of a client certificate:

<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()To disable checking certificate revocation list use context.Request.Certificate.VerifyNoRevocation() instead of context.Request.Certificate.Verify(). 如果客户端证书是自签名证书,则必须将根(或中间)CA 证书上传到 API 管理,context.Request.Certificate.Verify()context.Request.Certificate.VerifyNoRevocation() 才能正常工作。If client certificate is self-signed, root (or intermediate) CA certificate(s) must be uploaded to API Management for context.Request.Certificate.Verify() and context.Request.Certificate.VerifyNoRevocation() to work.

针对已上传到 API 管理的证书检查指纹Checking a thumbprint against certificates uploaded to API Management

以下示例演示如何针对已上传到 API 管理的证书,检查客户端证书的指纹:The following example shows how to check the thumbprint of a client certificate against certificates uploaded to 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()To disable checking certificate revocation list use context.Request.Certificate.VerifyNoRevocation() instead of context.Request.Certificate.Verify(). 如果客户端证书是自签名证书,则必须将根(或中间)CA 证书上传到 API 管理,context.Request.Certificate.Verify()context.Request.Certificate.VerifyNoRevocation() 才能正常工作。If client certificate is self-signed, root (or intermediate) CA certificate(s) must be uploaded to API Management for context.Request.Certificate.Verify() and context.Request.Certificate.VerifyNoRevocation() to work.

提示

中所述的客户端证书死锁问题可以通过多种方式表现出来,例如:请求冻结、请求在超时后生成 403 Forbidden 状态代码、context.Request.CertificatenullClient certificate deadlock issue described in this article can manifest itself in several ways, e.g. requests freeze, requests result in 403 Forbidden status code after timing out, context.Request.Certificate is null. 此问题通常会影响内容长度约为 60KB 或更大的 POSTPUT 请求。This problem usually affects POST and PUT requests with content length of approximately 60KB or larger. 若要防止出现此问题,请在“自定义域”边栏选项卡上为所需主机名启用“协商客户端证书”设置,如本文档的第一个图像所示。To prevent this issue from occurring turn on "Negotiate client certificate" setting for desired hostnames on the "Custom domains" blade as shown in the first image of this document. 在“消耗”层中,此功能不可用。This feature is not available in the Consumption tier.

自承载网关上的证书验证Certificate validation in self-hosted gateway

默认 API 管理 自承载网关 映像不支持使用上载到 API 管理实例的 CA 根证书 验证服务器和客户端证书。The default API Management self-hosted gateway image doesn't support validating server and client certificates using CA root certificates uploaded to an API Management instance. 向自承载网关呈现自定义证书的客户端可能会遇到较慢的响应,因为证书吊销列表 (CRL) 验证可能需要较长时间才能在网关上超时。Clients presenting a custom certificate to the self-hosted gateway may experience slow responses, because certificate revocation list (CRL) validation can take a long time to time out on the gateway.

在运行网关时,可以将 PKI IP 地址配置为指向 localhost 地址 (127.0.0.1) 而不是 API 管理实例。As a workaround when running the gateway, you may configure the PKI IP address to point to the localhost address (127.0.0.1) instead of the API Management instance. 当网关尝试验证客户端证书时,这会导致 CRL 验证快速失败。This causes the CRL validation to fail quickly when the gateway attempts to validate the client certificate. 若要配置网关,请将 API 管理实例的 DNS 条目添加到容器中文件中的 localhost /etc/hostsTo configure the gateway, add a DNS entry for the API Management instance to resolve to the localhost in the /etc/hosts file in the container. 可以在网关部署过程中添加此条目:You can add this entry during gateway deployment:

后续步骤Next steps