How To Configure Mutual SSL or Certificate Based Authentication in the Layer7 API Gateway

Article By: Eunice Mushawatu

The most common use-case for Mutual SSL is when there is a need to verify the identity of both a client and the server to establish a secure and encrypted client-server communication tunnel. In the traditional use of SSL i.e. when accessing https resources, only the client verifies the server’s certificate, the server does not verify the client certificate. When using two-way-SSL for an API on the Layer7 API gateway, the client verifies the servers’ certificate and sends its own certificate to be verified by the server. This is an advanced authentication called mutual authentication because both entities have established trust for each other. This guide will detail the setting up of mutual SSL to protect an API resource on the Layer7 API gateway.


  • Have the client certificate ready. This is the certificate that the client will use to access the protected resource. 
  • The API gateway server private key and server certificate is already configured.


Task 1 – Enable Certificate Based Authentication on the Gateway

The first task is to enable certificate-based authentication on the Layer7 API gateway. This is  enabled at the port level under SSL settings. The Layer7 API Gateway has 3 options to either enforce client authentication, to make it optional or to disable client authentication. 

Pro Tip: If you separate the port that regular clients use from the port that certificate-based clients use you may enforce certificate authentication on one port and make it optional on another. If you do this make sure the certificate-based authentication clients know to always use that designated port.  

1. Click on Tasks > Transports > Manage Listen Ports

2. Double click the port that is open to your clients.
3. Click on the SSL/TLS Settings tab.
4. On Server Private Key select the Private Key that your API gateway is using. Typically, that will be the Default SSL Key.
5. On Client Authentication select Required to enable certificate-based authentication.

Task 2 – Create User and Trust Client Certificate

The first task is to import the client certificate into the API gateway Identity Provider, typically this is done as a part of the user onboarding process. When the user is created their username must match exactly the cn on the certificate. If the API gateway is leveraging an external identity provider, the certificate must be uploaded to that identity provider. The method below is for the internal identity provider. 

1. Click on the Identity Providers tab
2. Right Click on the Internal Identity Provider and click Create Internal User

3. Make sure the username is the same as the cn on the certificate

4. Select the define additional properties checkbox and click Create
5. Go the certificate tab and click Import

6. Import the client certificate and then click OK.

Task 3 – Build Mutual SSL Policy

1. Publish the API as usual and open the policy window
2. Drag and drop the ‘Require SSL or TLS Transport with Client Authentication’ assertion.
3. Double click the assertion and make sure to select Required for ‘SSL or TLS requirements.’
4. Also check the ‘Require Client Certificate Authentication’ checkbox.

5. Drag and drop the Authenticate against Internal Identity Provider assertion into the policy.


You have successfully configured the API gateway to protect the API with mutual SSL. Looking for additional help with the CA API gateway? ISX Consulting is an elite IAM security firm that offers boundless expertise in a range of cybersecurity and business process services, including mutual and advanced authentication. Take your interoperability to the next level, and contact an ISX consultant today.

(Do Not Print) Tags for SEO: mutual SSL, certificate-based authentication, mutual authentication, two-way-SSL, Layer7 API gateway, CA API gateway, Layer7 Policy Manager

ISXHow To Configure Mutual SSL or Certificate Based Authentication in the Layer7 API Gateway

Related Posts

Leave a Reply

Your email address will not be published.