Application authentication with certificate

Introduction

API Gateway provides capabilities to secure exposed API and control traffic.

API Connect provides different means in term of securing API consumption which includes the consumer application authentication.

At its basic, application authentication is made using the ClientId, but more secured authentication is supported by the solution such as ClientId/ClientSecret, ClientId/Certificate, ClientId/ClientSecret + Certificate.

API Connect generates by default the application ClientId and ClientSecret when the application is registered to API Connect.

API Connect provides also the possibility to define your own ClientID/Secret.

When authentication with certificate needs to be set, the certificate has to be provided with the application registration. The application registration can be made through the developer portal or using the REST API provided by the API Connect manager node.

This post focus on the application authentication using certificate.

This feature allows to define for a specific exposed API that the application needs to present the registered certificate in order to be able to consume this API.

Client Certificate propagation

API Connect provides two ways to propagate client certificate for an application authentication: using Header or Mutual TLS.

Certificate in HTTP header

When using Header, the application needs to provide its X509 client certificate in the “x-client-certificate” HTTP header.

You have the option to hide this information in the developer portal. This is an developer admin task described here: hiding certificate header.

A common use case for this configuration is when the TLS termination is made on a LB in front of the API Gateway. The LB can then propagate the client certificate in the HTTP Header to allow the gateway to authenticate the application. The authentication is made by comparing the provided certificate with the one registered. There is no certificate validation (validation is performed when mutualTLS is used).

Certificate with Mutual TLS

The other option is to use mutual TLS which enforces the client application to provide it’s certificate. The API Gateway extract the Client TLS certificate from the TLS connection and the API Gateway service will use it to authenticate the application for exposed APIs that has been configured for Application Certificate authentication.

The mutual TLS authentication is configured on the API Gateway endpoint and therefore affects all application connecting to this service gateway endpoint.
API Connect provides the option to configure the mutual TLS with either require or request the client certificate Creating a TLS Server Profile.

• When request is set, if the application provides its certificate the API Gateway will verify it using its truststore (see further to find out how to configure the truststore). If the application doesn’t provide a certificate, no validation occurs and the processing of the API request continue.
• When require is selected, if the application doesn’t provide a certificate, the TLS connection is rejected.

A typical use case for the request option is when not all the exposed API on the Gateway needs to have an application certificate authentication. However it doesn’t enforce at the connection the certificate requirement. The application is still rejected afterwards if the called API requires an application authentication with a certificate.

Configuration

API Definition

Detailed information can be found on the APIC knowledge center.

The application authentication based on a certificate for a specific API is configured in the API definition under the Gateway section. The following code show the API definition properties that needs to be defined:

x-ibm-configuration:
  application-authentication-source:
    - tls-cert
  application-authentication:
    certificate: true

application-authentication-source can be either tls-cert or header.

Note that the Developer Portal provides the ability to register an application with a certificate authentication only if there is at least one API definition with the certificate authentication published on the Portal. The certificate is provided in Base64 Encoded.

There are two ways

If you decide to use the GW to terminate the TLS connection you can configure it for mutual authentication where it will be able to get the application certificate and will make it available on the API Gateway. You can then use the certificate to authenticate and identify the application if it has been configured with TLS authentication on the developer portal. The caveat of this approach is that all API exposed to this API Gateway will be secured with mutual TLS even those that are not using TLS for authentication.

Another approach is to provide the TLS certificate in the HTTP header to authenticate and identify the application. A typical use case is when you have a LB that terminates the TLS, the application is authenticated by the LB. Then the LB can put the certificate in the header and this certificate will be used by API Connect just like the client secret to authenticate the application. With this approach you can still have other application calling other APIs without mutual TLS.

Gateway

When using mutual TLS, the application certificate needs to be loaded in the gateway TrustStore.

This configuration is done on the TLS Service profile used to configure the Gateway. The TLS Profile defines:

• The mutual authentication level (none, request, require)
• Keystore
• TrustStore where the application certificates should be placed or an intermediate certificate or the root CA

The update of the TLS Server profile with the TrustStore and mutual authentication level can be done using the API Connect cloud manager UI and the update are reflected directly to the gateway.

It is also possible to use a REST API.