diff --git a/docs/src/main/sphinx/installation/cli.rst b/docs/src/main/sphinx/installation/cli.rst index 5642d487b47f..9a884d16cdcd 100644 --- a/docs/src/main/sphinx/installation/cli.rst +++ b/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,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 command line arguments to connect to a cluster that uses +:doc:`certificate authentication `. + +.. list-table:: CLI options for certificate authentication + :widths: 35 65 + :header-rows: 1 + + * - Option + - Description + * - ``--keystore-path=`` + - Absolute or relative path to a :doc:`PEM ` or + :doc:`JKS ` file, which must contain a certificate + that is trusted by the Trino cluster you are connecting to. + * - ``--keystore-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. + Pagination ---------- diff --git a/docs/src/main/sphinx/installation/jdbc.rst b/docs/src/main/sphinx/installation/jdbc.rst index b3dac22dbb88..3d9002efa5a9 100644 --- a/docs/src/main/sphinx/installation/jdbc.rst +++ b/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 ` enabled. + Specifies the path to a :doc:`PEM ` or :doc:`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 diff --git a/docs/src/main/sphinx/security.rst b/docs/src/main/sphinx/security.rst index ea79e436158c..df6ef551d228 100644 --- a/docs/src/main/sphinx/security.rst +++ b/docs/src/main/sphinx/security.rst @@ -33,6 +33,7 @@ Authentication security/oauth2 security/kerberos security/cli + security/certificate User name management ==================== diff --git a/docs/src/main/sphinx/security/authentication-types.rst b/docs/src/main/sphinx/security/authentication-types.rst index fb8e1c7eb118..659a4cbf6c7b 100644 --- a/docs/src/main/sphinx/security/authentication-types.rst +++ b/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` diff --git a/docs/src/main/sphinx/security/certificate.rst b/docs/src/main/sphinx/security/certificate.rst new file mode 100644 index 000000000000..720bb73427e7 --- /dev/null +++ b/docs/src/main/sphinx/security/certificate.rst @@ -0,0 +1,108 @@ +========================== +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 `. + +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 +` 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 ` in :ref:`etc/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 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 + ` 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 ` for this authentication type. + +Use certificate authencation with clients +----------------------------------------- + +When using the Trino :doc:`CLI `, specify the +``--keystore-path`` and ``--keystore-password`` options as described +in :ref:`cli-certificate-auth`. + +When using the Trino :doc:`JDBC driver ` to connect to a +cluster with certificate authentication enabled, use the ``SSLKeyStoreType`` and +``SSLKeyStorePassword`` :ref:`parameters ` to specify +the path to the client's certificate and its password, if any. diff --git a/docs/src/main/sphinx/security/overview.rst b/docs/src/main/sphinx/security/overview.rst index 7acdf7cb2a85..7c6fa1255a39 100644 --- a/docs/src/main/sphinx/security/overview.rst +++ b/docs/src/main/sphinx/security/overview.rst @@ -85,8 +85,10 @@ provider. * :doc:`Password file authentication ` * :doc:`LDAP authentication ` -* :doc:`OAuth 2.0 authentication ` * :doc:`Salesforce authentication ` +* :doc:`OAuth 2.0 authentication ` +* :doc:`Certificate authentication ` +* Java Web Token (JWT) authentication * :doc:`Kerberos authentication ` .. _user-name-management: