Control Plane security#

Note

The previous name of the Starburst Control Plane was Starburst Portal.

Starburst Control Plane provides authentication, TLS, and authorization options for securing access to your clusters.

TLS#

Starburst Control Plane requires TLS for all authentication methods. Configure TLS using one of the following methods:

Direct TLS termination: Starburst Control Plane terminates TLS connections directly
Load balancer termination: A load balancer terminates TLS and forwards traffic to Starburst Control Plane

Direct TLS termination#

To configure Starburst Control Plane to handle TLS termination directly, add a keystore that contains the server certificate and private key to your configuration.

To use a JKS keystore, set the following properties in your config.properties file:

http-server.https.enabled=true
http-server.https.port=8443
http-server.https.keystore.path=/etc/starburst/keystore.jks
http-server.https.keystore.key=keystore-password

To use a PEM-encoded certificate file, set the following properties in your config.properties file:

http-server.https.enabled=true
http-server.https.port=8443
http-server.https.keystore.path=/etc/starburst/server.pem
http-server.https.keystore.key=

Load balancer termination#

To configure Starburst Control Plane to accept forwarded traffic from a load balancer, set the following properties in your config.properties file:

http-server.http.port=8080
http-server.process-forwarded=true

When you enable http-server.process-forwarded, Starburst Control Plane uses X-Forwarded-* headers from the load balancer to construct correct redirect URLs and identify the original client.

Important

Only enable http-server.process-forwarded when Starburst Control Plane is behind a trusted load balancer.
Ensure the load balancer sets the appropriate X-Forwarded-* headers.
Secure the network between the load balancer and Starburst Control Plane.

TLS configuration properties#

Property	Description	Default
`http-server.https.enabled`	Enables HTTPS.	`false`
`http-server.https.port`	The HTTPS port.	`8443`
`http-server.https.keystore.path`	The path to the keystore file (JKS) or PEM certificate file.	None
`http-server.https.keystore.key`	The password for the keystore. Use an empty string for PEM files without a password.	None
`http-server.http.port`	The HTTP port.	`8080`
`http-server.process-forwarded`	Enables trust of `X-Forwarded-*` headers from a load balancer. Only enable when Starburst Control Plane is behind a trusted load balancer.	`false`

Certificates#

Configure Starburst Control Plane to trust self-signed certificates or certificates signed by an internal certificate authority (CA) using one of the following methods:

System truststore: Add certificates to the Java system trust store
JVM options: Configure a custom truststore in jvm.config
Application configuration: Configure truststores for specific Starburst Control Plane components

Note

Starburst Control Plane supports configuring only one truststore. Include certificates for all clusters in this truststore. :::

System truststore

Add your cluster certificates or your CA certificate to the Java system truststore:

keytool -importcert -alias cluster-ca \
  -file /path/to/ca-certificate.pem \
  -keystore $JAVA_HOME/lib/security/cacerts \
  -storepass changeit

JVM options

Configure a custom truststore in jvm.config:

-Djavax.net.ssl.trustStore=/path/to/truststore.jks
-Djavax.net.ssl.trustStorePassword=truststore-password

Application configuration

You can also configure truststores for specific Starburst Control Plane components at the application level.

To configure the proxy HTTP client for proxying requests to backend clusters, set the following properties in your config.properties file:

proxy.http-client.trust-store-path=/path/to/truststore.jks
proxy.http-client.trust-store-password=truststore-password

To configure internal communication with clusters for health checks and monitoring, set the following properties in your config.properties file:

clusters.internal-communication.https.truststore.path=/path/to/truststore.jks
clusters.internal-communication.https.truststore.key=truststore-password

Authentication

Important

Configure authentication identically on 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 to the same value 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.

Starburst Control Plane supports the following authentication methods:

Password authentication: Username and password validated against a password file
OAuth2/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, which must be identical across Starburst 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 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=your_client_id
http-server.authentication.oauth2.client-secret=your_client_secret
http-server.authentication.oauth2.state-key=<SHARED_SECRET>

OAuth2 authentication uses http-server.authentication.oauth2.state-key, which must be identical across Starburst Control Plane and all connected clusters. See Shared secrets.

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.
`http-server.authentication.oauth2.client-id`	The OAuth2 client ID registered with the identity provider.
`http-server.authentication.oauth2.client-secret`	The OAuth2 client secret for the registered client.
`http-server.authentication.oauth2.state-key`	Secret key used to HMAC-sign the OAuth2 state parameter. Must be identical across Control Plane and all connected clusters.
`http-server.authentication.oauth2.scopes`	Comma-separated list of OAuth2 scopes to request. Typically includes `openid`, `profile`, and `email`.
`http-server.authentication.oauth2.auth-url`	The authorization endpoint URL. Required when OIDC discovery is disabled.
`http-server.authentication.oauth2.token-url`	The token endpoint URL. Required when OIDC discovery is disabled.
`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.
`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.
`http-server.authentication.oauth2.end-session-url`	The end session (logout) endpoint URL. Optional: configure to enable single logout.
`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.
`http-server.authentication.oauth2.additional-audiences`	A comma-separated list of additional valid audience values for token validation.
`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 via 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, which must be identical across Starburst Control Plane and all connected clusters. See Shared secrets.

Shared secrets#

Starburst Control Plane uses shared secrets for two distinct purposes: signing authentication, and authenticating with backend clusters. Do not confuse them.

Secret	Where you set it	Constraint
`web-ui.shared-secret`	`config.properties` on Starburst Control Plane and on every connected cluster. Applies to password and insecure authentication.	Must be identical across Control Plane and all clusters
`http-server.authentication.oauth2.state-key`	`config.properties` on Starburst Control Plane and on every connected cluster. Applies to OAuth2 authentication.	Must be identical across Control Plane and all clusters
`internal-communication.shared-secret`	`config.properties` on each cluster, and entered per cluster in the Shared secret field of the Control Plane Clusters pane.	The value you enter in the UI must match the value configured on that specific cluster.

Authentication signing secret#

Control Plane and backend clusters must sign and validate authentication with the same secret, so the signing secret must be identical across Starburst Control Plane and all connected clusters. The property and what it signs depend on the authentication type:

Password or insecure authentication uses web-ui.shared-secret to sign the web UI session cookie.
OAuth2 authentication uses http-server.authentication.oauth2.state-key to sign the OAuth2 state parameter.

If the secrets do not match, authentication fails when Control Plane routes requests to a backend cluster.

If your secrets do not match, you may experience the following issues:

You successfully log in to Starburst Control Plane but receive authentication errors when queries route to clusters.
You experience intermittent authentication failures if some clusters have different secrets.
You cannot navigate to the cluster UI and are redirected back to the Starburst Control Plane clusters page.

internal-communication.shared-secret#

Each cluster uses its own internal-communication.shared-secret to authenticate internal communication. When you add a cluster in the Clusters pane, enter that cluster’s internal-communication.shared-secret value in the Shared secret field so that the Control Plane can reach the cluster for routing and health checks. If the values do not match, Control Plane marks the cluster as UNHEALTHY. For more information, see Control Plane administration and Secure internal communication.

User mapping#

Use user mapping to transform usernames from your authentication provider into Starburst Control Plane usernames. Choose one of the following methods:

Pattern mapping: A single regular expression.
File mapping: A JSON file containing multiple rules.

Pattern mapping#

Use pattern mapping to transform all usernames with a single regular expression.

For example, if your authentication provider uses usernames in the form alice@example.com, use a regex that captures the name before the @ sign:

http-server.authentication.oauth2.user-mapping.pattern=(.*)(@.*)

Starburst Control Plane uses the first capture group as the mapped username. If the regex does not match the username, Starburst Control Plane denies authentication.

Pattern mapping properties#

Authentication type	Property
Password	`http-server.authentication.password.user-mapping.pattern`
OAuth2	`http-server.authentication.oauth2.user-mapping.pattern`
Insecure	`http-server.authentication.insecure.user-mapping.pattern`

File mapping#

Use file mapping to define multiple transformation rules or to exclude specific users.

Create a JSON file with your mapping rules:

{
  "rules": [
    {
      "pattern": "test@example\\.com",
      "allow": false
    },
    {
      "pattern": "(.+)@example\\.com"
    },
    {
      "pattern": "(?<user>.+)@(?<region>.+)\\.example\\.com",
      "user": "${user}_${region}"
    }
  ]
}

Starburst Control Plane processes rules from top to bottom and uses the first matching rule. If no rules match, Control Plane denies authentication.

Each rule supports the following fields:

pattern (required): Regex to match against the username
user (optional): Replacement string. Default: $1
allow (optional): Whether to allow authentication for this match
case (optional): keep (default), lower, or upper

Add the mapping file path to your config.properties file:

http-server.authentication.oauth2.user-mapping.file=etc/user-mapping.json

File mapping properties#

Authentication type	Property
Password	`http-server.authentication.password.user-mapping.file`
OAuth2	`http-server.authentication.oauth2.user-mapping.file`
Insecure	`http-server.authentication.insecure.user-mapping.file`

Authorization#

Configure admin users and groups using the same properties used to configure BIAC in SEP. Set one or both of the following properties in the config.properties file for Starburst Control Plane, shown here with example values.

starburst.access-control.authorized-users=alice,bob
starburst.access-control.authorized-groups=portal-admins

At least one of these properties must be defined, or Starburst Control Plane cannot start.

Best practices#

Always enable TLS for production deployments.
Generate secrets with at least 256 bits of entropy.
Ensure the authentication signing secret is identical across Starburst Control Plane and all clusters: web-ui.shared-secret for password or insecure authentication, or http-server.authentication.oauth2.state-key for OAuth2.
Use environment variables or a secret management system to store secrets.
When using load balancer TLS termination, secure the network between the load balancer and Starburst Control Plane.