JWT authentication#

Starburst Enterprise platform (SEP) 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

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 SEP, as described in OAuth 2.0 authentication. 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 SEP coordinator, where their new system submits queries on behalf of users.

Using TLS and a configured shared secret is required for JWT authentication.

Using JWT authentication#

SEP 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 SEP 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 JWT authentication type in etc/config.properties, and specifying a URL or path to a key file:

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:

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:

Configuration properties for JWT authentication#

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 SEP principal.

http-server.authentication.jwt.user-mapping.pattern

A regular expression pattern to map all user names for this authentication system to the format expected by the SEP server.

http-server.authentication.jwt.user-mapping.file

The path to a JSON file that contains a set of 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 SEP 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 PEM or HMAC format that contains a single key. If the file path contains $KEYID, then SEP 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#

You can enable a client token authentication page in the Starburst Enterprise web UI that exposes a JWT for use with any clients that support JWT authentication. To enable this page, set the following configuration property to true in the coordinator’s config.properties file:

web-ui.token-copy.enabled=true

When using the Trino CLI, specify a JWT as described in JWT authentication.

When using the SEP JDBC driver, specify a JWT with the accessToken parameter.

JWT pass-through#

The JSON Web Token (JWT) pass-through feature guarantees that SEP uses the same token as a user accessing a data source directly. This feature allows you to authenticate to SEP using JWT and the received token is passed through SEP and the connector to the underlying data source.

Requirements#

A user authenticated with a JWT compatible server must be able to query SEP, and SEP accesses the data from the data source with the token authenticated as the user.

Note

The JWT pass-through feature is only supported in select connectors. Reference the connectors feature matrix for more information about which connectors support this feature.

Configure JWT pass-through#

To enable JWT pass-through in SEP:

  1. Set the following configuration properties in the config.properties file on the coordinator:

http-server.authentication.type=DELEGATED-JWT
web-ui.authentication.type=DELEGATED-JWT

  1. Set connector-specific properties in the connector catalog properties file. For connector-specific properties, see the connector documentation.

This method otherwise has the same configuration properties and works exactly the same as the JWT authentication configuration method.

The only difference is that the server passes the access token received with a query to other supported connectors in the connector session. As a result, compatible connectors can use the same token to authenticate with downstream data sources.

Resources#

The following resources may prove useful in your work with JWTs and JWKs.