Tab – Client Certificates

If client certificate authentication is activated and if authentication is successful, Airlock Gateway will provide the following additional cookies to the back-end that contain all information about the authenticated client certificate:

Example

AL_ENV_SSL_CLIENT_S_DN:            Distinguished name of the subject
AL_ENV_SSL_CLIENT_I_DN:            Distinguished name of the issuer
AL_ENV_SSL_CLIENT_M_VERSION:       The version of the certificate
AL_ENV_SSL_CLIENT_M_SERIAL:        Serial number of the certificate
AL_ENV_SSL_CLIENT_V_START:         Validity start time of certificate
AL_ENV_SSL_CLIENT_V_END:           Validity end time of certificate
AL_ENV_SSL_CLIENT_CERT:            Complete X509 certificate (PEM format)

Section - Certificate Verification Settings

SSL client certificate

Specifies whether accessing this virtual host requires the client to authenticate with a valid SSL client certificate. Together with the SSL server certificate, the client certificates provide mutual authentication (mTLS) between Airlock Gateway and the client. If the client authenticates himself with a client certificate, any man-in-the-middle attack is prevented.

Setting	Description
Not needed	No certificate is requested from the client. The virtual host may be accessed without a client certificate.
Optional	The client may send a certificate if available, but access is still allowed without a certificate. The optional setting is normally used in combination with an authentication service that presents an alternative login page if no certificate is sent. You should not use the 'optional' setting without this additional authentication service check.
Required	The client must send a valid certificate before accessing any of the connected mappings. If no client certificate is sent, the SSL handshake is canceled and the browser typically presents the user with a technical error message.

Notice

SSL client certificate settings are also available for each mapping. If you need to check client certificates, it is recommended to require a client certificate on the virtual host level, not on the mapping level.

If client certificates are required on the virtual host, set the SSL client-certificate configuration on connected mappings to inherit from virtual host.

GUI	Description
Chain verification depth	This parameter specifies the maximum number of issuing certificates from the client's issuer up to and including the trusted root (trust anchor). Shorter chains are allowed. 0 — only self-signed client certificates are accepted. 1 — the client certificate must be issued directly by the root CA. 2 — one intermediate CA may exist between the client and the root. 3 — two intermediate CA may exist between the client and the root. … — and so on for larger values. Notice Increasing the chain verification depth allows path building to accept additional intermediate CAs that are not preconfigured on the server (e.g., supplied by the client). If these intermediates chain to a trusted root, they will be accepted — which widens the effective trust scope and may make your deployment less secure. To avoid such an unintended expansion of the trust scope, set the chain verification depth to the lowest value that fits your public key infrastructure.
Enable OCSP validation	This option enables OCSP validation of the client certificate chain. For more information see the official Apache documentation of the SSLOCSPEnable directive. OCSP servers must be added to the list of allowed network endpoints since Airlock Gateway firewall rules refuse connections to arbitrary hosts on the internet.

GUI

Description

Chain verification depth

This parameter specifies the maximum number of issuing certificates from the client's issuer up to and including the trusted root (trust anchor). Shorter chains are allowed.

0 — only self-signed client certificates are accepted.
1 — the client certificate must be issued directly by the root CA.
2 — one intermediate CA may exist between the client and the root.
3 — two intermediate CA may exist between the client and the root.
… — and so on for larger values.

Notice

Increasing the chain verification depth allows path building to accept additional intermediate CAs that are not preconfigured on the server (e.g., supplied by the client). If these intermediates chain to a trusted root, they will be accepted — which widens the effective trust scope and may make your deployment less secure.

To avoid such an unintended expansion of the trust scope, set the chain verification depth to the lowest value that fits your public key infrastructure.

Enable OCSP validation

This option enables OCSP validation of the client certificate chain. For more information see the official Apache documentation of the SSLOCSPEnable directive.

OCSP servers must be added to the list of allowed network endpoints since Airlock Gateway firewall rules refuse connections to arbitrary hosts on the internet.

Section - Certificate Authority

GUI	Description
CAs for client certificate selection	Into this field, you can insert CAs that shall be used to restrict the selection of client certificates presented by the browser, ensuring that only certificates issued by one of the specified CAs are offered to the user in the browser’s certificate selection dialog. For more information, refer to the official Apache documentation of the SSLCADNRequestFile directive. Functional limitation The CA certificates configured in this field must be in PEM format.
CAs for chain validation and OCSP server validation	Into this field, you can insert CAs that shall be used for client certificate validation. The certificates are merged with those specified in the CAs for client certificate selection field. Note that the complete certificate chain up to the root certificate must be configured here because partial chain validation is insufficient. You can leave the field empty unless specific CA certificates are intended to be used for validation but not for client certificate selection. For more information, refer to the official Apache documentation of the SSLCACertificateFile directive. Notice To enforce stricter authentication or implement certificate pinning, consider using the Require expr directive with attributes such as the certificate’s subject, issuer, or serial number. By allowing only client certificates issued by certain intermediate CAs under a trusted root certificate (e.g., `Require expr “%{SSL_CLIENT_I_DN} eq 'CN=SubCA,O=Org,C=CH'”`), you can prevent unintended chains. This mechanism is particularly recommended when the verification depth permits intermediates (`≥2`), since intermediates can also be sent by the client and form new unintended chains that still anchor to a trusted root. Also note that Airlock Gateway does not cache intermediate CA certificates for SSL session reuse. Missing intermediate CAs can lead to sporadic handshake or re-negotiation failures. Ensure that all intermediate CAs relevant to client authentication are configured on the corresponding virtual host. For detailed background, see the official Apache documentation of the SSLVerifyDepth directive.

GUI

Description

CAs for client certificate selection

Into this field, you can insert CAs that shall be used to restrict the selection of client certificates presented by the browser, ensuring that only certificates issued by one of the specified CAs are offered to the user in the browser’s certificate selection dialog.

For more information, refer to the official Apache documentation of the SSLCADNRequestFile directive.

Functional limitation

The CA certificates configured in this field must be in PEM format.

CAs for chain validation and OCSP server validation

Into this field, you can insert CAs that shall be used for client certificate validation. The certificates are merged with those specified in the CAs for client certificate selection field. Note that the complete certificate chain up to the root certificate must be configured here because partial chain validation is insufficient. You can leave the field empty unless specific CA certificates are intended to be used for validation but not for client certificate selection.

For more information, refer to the official Apache documentation of the SSLCACertificateFile directive.

Notice

To enforce stricter authentication or implement certificate pinning, consider using the Require expr directive with attributes such as the certificate’s subject, issuer, or serial number. By allowing only client certificates issued by certain intermediate CAs under a trusted root certificate (e.g., Require expr “%{SSL_CLIENT_I_DN} eq 'CN=SubCA,O=Org,C=CH'”), you can prevent unintended chains. This mechanism is particularly recommended when the verification depth permits intermediates (≥2), since intermediates can also be sent by the client and form new unintended chains that still anchor to a trusted root.
Also note that Airlock Gateway does not cache intermediate CA certificates for SSL session reuse. Missing intermediate CAs can lead to sporadic handshake or re-negotiation failures. Ensure that all intermediate CAs relevant to client authentication are configured on the corresponding virtual host.
For detailed background, see the official Apache documentation of the SSLVerifyDepth directive.

Section - Certificate Revocation List

Airlock Gateway provides the possibility to upload the PEM representation of certificate revocation lists. Use the upload, download, and delete buttons to modify the certificate revocation list (CRL). After that, confirm the settings on the page and activate the new configuration as usual for the changes to take effect. If a client certificate is on such a list, it will not be accepted, the connection will fail, and a technical error message will be will be returned by the client. If additional certificate checks are required, it is advisable to perform them with Airlock IAM and configure the client certificate as optional, as described above.

Notice

If the configured CRL file does not contain all CRLs for the certificates configured in CAs for client certificate selection and CAs for chain validation and OCSP server validation, which are combined for certificate verification, add the following setting in the Apache section of the virtual host’s Expert Settings tab:

SSLCARevocationCheck leaf

For background information, see the official Apache documentation for the SSLCARevocationCheck directive.

Automatic update of CRLs

Airlock Gateway allows you to periodically update your certificate revocation lists (CRL). For more information, read this Techzone Article.

Hint

Typically, only the authentication service will interpret the certificate information, map it to a registered user profile, and issue the appropriate credentials to the current user's session. A commonly used technique is to configure one dedicated URL to require an SSL certificate. This URL is mapped to the authentication service which will get the certificate information and interpret it. To initiate the certificate authentication process on the client side, a public login page just needs to point a web link to that special URL. As soon as the user clicks this link, the user's browser will initiate the client certificate authentication process with Airlock Gateway. The authentication service will get the certificate information just like any other authentication information if the authentication step is successful.

Further information and links

Internal links:

External links: