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 |
|---|---|---|
|
|
Must be identical across control plane and all clusters |
|
|
Must be identical across control plane and all clusters |
|
|
The value you enter in the UI must match the value configured on that specific cluster. |
|
|
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-secretto sign the web UI session cookie.OAuth2 authentication uses
http-server.authentication.oauth2.state-keyto 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.