Configure authentication#

Important

In standalone mode, configure authentication identically on the Starburst control plane and on every connected cluster. This includes the authentication type, user mapping rules, and the secret used to sign authentication:

  • For password or insecure authentication, set web-ui.shared-secret to the same value on control plane and all clusters.

  • For OAuth2 authentication, set http-server.authentication.oauth2.state-key and http-server.authentication.oauth2.issuer to the same values on control plane and all clusters.

If the configurations differ, you can log in to control plane but authentication fails when queries route to a cluster. See Shared secrets.

In managed mode, you configure authentication only on control plane. Control plane authenticates the users of the clusters, and managed mode sets the authentication types of the clusters for you. See Connect a cluster to control plane.

Control plane supports the following authentication methods:

  • Password authentication: Username and password validated against a password file.

  • LDAP authentication: Username and password validated against an LDAP server.

  • OAuth2/OpenID Connect (OIDC) authentication: Single sign-on through external identity providers.

  • Insecure authentication: No authentication (development only).

Password authentication#

Password authentication uses a password file to validate usernames and passwords.

Set the following properties in your config.properties file:

web-ui.authentication.type=form
http-server.authentication.type=password
web-ui.shared-secret=<SHARED_SECRET>
password-authenticator.config-files=/path/to/password-authenticator.properties

Create a password-authenticator.properties file at the path you specify in password-authenticator.config-files. Set the following properties:

password-authenticator.name=file
file.password-file=/path/to/passwords.db

Password authenticator properties#

Property

Description

Default

file.password-file

The path to the password file.

None (required)

file.refresh-period

The refresh period for the password file.

5s

file.auth-token-cache.max-size

The maximum number of cached authenticated passwords.

1000

Password authentication uses web-ui.shared-secret. In standalone mode, it must be identical across control plane and all connected clusters. See Shared secrets.

LDAP authentication#

LDAP authentication validates usernames and passwords against an LDAP server, such as OpenLDAP or Active Directory. Control plane uses the same LDAP password authenticator as SEP, so all properties described in LDAP authentication in SEP also apply to control plane.

Set the following properties in your config.properties file:

web-ui.authentication.type=form
http-server.authentication.type=password
web-ui.shared-secret=<SHARED_SECRET>
password-authenticator.config-files=/path/to/password-authenticator.properties

Create a password-authenticator.properties file at the path you specify in password-authenticator.config-files. To authenticate users by binding with a distinguished name (DN) built from the username, set the following properties:

password-authenticator.name=ldap
ldap.url=ldaps://ldap-server:636
ldap.ssl.truststore.path=/path/to/ldap-truststore.pem
ldap.user-bind-pattern=uid=${USER},ou=people,dc=example,dc=com

To look up the user with a service account instead, for example to allow only members of a specific group to log in, set the following properties:

password-authenticator.name=ldap
ldap.url=ldaps://ldap-server:636
ldap.ssl.truststore.path=/path/to/ldap-truststore.pem
ldap.bind-dn=cn=service-account,dc=example,dc=com
ldap.bind-password=<BIND_PASSWORD>
ldap.user-base-dn=ou=people,dc=example,dc=com
ldap.group-auth-pattern=(&(uid=${USER})(memberOf=cn=starburst-users,ou=groups,dc=example,dc=com))

LDAP authenticator properties#

The following table lists the most commonly used properties. For all properties, see LDAP authentication in SEP.

Property

Description

Default

ldap.url

The URL of the LDAP server. Use the ldaps:// scheme.

None (required)

ldap.allow-insecure

Allows an ldap:// URL without TLS. Only use for testing or development.

false

ldap.ssl.truststore.path

The path to the PEM or JKS truststore that contains the certificate of the LDAP server.

None

ldap.user-bind-pattern

The pattern for the DN to bind as, where ${USER} is replaced with the username. Separate multiple patterns with a colon (:).

None

ldap.bind-dn

The DN of the service account used to look up users.

None

ldap.bind-password

The password of the service account.

None

ldap.user-base-dn

The base DN under which to look up users. Required with ldap.group-auth-pattern.

None

ldap.group-auth-pattern

The LDAP search filter, where ${USER} is replaced with the username, that a user must match to log in. Required with ldap.bind-dn.

None

ldap.cache-ttl

How long successful logins are cached.

1h

Note

ldap.group-auth-pattern only controls who can log in. It does not provide group memberships to control plane. LDAP authentication checks the credentials at login. It does not create accounts, and it does not synchronize groups. To use LDAP groups for authorization, configure LDAP user and group synchronization. The SEP LDAP group provider, which queries the directory directly, is a different setup, and control plane does not support it.

Like password authentication, LDAP authentication uses web-ui.shared-secret. In standalone mode, it must be identical across control plane and all connected clusters. See Shared secrets.

OAuth2 authentication#

Use OAuth2 authentication to enable single sign-on (SSO) through an external identity provider such as Okta, Azure AD, or Keycloak.

Set the following minimum required properties in your config.properties file:

web-ui.authentication.type=oauth2
http-server.authentication.type=oauth2
http-server.authentication.oauth2.issuer=https://your-idp.com/
http-server.authentication.oauth2.client-id=<CLIENT_ID>
http-server.authentication.oauth2.client-secret=<CLIENT_SECRET>
http-server.authentication.oauth2.state-key=<SHARED_SECRET>

OAuth2 authentication uses http-server.authentication.oauth2.state-key. In standalone mode, it must be identical across control plane and all connected clusters. See Shared secrets. In standalone mode, http-server.authentication.oauth2.issuer must also be identical across control plane and all connected clusters.

OAuth2 configuration properties#

Property

Description

Default

http-server.authentication.oauth2.issuer

The issuer URL of the OAuth2/OIDC provider. Used for token validation and OIDC. In standalone mode, must be identical across control plane and all connected clusters.

None

http-server.authentication.oauth2.client-id

The OAuth2 client ID registered with the identity provider.

None

http-server.authentication.oauth2.client-secret

The OAuth2 client secret for the registered client.

None

http-server.authentication.oauth2.state-key

Secret key used to HMAC-sign the OAuth2 state parameter. In standalone mode, must be identical across control plane and all connected clusters.

None

http-server.authentication.oauth2.scopes

Comma-separated list of OAuth2 scopes to request. Typically includes openid, profile, and email.

None

http-server.authentication.oauth2.auth-url

The authorization endpoint URL. Required when OIDC discovery is disabled.

None

http-server.authentication.oauth2.token-url

The token endpoint URL. Required when OIDC discovery is disabled.

None

http-server.authentication.oauth2.jwks-url

The JSON Web Key Set (JWKS) endpoint URL used to verify token signatures. Required when OIDC discovery is disabled.

None

http-server.authentication.oauth2.userinfo-url

The UserInfo endpoint URL. Optional: use to obtain user claims or to validate opaque tokens that cannot be validated locally.

None

http-server.authentication.oauth2.end-session-url

The end session (logout) endpoint URL. Optional: configure to enable single logout.

None

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

The expected issuer claim value for access tokens. Use this when access token issuer differs from the main issuer value returned.

None

http-server.authentication.oauth2.additional-audiences

A comma-separated list of additional valid audience values for token validation.

None

http-server.authentication.oauth2.principal-field

The token claim to use as the principal (username). Common alternatives: upn, email, or preferred_username.

sub

http-server.authentication.oauth2.oidc.discovery

Enable OIDC discovery to fetch provider endpoints from the issuer. Set to false to supply endpoints manually.

true

http-server.authentication.oauth2.oidc.use-userinfo-endpoint

Use the UserInfo endpoint obtained through OIDC discovery. Set to false if tokens are non-opaque and can be validated locally.

true

Insecure authentication#

Warning

Do not use insecure authentication in production environments.

Insecure authentication accepts any username without validation. Use this authentication type only for development and testing.

To enable insecure authentication, set the following properties in your config.properties file:

http-server.authentication.type=insecure
web-ui.shared-secret=<SHARED_SECRET>

Like password authentication, insecure authentication uses web-ui.shared-secret. In standalone mode, it must be identical across control plane and all connected clusters. See Shared secrets.

Configure cluster authentication#

Cluster authentication lets control plane prove its identity to the clusters. Control plane signs a token for each request that it sends to a cluster, and the cluster accepts the request only if it trusts the token. Managed mode needs cluster authentication, and so does the smart load balancing statement queue.

Cluster authentication is different from the authentication of your users. See Configure authentication. It is also different from the secret that you enter when you add a cluster. See Shared secrets.

Turn on cluster authentication#

Set the following properties in the config.properties file of control plane:

gateway.clusters.authentication.enabled=true
gateway.clusters.authentication.issuer=https://control-plane.example.com
gateway.clusters.authentication.secret=${ENV:CLUSTERS_AUTH_SECRET}

Set gateway.clusters.authentication.secret or gateway.clusters.authentication.private-key-file, but not both. Use the private key file where you cannot derive the signing key from a secret. The file holds a PEM-encoded RSA private key.

The issuer must be an HTTP or HTTPS URL, without a query or a fragment. It must match http-server.authentication.managed.issuer on the clusters, or their discovery.uri when http-server.authentication.managed.issuer is not set. In managed mode, discovery.uri of a cluster comes from deployment.manager.uri. If a cluster reaches control plane at a different address than the issuer, set http-server.authentication.managed.issuer on the cluster to the issuer. See Connect a cluster to control plane.

Store the secret in a secret manager, or in an environment variable. See Configure a secrets provider.

When you need cluster authentication#

  • Managed mode. Control plane does not start if control-plane.enabled is true and cluster authentication is off. The error says: control-plane.enabled requires gateway.enabled and gateway.clusters.authentication.enabled.

  • The smart load balancing statement queue. Control plane does not start if the queue is on and cluster authentication is off. The error says: statement-queue.enabled requires gateway.clusters.authentication.enabled to be true. See Smart load balancing.

  • Auto tag-based routing. Cluster authentication needs auto tag-based routing, which is the default. See Set the routing method.

Cluster authentication is off by default. In standalone mode, turn off the statement queue by setting statement-queue.enabled to false.

Cluster authentication properties#

Property

Description

Default

gateway.clusters.authentication.enabled

Authenticates the requests that control plane sends to clusters with tokens that control plane signs. It is required when control-plane.enabled is true.

false

gateway.clusters.authentication.issuer

The issuer of the tokens that control plane creates. It must be an HTTP or HTTPS URL without a query or a fragment. It must match http-server.authentication.managed.issuer on the clusters, or their discovery.uri when that is not set.

None (required)

gateway.clusters.authentication.secret

The secret that control plane uses to derive the signing key of its tokens.

None

gateway.clusters.authentication.private-key-file

The path to a PEM-encoded RSA private key that signs the tokens. Use it where you cannot derive the key from a secret.

None

gateway.clusters.authentication.token.ttl

How long a token is valid.

6h

gateway.clusters.authentication.statement.ttl

How long a statement submission token is valid. It must not be longer than gateway.clusters.authentication.token.ttl.

30s

If a property is missing, control plane does not start, and the error names the property.

Other secrets of control plane#

The cluster authentication secret is not the only secret that control plane uses. Control plane encrypts the credentials of clusters, the catalog files, and the queued statements with a key that it derives from gateway.clusters.encryption.secret. Do not use the same value for both secrets. For the other secrets, see Shared secrets.