OAuth 2.0 authentication#

BDV can be configured to enable OAuth 2.0 authentication over HTTPS for the Web UI and the JDBC driver. BDV 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 BDV coordinator redirects a user’s browser to the Authorization Server

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

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

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

To enable OAuth 2.0 authentication for BDV, configuration changes are made on the BDV 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://<bdv-coordinator-domain-name>/oauth2/callback, when configuring an OAuth 2.0 authorization server like an OpenID-connect provider.

BDV server configuration#

Using the OAuth2 authentication requires the BDV 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.auth-url=https://authorization-server.com/authorize
http-server.authentication.oauth2.token-url=https://authorization-server.com/token
http-server.authentication.oauth2.jwks-url=https://authorization-server.com/.well-known/jwks.json
http-server.authentication.oauth2.client-id=CLIENT_ID
http-server.authentication.oauth2.client-secret=CLIENT_SECRET

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

web-ui.authentication.type=oauth2

The following configuration properties are available:

OAuth2 configuration properties#

Property

Description

http-server.authentication.type

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

http-server.authentication.oauth2.issuer

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

http-server.authentication.oauth2.access-token-issuer

The issuer URL of the IdP for access tokens, if different. All issued access tokens must have this in the iss field. Defaults to http-server.authentication.oauth2.issuer.

http-server.authentication.oauth2.auth-url

The authorization URL. The URL a user’s browser will be redirected to in order to begin the OAuth 2.0 authorization process.

http-server.authentication.oauth2.token-url

The URL of the endpoint on the authorization server which BDV uses to obtain an access token.

http-server.authentication.oauth2.jwks-url

The URL of the JSON Web Key Set (JWKS) endpoint on the authorization server. It provides BDV the set of keys containing the public key to verify any JSON Web Token (JWT) from the authorization server.

http-server.authentication.oauth2.userinfo-url

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.

http-server.authentication.oauth2.client-id

The public identifier of the BDV client.

http-server.authentication.oauth2.client-secret

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

http-server.authentication.oauth2.additional-audiences

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

http-server.authentication.oauth2.scopes

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

http-server.authentication.oauth2.challenge-timeout

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

http-server.authentication.oauth2.state-key

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.

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

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.

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

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

http-server.authentication.oauth2.principal-field

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

http-server.authentication.oauth2.groups-field

The field of the access token used for BDV groups. The corresponding claim value must be an array.

Troubleshooting#

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

io.trino.server.security.oauth2=DEBUG