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:
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. |
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.
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.
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. Where possible, explicitly configure the intended issuing intermediates rather than relying on client-supplied chains.
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
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.
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.
- 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. This approach can also be used to restrict authentication to specific subtrees of the trust hierarchy, for example 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'”). - 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
Certificate revocation list (CRL)
Airlock Gateway provides the possibility to upload the PEM representation of certificate revocation lists. If a client certificate is on such a list, it will not be accepted and the connection will fail. Although Airlock provides this functionality, it is recommended to check certificates against CRLs and other types of denylists within the authentication service and not in Airlock.
For example, if the client certificate is blocked on Airlock Gateway using the CRL, the corresponding SSL handshake will fail and the user will not be able to connect to the authentication service. Typically, it is better to let technically valid certificates connect to the authentication service and verify the content of the certificate there. That is also true for certificate validity, expiry etc. It does not mean that anybody can connect to the authentication service since the user first needs a technically valid certificate. Use the upload, download, and delete buttons to modify the CRL parameter. After that, confirm the settings on the page and activate the new configuration as usual for the changes to take effect.
Automatic update of CRLs
Airlock Gateway allows you to periodically update your certificate revocation lists (CRL). For more information please read this Techzone Article.
Hints
- 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.
- Airlock Gateway services of a virtual host can be temporarily disabled by checking the maintenance page option.
Further information and links
External links: