Web service authentication using client certificates

Airlock IAM and Airlock Gateway (WAF) can be used to authenticate web service requests using client certificates.

Note that this feature has been deprecated and will be removed. See Features discontinued with the JSP-Loginapp.

To authenticate web service requests with client certificates, use the one-shote feature described in HTTP request authentication (Airlock One-Shot flow).

The roles of Gateway (WAF) and IAM are as follows:

  • Airlock Gateway (WAF):
    • Checks the client certificate's validity and makes sure the issuer is trusted (i.e. signed by a trusted CA).
    • Sends a request to Airlock IAM with the client certificate (using "one-shot" authentication).
  • Airlock IAM:
    • Makes sure, the client certificate is known, i.e. the subject in the certificate is known. 
    • Decides what roles are issued to Airlock in order to authenticate the request.

Airlock Gateway (WAF) configuration

  • On the mapping protecting the web service, choose the following settings:
    • Set "Authentication flow" to "One-Shot"
    • Restrict access providing a role (e.g. wsaccess)
    • Configure a custom denied access URL to point to the Airlock IAM URI /ws-auth (e.g. /auth/ws-auth). There must be a mapping for Airlock IAM.
    • Either in the mapping or in the virtual host settings: require an SSL client certificate
  • In the Airlock IAM mapping, choose the following settings:
    • Make sure to activate the allow rule AuthWebserviceCertAuthorization
    • If the Airlock IAM mapping is only used to authenticate web service requests, all other allow rules should be deactivated.


IAM configuration

  • In Airlock IAM enable the Webservices Cert Auth in Loginapp >> Authentication Settings.
  • A list of access rules may be defined. Each access rule contains the following properties:
    • A pattern matched against the subject DN (distinguished name) of the client certificate.
    • A pattern matched against the issuer DN (distinguished name) of the client certificate.
    • A list of roles granted to Airlock in case both patterns match. Usually one role is required (e.g. wsaccess:5, see hint below)
    • An audit token (optional): it is written to log statements in Airlock concerning the same session. It may help to find information in the log.
  • Make sure, Airlock Gateway (WAF) settings are configured (environment header prefix, control cookie name).

Configuration of Granted Roles

Web service clients usually don't send back the session cookie issued by Airlock Gateway (WAF). Thus, every request results in a new Airlock Gateway (WAF) session.
In order to keep the number of unused sessions low, a small timeout should be used for the roles granted for web service request authentication.
This may be achieved as in the following example role: wsaccess:5. This role will timeout after five seconds.

If using Airlock IAM for both authenticating web service requests and users for web applications: make sure that the web service mapping and web application mappings require distinct roles on the Airlock mappings.

This is for security: If sharing roles on Airlock Gateway (WAF) mappings, a client may get unwanted access to a web application by connecting with a client certificate meant for the web service mapping.