Authentication of REST API calls with client certificates (X.509)

This guide explains how to authenticate REST clients using X.509 client certificates by enforcing mutual authentication in the TLS handshake followed by extracting and validating the client certificate.


To configure client-certificate authentication, follow the instructions below.

  • The configuration entry points are:
  • Loginapp REST API: Loginapp >> Session-less REST Endpoints >> Request Authentication
  • Adminapp REST API: Adminapp >> REST API Configuration >> Request Authentication
  • Transaction Approval >> Request Authentication
  1. Go to the corresponding configuration entry point in the Config Editor (see above).
  2. For property Request Authentication, choose the plugin Client Certificate (X.509) Request Authentication
  3. Configure the desired certificate validation settings (validity period and certificate status checks).
  4. In property User Attribute, choose what part of the client certificates subject to use as the REST client's user ID. The Username Transformation property allows to transform the username if required.
  5. If the REST API to be protected is accessed via Airlock Gateway, the Airlock Gateway (WAF) Settings of the corresponding module (Loginapp, Adminapp, Transaction Approval) must be configured. This tells IAM how to extract the client certificate from the request.
  6. A valid client certificate is now required to access the corresponding REST API.
  7. To restrict access to specific client certificates, i.e., specific subjects, configure the User Store used to look up the REST client (or user) with the extracted user attribute. A REST client (or user) must be valid, unlocked and - where applicable - have the required roles.