Add certificate auth doc

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

@@ -29,7 +29,7 @@ The CLI uses the HTTP protocol and the
 :doc:`Trino client REST API </develop/client-protocol>` to communicate
 with Trino.
 
-HTTPS/TLS
+TLS/HTTPS
 ---------
 
 Trino is typically available with an HTTPS URL. This means that all network
@@ -58,6 +58,8 @@ password value to avoid the prompt.
 Use ``--help`` to see information about specifying the keystore, truststore, and
 other authentication details as required. If using Kerberos, see :doc:`/security/cli`.
 
+.. _cli-external-sso-auth:
+
 External authentication - SSO
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -78,9 +80,34 @@ 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 arguments to connect to a cluster that uses
+:doc:`certificate authentication </security/certificate>`.
+
+.. list-table:: CLI options for certificate 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.
+
+The three ``--truststore`` related options are independent of client certificate
+authentication with the CLI; instead, they control the client's trust of the
+server's certificate.
+
 .. _cli-jwt-auth:
 
 JWT authentication

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

@@ -134,14 +134,17 @@ Name                                                         Description
                                                              property nor ``ApplicationName`` or ``source`` are set, the source
                                                              name for the query is ``trino-jdbc``.
 ``accessToken``                                              :doc:`JWT </security/jwt>` access token for token based authentication.
-``SSL``                                                      Use HTTPS for connections
-``SSLVerification``                                          The method of SSL verification. There are three modes: ``FULL``
+``SSL``                                                      Set ``true`` to specify using 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.

docs/src/main/sphinx/security.rst

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

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

@@ -18,8 +18,8 @@ and authenticators are available:
 
 * ``OAUTH2`` for :doc:`oauth2`
 * ``KERBEROS`` for :doc:`kerberos`
+* ``CERTIFICATE`` for :doc:`certificate`
 * ``JWT`` for :doc:`jwt`
-* ``CERTIFICATE`` for certificate authentication
 
 Get started with a basic password authentication configuration backed by a
 :doc:`password file <password-file>`:

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. You can use :doc:`user mapping
+</security/user-mapping>` to map the subject DN 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.
+For example, the following setting shows the use of two authentication types:
+
+.. 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>`
+* :doc:`Java Web Token (JWT) authentication <jwt>`
 * :doc:`Kerberos authentication <kerberos>`
 
 .. _user-name-management:
@@ -98,8 +100,9 @@ Trino provides ways to map the user and group names from authentication
 providers to Trino user names.
 
 * :doc:`User mapping <user-mapping>` applies to all authentication systems,
-  and allows for JSON files to specify rules to map complex user names from
-  other systems (``[email protected]``) to simple user names (``alice``).
+  and allows for regular expression rules to be specified that map complex user
+  names from other systems (``[email protected]``) to simple user names
+  (``alice``).
 * :doc:`File group provider <group-file>` provides a way to assign a set
   of user names to a group name to ease access control.