Add client certificate auth page

docs/src/main/sphinx/installation/cli.rst

@@ -59,7 +59,7 @@ Use ``--help`` to see information about specifying the keystore, truststore, and
 other authentication details as required. If using Kerberos, see :doc:`/security/cli`.
 
 External authentication - SSO
------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The ``--external-authentication`` option is used for browser-based SSO
 authentication, as detailed in :doc:`/security/oauth2`. With this configuration,
@@ -77,9 +77,37 @@ The detailed behavior is as follows:
   the query.
 * Further queries in the CLI session do not require additional logins while the
   authentication token remains valid. Token expiration depends on the external
-  authentication system configuration.
+  authentication type configuration.
 * Expired tokens force you to log in again.
 
+.. _cli-certificate-auth:
+
+Certificate authentication
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use the following CLI command line arguments to connect to a cluster that uses
+:doc:`certificate authentication </security/certificate>`.
+
+.. list-table:: CLI options for ertificate authentication
+   :widths: 35 65
+   :header-rows: 1
+
+   * - Option
+     - Description
+   * - ``--keystore-path=<path>``
+     - Absolute or relative path to a :doc:`PEM </security/inspect-pem>` or
+       :doc:`JKS </security/inspect-jks>` file, which must contain a certificate
+       that is trusted by the Trino cluster you are connecting to.
+   * - ``--keystore-password=<password>``
+     - Only required if the keystore has a password.
+   * - ``--keystore-type=<type>``
+     - Rarely used. Specifies the value of the keystore.type property, or ``jks``
+       if not specified. See the ``java.security`` file in your JDK
+       installation's ``lib/security`` or ``conf/security`` directory.
+
+The three ``--truststore`` related options are not used for client certificate
+authentication with the CLI.
+
 Pagination
 ----------
 

docs/src/main/sphinx/installation/jdbc.rst

@@ -110,6 +110,8 @@ These methods may be mixed; some parameters may be specified in the URL,
 while others are specified using properties. However, the same parameter
 may not be specified using both methods.
 
+.. _jdbc-parameter-reference:
+
 Parameter reference
 -------------------
 
@@ -132,17 +134,20 @@ Name                                                         Description
                                                              property nor ``ApplicationName`` or ``source`` are set, the source
                                                              name for the query is ``trino-jdbc``.
 ``accessToken``                                              Access token for token based authentication.
-``SSL``                                                      Use HTTPS for connections
-``SSLVerification``                                          The method of SSL verification. There are three modes: ``FULL``
+``SSL``                                                      Use HTTPS/TLS for connections
+``SSLVerification``                                          The method of TLS verification. There are three modes: ``FULL``
                                                              (default), ``CA`` and ``NONE``. For ``FULL``, the normal TLS
                                                              verification is performed. For ``CA``, only the CA is verified but
                                                              hostname mismatch is allowed. For ``NONE``, there is no verification.
-``SSLKeyStorePath``                                          The location of the Java KeyStore file that contains the certificate
-                                                             and private key to use for authentication.
-``SSLKeyStorePassword``                                      The password for the KeyStore.
+``SSLKeyStorePath``                                          Use only when connecting to a Trino cluster that has :doc:`certificate
+                                                             authentication </security/certificate>` enabled.
+                                                             Specifies the path to a :doc:`PEM </security/inspect-pem>` or :doc:`JKS
+                                                             </security/inspect-jks>` file, which must contain a certificate that
+                                                             is trusted by the Trino cluster you connect to.
+``SSLKeyStorePassword``                                      The password for the KeyStore, if any.
 ``SSLKeyStoreType``                                          The type of the KeyStore. The default type is provided by the Java
                                                              ``keystore.type`` security property or ``jks`` if none exists.
-``SSLTrustStorePath``                                        The location of the Java TrustStore file to use.
+``SSLTrustStorePath``                                        The location of the Java TrustStore file to use
                                                              to validate HTTPS server certificates.
 ``SSLTrustStorePassword``                                    The password for the TrustStore.
 ``SSLTrustStoreType``                                        The type of the TrustStore. The default type is provided by the Java

docs/src/main/sphinx/security.rst

@@ -33,6 +33,7 @@ Authentication
   security/oauth2
   security/kerberos
   security/cli
+  security/certificate
 
 User name management
 ====================

docs/src/main/sphinx/security/authentication-types.rst

@@ -12,7 +12,7 @@ and authenticators are available:
 
 * ``PASSSWORD`` for  :doc:`password-file`, :doc:`ldap`, and :doc:`salesforce`
 * ``OAUTH2`` for :doc:`oauth2`
-* ``CERTIFICATE`` for certificate authentication
+* ``CERTIFICATE`` for :doc:`certificate`
 * ``JWT`` for Java Web Token (JWT) authentication
 * ``KERBEROS`` for :doc:`kerberos`
 

docs/src/main/sphinx/security/certificate.rst

@@ -0,0 +1,107 @@
+==========================
+Certificate authentication
+==========================
+
+You can configure Trino to support client-provided certificates validated by the
+Trino server on initial connection.
+
+.. important::
+
+    This authentication method is only provided to support sites that have an
+    absolute requirement for client authentication *and already have* client
+    certificates for each client. Sites in this category have an existing PKI
+    infrastructure, possibly including an onsite Certificate Authority (CA).
+
+    This feature is not appropriate for sites that need to generate a set of
+    client certificates in order to use this authentication type. Consider
+    instead using another :ref:`authentication type <cl-access-auth>`.
+
+Using certificate authentication
+--------------------------------
+
+All clients connecting with HTTPS/TLS go through the following initial steps:
+
+1. The client attempts to contact the coordinator.
+2. The coordinator returns its certificate to the client.
+3. The client validates the server's certificate using the client's trust store.
+
+A cluster with certificate authentication enabled goes through the following
+additional steps:
+
+4. The coordinator asks the client for its certificate.
+5. The client responds with its certificate.
+6. The coordinator verifies the client's certificate, using the coordinator's
+   trust store.
+
+Several rules emerge from these steps:
+
+* Trust stores used by clients must include the certificate of the signer of
+  the coordinator's certificate.
+* Trust stores used by coordinators must include the certificate of the signer
+  of client certificates.
+* The trust stores used by the coordinator and clients do not need to be the
+  same.
+* The certificate that verifies the coordinator does not need to be the same as
+  the certificate verifying clients.
+
+Trino validates certificates based on the distinguished name (DN) from the
+X.509 ``Subject`` field. The principal created for the connection is the common
+name (CN) from the ``Subject`` field. You can use :doc:`user mapping
+</security/user-mapping>` to map the CN to a Trino user name.
+
+There are three levels of client certificate support possible. From the point of
+view of the server:
+
+* The server does not require a certificate from clients.
+* The server asks for a certificate from clients, but allows connection without one.
+* The server must have a certificate from clients to allow connection.
+
+Trino's client certificate support is the middle type. It asks for a certificate
+but allows connection if another authentication method passes.
+
+Certificate authentication configuration
+----------------------------------------
+
+Enable certificate authentication by setting the :doc:`Certificate
+authentication type <authentication-types>` in :ref:`etc/config.properties
+<config_properties>`:
+
+.. code-block:: properties
+
+    http-server.authentication.type=CERTIFICATE
+
+You can specify certificate authentication along with another authenticaton
+method, such as ``PASSWORD``. In this case, authentication is performed in the
+order of entries, and the first successful authentication results in access.
+
+.. code-block:: properties
+
+    http-server.authentication.type=CERTIFICATE,PASSWORD
+
+The following configuration properties are also available:
+
+.. list-table:: Configuration properties
+   :widths: 50 50
+   :header-rows: 1
+
+   * - Property name
+     - Description
+   * - ``http-server.authentication.certificate.user-mapping.pattern``
+     -  A regular expression pattern to :doc:`map all user names
+        </security/user-mapping>` for this authentication type to the format
+        expected by Trino.
+   * - ``http-server.authentication.certificate.user-mapping.file``
+     - The path to a JSON file that contains a set of :doc:`user mapping
+       rules </security/user-mapping>` for this authentication type.
+
+Use certificate authencation with clients
+-----------------------------------------
+
+When using the Trino :doc:`CLI </installation/cli>`, specify the
+``--keystore-path`` and ``--keystore-password`` options as described
+in :ref:`cli-certificate-auth`.
+
+When using the Trino :doc:`JDBC driver </installation/jdbc>` to connect to a
+cluster with certificate authentication enabled, use the ``SSLKeyStoreType`` and
+``SSLKeyStorePassword`` :ref:`parameters <jdbc-parameter-reference>` to specify
+the path to the client's certificate and its password, if any.

docs/src/main/sphinx/security/overview.rst

@@ -85,8 +85,10 @@ provider.
 
 * :doc:`Password file authentication <password-file>`
 * :doc:`LDAP authentication <ldap>`
-* :doc:`OAuth 2.0 authentication <oauth2>`
 * :doc:`Salesforce authentication <salesforce>`
+* :doc:`OAuth 2.0 authentication <oauth2>`
+* :doc:`Certificate authentication <certificate>`
+* Java Web Token (JWT) authentication
 * :doc:`Kerberos authentication <kerberos>`
 
 .. _user-name-management: