如何使用 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 below. 在“消耗”层中,此功能不可用。This feature is not available in the Consumption tier.

协商客户端证书

后续步骤Next steps