Shared secrets#

The Starburst control plane uses secrets for three distinct purposes: signing authentication, authenticating with backend clusters, and signing the tokens that it sends to clusters. Do not confuse them. The first two rows of the table apply to clusters in standalone mode.

Secret

Where you set it

Constraint

web-ui.shared-secret

config.properties on 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 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.

gateway.clusters.authentication.secret

config.properties on control plane. Set it, or set gateway.clusters.authentication.private-key-file, but not both.

Control plane signs the tokens that it sends to clusters with it. Cluster authentication needs it, and managed mode and the smart load balancing statement queue need cluster authentication. See Configure cluster authentication.

Authentication signing secret#

In standalone mode, control plane and backend clusters must sign and validate authentication with the same secret. The signing secret must therefore be identical across control plane and all connected clusters. In managed mode, the clusters accept the tokens that control plane signs, so they do not need the same signing secret. See Configure cluster authentication. 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. You might see the following issues:

  • You successfully log in to 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 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. Control plane then 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 Manage clusters and Secure internal communication.