OAuth 2.0 authentication#
Trino can be configured to enable OAuth 2.0 authentication over HTTPS for the Web UI and the JDBC driver. Trino uses the Authorization Code flow which exchanges an Authorization Code for a token. At a high level, the flow includes the following steps:
the Trino coordinator redirects a user’s browser to the Authorization Server
the user authenticates with the Authorization Server, and it approves the Trino’s permissions request
the user’s browser is redirected back to the Trino coordinator with an authorization code
the Trino coordinator exchanges the authorization code for a token
To enable OAuth 2.0 authentication for Trino, configuration changes are made on the Trino 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.
If Web UI is enabled, set the post-logout callback URL to
https://<trino-coordinator-domain-name>/ui/logout/logout.html
when configuring
an OAuth 2.0 authentication server like an OpenID Connect (OIDC) provider.
Using TLS and a configured shared secret is required for OAuth 2.0 authentication.
OpenID Connect Discovery#
Trino supports reading Authorization Server configuration from OIDC provider configuration metadata document. During startup of the coordinator Trino 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
end_session_endpoint
->http-server.authentication.oauth2.end-session-url
Warning
If the authorization server is issuing JSON Web Tokens (JWTs) and the
metadata document contains userinfo_endpoint
, Trino 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 Trino 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
.
Trino server configuration#
Using the OAuth2 authentication requires the Trino 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:
http-server.authentication.type=oauth2
http-server.https.port=8443
http-server.https.enabled=true
http-server.authentication.oauth2.issuer=https://authorization-server.com
http-server.authentication.oauth2.client-id=CLIENT_ID
http-server.authentication.oauth2.client-secret=CLIENT_SECRET
To enable OAuth 2.0 authentication for the Web UI, the following property must be be added:
web-ui.authentication.type=oauth2
The following configuration properties are available:
Property |
Description |
---|---|
|
The type of authentication to use. Must be set to |
|
The issuer URL of the IdP. All issued tokens must have this in the |
|
The issuer URL of the IdP for access tokens, if different. All issued access
tokens must have this in the |
|
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 Trino 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 Trino 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 |
|
The public identifier of the Trino client. |
|
The secret used to authorize Trino 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 |
|
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
|
|
File containing rules for mapping user. See User mapping for more information. |
|
The field of the access token used for the Trino user principal. Defaults to
|
|
Enable reading the OIDC provider metadata.
Default is |
|
The timeout when reading OpenID provider metadata. Default is |
|
Use the value of |
|
The URL of the endpoint on the authentication server to which the user’s browser is redirected to so that End-User is logged out from the authentication server when logging out from Trino. |
Refresh tokens#
Refresh tokens allow you to securely control the length of user sessions within applications. The refresh token has a longer lifespan (TTL) and is used to refresh the access token that has a shorter lifespan. When refresh tokens are used in conjunction with access tokens, users can remain logged in for an extended duration without interruption by another login request.
In a refresh token flow, there are three tokens with different expiration times:
access token
refresh token
Trino-encrypted token that is a combination of the access and refresh tokens. The encrypted token manages the session lifetime with the timeout value that is set with the
http-server.authentication.oauth2.refresh-tokens.issued-token.timeout
property.
In the following scenario, the lifespan of the tokens issued by an IdP are:
access token 5m
refresh token 24h
Because the access token lifespan is only five minutes, Trino uses the longer
lifespan refresh token to request another access token every five minutes on
behalf of a user. In this case, the maximum
http-server.authentication.oauth2.refresh-tokens.issued-token.timeout
is
twenty-four hours.
To use refresh token flows, the following property must be enabled in the coordinator configuration.
http-server.authentication.oauth2.refresh-tokens=true
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:
Property |
Description |
---|---|
|
Expiration time for an issued token, which is the Trino-encrypted token that
contains an access token and a refresh token. The timeout value must be less
than or equal to the duration of the refresh token
expiration issued by the IdP. Defaults to |
|
Issuer representing the coordinator instance, that is referenced in the
issued token, defaults to |
|
Audience representing this coordinator instance, that is used in the
issued token. Defaults to |
|
Base64-encoded secret key used to encrypt the generated token. By default it’s generated during startup. |
Troubleshooting#
To debug issues, change the log level for the OAuth 2.0 authenticator:
io.trino.server.security.oauth2=DEBUG
To debug issues with OAuth 2.0 authentication use with the web UI, set the following configuration property:
io.trino.server.ui.OAuth2WebUiAuthenticationFilter=DEBUG
This assumes the OAuth 2.0 authentication for the Web UI is enabled as described in Trino server configuration.
The logged debug error for a lapsed refresh token is Tokens refresh challenge has failed
.
Warning
If a refresh token lapses, the user session is interrupted and the user must
reauthenticate by logging in again. Ensure you set the
http-server.authentication.oauth2.refresh-tokens.issued-token.timeout
value to less than or equal to the duration of the refresh token expiration
issued by your IdP. Optimally, the timeout should be slightly less than the
refresh token lifespan of your IdP to ensure that sessions end gracefully.