HTTPS/TLS client authentication

In addition to HTTPS/TLS with server certificate, client certificates with client authentication enforces that only the trusted client can send requests to IAM.

  1. Configure HTTPS/TLS with authentication of IAM.
  2. Create a client certificate for clients, e.g. using OpenSSL:
  3.  
    Terminal box
    openssl req -x509 -sha512 -newkey rsa:4096 -keyout iam-client-private-key.pem -out iam-client-certificate.pem -days 365 -nodes
  4.  
    Notice

    For multiple clients, separate certificates can be created. Multiple certificates can be included as part of the trust store in the next step.

  5. Create a trust store for IAM containing the client certificate:
  6.  
    Terminal box
    iam build-trust-store --certs iam-client-certificate.pem --output iam-truststore.p12

# The --certs option can be repeated to include multiple certificates.
  7.  
    Info

    This example uses "iam build-trust-store" instead of "openssl" due to incompatibilities between trust stores in the PKCS #12 format and Java. "iam build-trust-store" will set a special required "bag attribute", but "openssl" will not. Other tools are available, e.g. KeyStore Explorer

    (See also: https://bugs.java.com/bugdatabase/view_bug.do?bug_id=8181737, https://stackoverflow.com/questions/42766935/creating-p12-truststore-with-openssl)

  8. Enable client authentication, through the application parameters in instance.properties:
  9.  
    Example
    # Enable client authentication
iam.web-server.https.client-auth = REQUIRED

# Configure web server trust store
iam.web-server.https.truststore.type = PKCS12
iam.web-server.https.truststore.file = instances/auth/iam-truststore.p12
iam.web-server.https.truststore.password = password
  10.  
    Info

    Caution with using client-auth = REQUIRED

    iam.web-server.https.client-auth = REQUIRED is good security practice, but it affects all modules configured in this instance.properties and makes the use of X.509 client certifiicates mandatory for all modules including the Adminapp and the Service Container.

    To enforce REQUIRED only on the Loginapp, the use of profiles is recommended (see Sandboxing with profiles) allowing a separate configuration of the Loginapp in its own profile.

    Using a more flexible configuration of the iam.web-server.https.client-auth parameter is discouraged for the purpose of securing the connection between Airlock Gateway and IAM. See Authentication of REST API calls with client certificates (X.509) for other use case scenarios.

HTTPS/TLS with mutual authentication between Airlock Gateway and IAM

A special and common case of is mutual authentication between Airlock Gateway and IAM. In this case, Airlock Gateway ist the “client” and IAM is the “server”.

  1. Configure Securing Airlock IAM with HTTPS.
  2. Add the client certificate iam-client-certificate.pem as BackendSSLClientCert and the private key iam-client-private-key.pem as BackendSSLClientCertKey to the IAM backend group on the Airlock Gateway.

Create a trust store for IAM containing the client certificate:

 
Terminal box
iam build-trust-store --certs waf-certificate.pem --output iam-truststore.p12
 
Info

To allow access to Adminapp without possession of the Airlock Gateway client certificate, you must either:

  • Create a separate client certificate and also add it to the trust store when running the build-trust-store command.
  • Run Adminapp in a separate process and disable client authentication for that process, i.e. use Sandboxing with profiles