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-secretto the same value on control plane and all clusters.For OAuth2 authentication, set
http-server.authentication.oauth2.state-keyandhttp-server.authentication.oauth2.issuerto 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 |
|---|---|---|
|
The path to the password file. |
None (required) |
|
The refresh period for the password file. |
|
|
The maximum number of cached authenticated passwords. |
|
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 |
|---|---|---|
|
The URL of the LDAP server. Use the |
None (required) |
|
Allows an |
|
|
The path to the PEM or JKS truststore that contains the certificate of the LDAP server. |
None |
|
The pattern for the DN to bind as, where |
None |
|
The DN of the service account used to look up users. |
None |
|
The password of the service account. |
None |
|
The base DN under which to look up users. Required with
|
None |
|
The LDAP search filter, where |
None |
|
How long successful logins are cached. |
|
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 |
|---|---|---|
|
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 |
|
The OAuth2 client ID registered with the identity provider. |
None |
|
The OAuth2 client secret for the registered client. |
None |
|
Secret key used to HMAC-sign the OAuth2 state parameter. In standalone mode, must be identical across control plane and all connected clusters. |
None |
|
Comma-separated list of OAuth2 scopes to request. Typically includes
|
None |
|
The authorization endpoint URL. Required when OIDC discovery is disabled. |
None |
|
The token endpoint URL. Required when OIDC discovery is disabled. |
None |
|
The JSON Web Key Set (JWKS) endpoint URL used to verify token signatures. Required when OIDC discovery is disabled. |
None |
|
The UserInfo endpoint URL. Optional: use to obtain user claims or to validate opaque tokens that cannot be validated locally. |
None |
|
The end session (logout) endpoint URL. Optional: configure to enable single logout. |
None |
|
The expected issuer claim value for access tokens. Use this when access token issuer differs from the main issuer value returned. |
None |
|
A comma-separated list of additional valid audience values for token validation. |
None |
|
The token claim to use as the principal (username). Common alternatives:
|
|
|
Enable OIDC discovery to fetch provider endpoints from the issuer. Set to
|
|
|
Use the UserInfo endpoint obtained through OIDC discovery. Set to |
|
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.enabledistrueand 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 |
|---|---|---|
|
Authenticates the requests that control plane sends to clusters with tokens
that control plane signs. It is required when |
|
|
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
|
None (required) |
|
The secret that control plane uses to derive the signing key of its tokens. |
None |
|
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 |
|
How long a token is valid. |
|
|
How long a statement submission token is valid. It must not be longer than
|
|
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.