OAuth 2.0 authentication#

Starburst Enterprise platform (SEP) can be configured to enable OAuth 2.0 authentication over HTTPS for the Web UI and the JDBC driver. SEP uses the Authorization Code flow which exchanges an Authorization Code for a token. At a high level, the flow includes the following steps:

  1. the SEP coordinator redirects a user’s browser to the Authorization Server

  2. the user authenticates with the Authorization Server, and it approves the SEP’s permissions request

  3. the user’s browser is redirected back to the SEP coordinator with an authorization code

  4. the SEP coordinator exchanges the authorization code for a token

To enable OAuth 2.0 authentication for SEP, configuration changes are made on the SEP coordinator. No changes are required to the worker configuration; only the communication from the clients to the coordinator is authenticated.

Set the callback/redirect URL to https://<trino-coordinator-domain-name>/oauth2/callback, when configuring an OAuth 2.0 authorization server like an OpenID Connect (OIDC) provider.

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

OpenID Connect Discovery#

SEP supports reading Authorization Server configuration from OIDC provider configuration metadata document. During startup of the coordinator SEP retrieves the document and uses provided values to set corresponding OAuth2 authentication configuration properties:

  • authorization_endpoint -> http-server.authentication.oauth2.auth-url

  • token_endpoint -> http-server.authentication.oauth2.token-url

  • jwks_uri -> http-server.authentication.oauth2.jwks-url

  • userinfo_endpoint -> http-server.authentication.oauth2.userinfo-url

  • access_token_issuer -> http-server.authentication.oauth2.access-token-issuer


If the authorization server is issuing JSON Web Tokens (JWTs) and the metadata document contains userinfo_endpoint, SEP uses this endpoint to check the validity of OAuth2 access tokens. Since JWTs can be inspected locally, using them against userinfo_endpoint may result in authentication failure. In this case, set the http-server.authentication.oauth2.oidc.use-userinfo-endpoint configuration property to false (http-server.authentication.oauth2.oidc.use-userinfo-endpoint=false). This instructs SEP to ignore userinfo_endpoint and inspect tokens locally.

This functionality is enabled by default but can be turned off with: http-server.authentication.oauth2.oidc.discovery=false.

SEP server configuration#

Using the OAuth2 authentication requires the SEP coordinator to be secured with TLS.

The following is an example of the required properties that need to be added to the coordinator’s config.properties file:




In order to enable OAuth 2.0 authentication for the Web UI, the following properties need to be added:


The following configuration properties are available:

OAuth2 configuration properties#




The type of authentication to use. Must be set to oauth2 to enable OAuth2 authentication for the SEP coordinator.


The issuer URL of the IdP. All issued tokens must have this in the iss field.


The issuer URL of the IdP for access tokens, if different. All issued access tokens must have this in the iss field. Providing this value while OIDC discovery is enabled overrides the value from the OpenID provider metadata document. Defaults to the value of http-server.authentication.oauth2.issuer.


The authorization URL. The URL a user’s browser will be redirected to in order to begin the OAuth 2.0 authorization process. Providing this value while OIDC discovery is enabled overrides the value from the OpenID provider metadata document.


The URL of the endpoint on the authorization server which SEP uses to obtain an access token. Providing this value while OIDC discovery is enabled overrides the value from the OpenID provider metadata document.


The URL of the JSON Web Key Set (JWKS) endpoint on the authorization server. It provides SEP the set of keys containing the public key to verify any JSON Web Token (JWT) from the authorization server. Providing this value while OIDC discovery is enabled overrides the value from the OpenID provider metadata document.


The URL of the IdPs /userinfo endpoint. If supplied then this URL is used to validate the OAuth access token and retrieve any associated claims. This is required if the IdP issues opaque tokens. Providing this value while OIDC discovery is enabled overrides the value from the OpenID provider metadata document.


The public identifier of the SEP client.


The secret used to authorize SEP client with the authorization server.


Additional audiences to trust in addition to the client ID which is always a trusted audience.


Scopes requested by the server during the authorization challenge. See: https://tools.ietf.org/html/rfc6749#section-3.3


Maximum duration of the authorization challenge. Default is 15m.


A secret key used by the SHA-256 HMAC algorithm to sign the state parameter in order to ensure that the authorization request was not forged. Default is a random string generated during the coordinator start.


Regex to match against user. If matched, the user name is replaced with first regex group. If not matched, authentication is denied. Default is (.*) which allows any user name.


File containing rules for mapping user. See User mapping for more information.


The field of the access token used for the SEP user principal. Defaults to sub. Other commonly used fields include sAMAccountName, name, upn, and email.


Enable reading the OIDC provider metadata. Default is true.


The timeout when reading OpenID provider metadata. Default is 30s.


Use the value of userinfo_endpoint in the provider metadata. When a userinfo_endpoint value is supplied this URL is used to validate the OAuth 2.0 access token, and retrieve any associated claims. This flag allows ignoring the value provided in the metadata document. Required for JWT access tokens which support local validation. Default is true.

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


Refresh tokens#

In order to start using refresh tokens flows, the following property must be enabled in the coordinator configuration.


Additional scopes for offline access might be required, depending on IdP configuration.

http-server.authentication.oauth2.scopes=openid,offline_access [or offline]

The following configuration properties are available:

OAuth2 configuration properties for refresh flow#




Expiration time for issued token. Value must be less than or equal to the duration of the refresh token expiration issued by the IdP. Defaults to 1h.


Issuer representing the coordinator instance, that is referenced in the issued token, defaults to Trino_coordinator. The current Trino version is appended to the value. This is mainly used for debugging purposes.


Audience representing this coordinator instance, that is used in the issued token. Defaults to Trino_coordinator.


Base64-encoded secret key used to encrypt the generated token. By default it’s generated during startup.


If you need to debug issues with SEP OAuth 2.0 configuration you can change the log level for the OAuth 2.0 authenticator: