From 52f5e7dd01dffaf1ee5b73e703b2898be3511afa Mon Sep 17 00:00:00 2001 From: Barton Wright Date: Wed, 26 May 2021 12:21:32 -0400 Subject: [PATCH] Add page for JWT authentication --- docs/src/main/sphinx/installation/cli.rst | 19 ++- docs/src/main/sphinx/installation/jdbc.rst | 6 +- docs/src/main/sphinx/security.rst | 3 +- .../sphinx/security/authentication-types.rst | 11 +- docs/src/main/sphinx/security/jwt.rst | 141 ++++++++++++++++++ 5 files changed, 169 insertions(+), 11 deletions(-) create mode 100644 docs/src/main/sphinx/security/jwt.rst diff --git a/docs/src/main/sphinx/installation/cli.rst b/docs/src/main/sphinx/installation/cli.rst index 5642d487b47fb..d17a9aa4a0d73 100644 --- a/docs/src/main/sphinx/installation/cli.rst +++ b/docs/src/main/sphinx/installation/cli.rst @@ -29,7 +29,7 @@ The CLI uses the HTTP protocol and the :doc:`Trino client REST API ` to communicate with Trino. -TLS/HTTPS +HTTPS/TLS --------- Trino is typically available with an HTTPS URL. This means that all network @@ -59,16 +59,17 @@ 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 +Use the ``--external-authentication`` option for browser-based SSO authentication, as detailed in :doc:`/security/oauth2`. With this configuration, the CLI displays a URL that you must open in a web browser for authentication. The detailed behavior is as follows: -* Start the CLI with the ``--external-authentication`` option. -* CLI starts and connects to Trino. +* Start the CLI with the ``--external-authentication`` option and execute a + query. +* The CLI starts and connects to Trino. * A message appears in the CLI directing you to open a browser with a specified URL when the first query is submitted. * Open the URL in a browser and follow through the authentication process. @@ -80,6 +81,14 @@ The detailed behavior is as follows: authentication system configuration. * Expired tokens force you to log in again. +.. _cli-jwt-auth: + +JWT authentication +^^^^^^^^^^^^^^^^^^ + +To access a Trino cluster configured to use :doc:`/security/jwt`, use the +``--access-token=`` option to pass a JWT to the server. + Pagination ---------- diff --git a/docs/src/main/sphinx/installation/jdbc.rst b/docs/src/main/sphinx/installation/jdbc.rst index b3dac22dbb884..613cc304a7e1e 100644 --- a/docs/src/main/sphinx/installation/jdbc.rst +++ b/docs/src/main/sphinx/installation/jdbc.rst @@ -80,7 +80,7 @@ This example JDBC URL locates a Trino instance running on port ``8080`` on ``example.net``, with the catalog ``hive`` and the schema ``sales`` defined. .. note:: - + Typically, the JDBC driver classname is configured automatically by your client. If it is not, use ``io.trino.jdbc.TrinoDriver`` wherever a driver classname is required. @@ -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 ------------------- @@ -131,7 +133,7 @@ Name Description if the ``source`` parameter has not been set. If neither this property nor ``ApplicationName`` or ``source`` are set, the source name for the query is ``trino-jdbc``. -``accessToken`` Access token for token based authentication. +``accessToken`` :doc:`JWT ` access token for token based authentication. ``SSL`` Use HTTPS for connections ``SSLVerification`` The method of SSL verification. There are three modes: ``FULL`` (default), ``CA`` and ``NONE``. For ``FULL``, the normal TLS diff --git a/docs/src/main/sphinx/security.rst b/docs/src/main/sphinx/security.rst index ea79e436158c4..1d315ee569f3d 100644 --- a/docs/src/main/sphinx/security.rst +++ b/docs/src/main/sphinx/security.rst @@ -27,12 +27,13 @@ Authentication :maxdepth: 1 security/authentication-types - security/ldap security/password-file + security/ldap security/salesforce security/oauth2 security/kerberos security/cli + security/jwt User name management ==================== diff --git a/docs/src/main/sphinx/security/authentication-types.rst b/docs/src/main/sphinx/security/authentication-types.rst index fb8e1c7eb1182..d9a232c62b9c4 100644 --- a/docs/src/main/sphinx/security/authentication-types.rst +++ b/docs/src/main/sphinx/security/authentication-types.rst @@ -10,11 +10,16 @@ You can configure one or more authentication types with the ``http-server.authentication.type`` property. The following authentication types and authenticators are available: -* ``PASSSWORD`` for :doc:`password-file`, :doc:`ldap`, and :doc:`salesforce` +* ``PASSWORD`` for + + * :doc:`password-file` + * :doc:`ldap` + * :doc:`salesforce` + * ``OAUTH2`` for :doc:`oauth2` -* ``CERTIFICATE`` for certificate authentication -* ``JWT`` for Java Web Token (JWT) authentication * ``KERBEROS`` for :doc:`kerberos` +* ``JWT`` for :doc:`jwt` +* ``CERTIFICATE`` for certificate authentication Get started with a basic password authentication configuration backed by a :doc:`password file `: diff --git a/docs/src/main/sphinx/security/jwt.rst b/docs/src/main/sphinx/security/jwt.rst new file mode 100644 index 0000000000000..624932051f9ab --- /dev/null +++ b/docs/src/main/sphinx/security/jwt.rst @@ -0,0 +1,141 @@ +================== +JWT authentication +================== + +Trino can be configured to authenticate client access using `JSON web tokens +`_. A JWT is a small, web-safe +JSON file that contains cryptographic information similar to a certificate, +including: + +* Subject +* Valid time period +* Signature + +Sites such as `jwt.io `_ are available to help you decode and verify a +JWT. + +A JWT is designed to be passed between servers as proof of prior authentication +in a workflow like the following: + +1. An end user logs into a client application and requests access to a server. +2. The server sends the user's credentials to a separate authentication service + that: + + * validates the user + * generates a JWT as proof of validation + * returns the JWT to the requesting server + +3. The same JWT can then be forwarded to other services to maintain the user's + validation without further credentials. + +.. important:: + + If you are trying to configure OAuth2 or OIDC, there is a dedicated system + for that in Trino, as described in :doc:`/security/oauth2`. When using + OAuth2 authentication, you do not need to configure JWT authentication, + because JWTs are handled automatically by the OAuth2 code. + + A typical use for JWT authentication is to support administrators at large + sites who are writing their own single sign-on or proxy system to stand + between users and the Trino coordinator, where their new system submits + queries on behalf of users. + +Using JWT authentication +------------------------ + +Trino supports Base64 encoded JWTs, but not encrypted JWTs. + +There are two ways to get the encryption key necessary to validate the JWT +signature: + +- Load the key from a JSON web key set (JWKS) endpoint service (the + typical case) +- Load the key from the local file system on the Trino coordinator + +A JWKS endpoint is a read-only service that contains public key information in +`JWK `_ format. These public +keys are the counterpart of the private keys that sign JSON web tokens. + +JWT authentication configuration +-------------------------------- + +Enable JWT authentication by setting the :doc:`JWT authentication type +` in :ref:`etc/config.properties `, and +specifying a URL or path to a key file: + +.. code-block:: properties + + http-server.authentication.type=JWT + http-server.authentication.jwt.key-file=https://cluster.example.net/.well-known/jwks.json + +JWT authentication is typically used in addition to other authentication +methods: + +.. code-block:: properties + + http-server.authentication.type=PASSWORD,JWT + http-server.authentication.jwt.key-file=https://cluster.example.net/.well-known/jwks.json + +The following configuration properties are available: + +.. list-table:: Configuration properties for JWT authentication + :widths: 50 50 + :header-rows: 1 + + * - Property + - Description + * - ``http-server.authentication.jwt.key-file`` + - Required. Specifies either the URL to a JWKS service or the path to a + PEM or HMAC file, as described below this table. + * - ``http-server.authentication.jwt.required-issuer`` + - Specifies a string that must match the value of the JWT's + issuer (``iss``) field in order to consider this JWT valid. + The ``iss`` field in the JWT identifies the principal that issued the + JWT. + * - ``http-server.authentication.jwt.required-audience`` + - Specifies a string that must match the value of the JWT's + Audience (``aud``) field in order to consider this JWT valid. + The ``aud`` field in the JWT identifies the recipients that the + JWT is intended for. + * - ``http-server.authentication.jwt.principal-field`` + - String to identify the field in the JWT that identifies the + subject of the JWT. The default value is ``sub``. This field is used to + create the Trino principal. + * - ``http-server.authentication.jwt.user-mapping.pattern`` + - A regular expression pattern to :doc:`map all user names + ` for this authentication system to the format + expected by the Trino server. + * - ``http-server.authentication.jwt.user-mapping.file`` + - The path to a JSON file that contains a set of + :doc:`user mapping rules ` for this + authentication system. + +Use the ``http-server.authentication.jwt.key-file`` property to specify +either: + +- The URL to a JWKS endpoint service, where the URL begins with ``https://``. + The JWKS service must be reachable from the coordinator. If the coordinator + is running in a secured or firewalled network, the administrator *may* have + to open access to the JWKS server host. + + .. caution:: + + The Trino server also accepts JWKS URLs that begin with ``http://``, but + using this protocol results in a severe security risk. Only use this + protocol for short-term testing during development of your cluster. + +- The path to a local file in :doc:`PEM ` or `HMAC + `_ format that contains a single key. + If the file path contains ``$KEYID``, then Trino interpolates the ``keyid`` + from the JWT into the file path before loading this key. This enables support + for setups with multiple keys. + +Using JWTs with clients +----------------------- + +When using the Trino :doc:`CLI `, specify a JWT as described +in :ref:`cli-jwt-auth`. + +When using the Trino JDBC driver, specify a JWT with the ``accessToken`` +:ref:`parameter `. +