Client Certificate Authentication or Mutual TLS Authentication is a way for a client to authenticate to a server using a certificate. The client certificate is issued by a trusted Certificate Authority (CA) and is used to authenticate the client to the server. The server can then use the information in the certificate to authenticate the client and authorize access to the API. This is one of the most secure ways for customers to authenticate into your APIs.
When setting up client certificate authentication in Azure API Management Service, there are two different ways to do it. The first way is to use and the one they have in Microsoft’s main documentation page is uploading each certificate to your API Management Service and have the service check if the certificate is in the list of approved certificates. This is a very manual process and is not scalable and it is no longer recommended by industry standards. The second way is to use a Certificate Authority and have the API Management Service validate the issuer of the certificate is a trusted certificate Authority and pass the subject name to your backend service for authorization. This is a much more scalable solution due to only having to manage the CA certificates, and it even allows for self service certificate rotation for your customers without having your team involved.
The fist step of the project is to understand the architecture of the solution. The diagram below shows the architecture of the solution. When the client registers for your service, they will submit a certificate signing request (CSR) (learn how to create one) then your service will register the client and will issue the first certificate for the client. The client will use that certificate to authenticate to the API Management Service. The API Management Service will validate the certificate and pass the subject name to the backend service for authorization. The backend service will then validate the subject name and authorize the request. If using EZCA, the client will setup the open-source certificate rotation tool to automatically renew the certificate before it expires. Since the API Management Service will use CA validation, there is no need for your service to register the new certificate (that is the great thing of subject based certificate authentication).
To start the implementation, we have to setup a Certificate Authority (CA) that can issue client certificates. You can use any CA; however, we recommend using EZCA which is a cloud-based CA that supports automatic certificate rotation with an open-source certificate rotation tool for your customers, and easy API integration to create the user’s first certificate. It is fully managed and you don’t have to worry about the maintenance of the CA. Check out this video on how to create a certificate authority in Azure.
Now that we have created the CA, we need to add the CA certificate to the API Management Service. To do this, we need to download the CA certificate from the CA. In EZCA, you can download the CA certificate from the CA details page. Once you have the CA certificate, you can upload it to the API Management Service. To do this, go to the API Management Service and click on the “Certificates” menu, in the certificates page, ensure you are in the CA Certificates tab, then click on “Add” and upload the Root CA certificate, and your Issuing CA Certificate. Learn more about root vs issuing CA here.
The last step is to setup the inbound policy to validate the client certificate. To do this, go to the API Management Service and click on the “APIs” menu, then click on the API you want to enable client certificate authentication, and in the inbound processing section, click on “Add policy” and select “Other policies”.
In the policy editor, add the following policy:
<inbound>
<base />
<validate-client-certificate
validate-revocation="true"
validate-trust="true"
validate-not-before="true"
validate-not-after="true"
ignore-error="false" />
<!-- Setting the client certificate subject as a header -->
<set-header name="X-Client-Cert-Subject" exists-action="override">
<value>@(context.Request.Certificate.Subject)</value>
</set-header>
</inbound>
This policy will validate that the certificate is issued by one of your approved CAs (and it has not been revoked), and will pass the subject name to the backend service as a ‘X-Client-Cert-Subject’ header. To learn more about the validate-client-certificate policy, you can read this Microsoft Documentation. Now your service can validate the subject name and authorize the request.
