Security#

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

TLS#

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

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

Direct TLS termination#

To configure Starburst Portal 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 Portal 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 Portal 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 Portal 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 Portal.

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 Portal is behind a trusted load balancer.	`false`

Certificates#

Configure Starburst Portal 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 Portal components

Note

Starburst Portal 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 Portal 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#

Starburst Portal 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`

Shared secret#

Important

When you use password authentication, set web-ui.shared-secret to the same value on Starburst Portal and all connected clusters.

Starburst Portal uses web-ui.shared-secret to sign session cookies. When Starburst Portal routes requests to backend clusters, those clusters validate the cookie signature using the same secret. If the secrets do not match, authentication fails.

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

You successfully log in to Starburst Portal 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 Starburst Portal’s clusters page.

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

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.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

User mapping#

Use user mapping to transform usernames from your authentication provider into Starburst Portal 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 Portal uses the first capture group as the mapped username. If the regex does not match the username, Starburst Portal 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 Portal processes rules from top to bottom and uses the first matching rule. If no rules match, Starburst Portal 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 authorization rules using regex patterns to match user privileges. Set the following properties in your config.properties file:

authorization:
  admin: .*ADMIN.*
  user: .*USER.*
  api: .*API.*

Best practices#

Always enable TLS for production deployments.
Generate secrets with at least 256 bits of entropy.
When using password authentication, ensure web-ui.shared-secret is identical across Starburst Portal and all clusters.
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 Portal.