orchestratord: Add SASL/SCRAM-SHA-256 authentication

Author: bobbyiliev

doc/user/content/security/self-managed/authentication.md

@@ -82,6 +82,73 @@ users:
 [^1]: The `mz_system` user is also used by the Materialize Operator for upgrades
 and maintenance tasks.
 
+## Configuring SASL/SCRAM authentication
+
+{{< public-preview >}}This feature{{</ public-preview >}}
+
+{{< note >}}
+SASL/SCRAM-SHA-256 authentication requires Materialize v0.147.16 or later.
+{{</ note >}}
+
+SASL/SCRAM-SHA-256 authentication is a challenge-response authentication mechanism
+that provides security for PostgreSQL wire protocol connections. It is
+compatible with PostgreSQL clients that support SCRAM-SHA-256.
+
+To configure Self-Managed Materialize for SASL/SCRAM authentication:
+
+| Configuration | Description
+|---------------| ------------
+|`spec.authenticatorKind` | Set to `Sasl` to enable SASL/SCRAM-SHA-256 authentication for PostgreSQL connections.
+|`external_login_password_mz_system` | To the Kubernetes Secret referenced by `spec.backendSecretName`, add the secret key `external_login_password_mz_system`. This is the password for the `mz_system` user [^1], who is the only user initially available when SASL authentication is enabled.
+
+For example, if using Kind, in the `sample-materialize.yaml` file:
+
+```
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: materialize-environment
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: materialize-backend
+  namespace: materialize-environment
+stringData:
+  metadata_backend_url: "..."
+  persist_backend_url: "..."
+  external_login_password_mz_system: "enter_mz_system_password"
+---
+apiVersion: materialize.cloud/v1alpha1
+kind: Materialize
+metadata:
+  name: 12345678-1234-1234-1234-123456789012
+  namespace: materialize-environment
+spec:
+  environmentdImageRef: materialize/environmentd:v0.147.2
+  backendSecretName: materialize-backend
+  authenticatorKind: Sasl
+```
+
+### Logging in and creating users
+
+The process is the same as for [password authentication](#logging-in-and-creating-users):
+
+1. Login as the `mz_system` user using the `external_login_password_mz_system` password
+2. Use [`CREATE ROLE ... WITH LOGIN PASSWORD ...`](/sql/create-role) to create new users
+
+User passwords are automatically stored in SCRAM-SHA-256 format in the database.
+
+### Authentication behavior
+
+When SASL authentication is enabled:
+
+- **PostgreSQL connections** (e.g., `psql`, client libraries) use SCRAM-SHA-256 authentication
+- **HTTP/Web Console connections** use standard password authentication
+
+This hybrid approach provides maximum security for SQL connections while maintaining
+compatibility with web-based tools.
+
 ## Enabling RBAC
 
 {{< include-md file="shared-content/enable-rbac.md" >}}

doc/user/data/self_managed/authentication_setting.yml

@@ -3,17 +3,28 @@ columns:
   - column: "Description"
 
 rows:
-- "authenticatorKind Value": "**None**"
-  "Description": |
-    Disables authentication. All users are trusted based on their claimed
-    identity **without** any verification. **Default**
-- "authenticatorKind Value": "**Password**"
-  "Description": |
-    Enables [password authentication](#configuring-password-authentication) for
-    users. When enabled, users must authenticate with their password.
+  - "authenticatorKind Value": "**None**"
+    "Description": |
+      Disables authentication. All users are trusted based on their claimed
+      identity **without** any verification. **Default**
+  - "authenticatorKind Value": "**Password**"
+    "Description": |
+      Enables [password authentication](#configuring-password-authentication) for
+      users. When enabled, users must authenticate with their password.
 
-    {{< tip >}}
-    When enabled, you must also set the `mz_system` user password in
-    `external_login_password_mz_system`. See [Configuring password
-    authentication](#configuring-password-authentication) for details.
-    {{</ tip >}}
+      {{< tip >}}
+      When enabled, you must also set the `mz_system` user password in
+      `external_login_password_mz_system`. See [Configuring password
+      authentication](#configuring-password-authentication) for details.
+      {{</ tip >}}
+  - "authenticatorKind Value": "**Sasl**"
+    "Description": |
+      Enables [SASL/SCRAM-SHA-256 authentication](#configuring-saslscram-authentication) for
+      PostgreSQL wire protocol connections. This is a challenge-response authentication
+      mechanism that provides enhanced security compared to simple password authentication.
+
+      {{< tip >}}
+      When enabled, you must also set the `mz_system` user password in
+      `external_login_password_mz_system`. See [Configuring SASL/SCRAM
+      authentication](#configuring-saslscram-authentication) for details.
+      {{</ tip >}}

src/cloud-resources/src/crd/materialize.rs

@@ -175,10 +175,11 @@ pub mod v1alpha1 {
         pub rollout_strategy: MaterializeRolloutStrategy,
         // The name of a secret containing metadata_backend_url and persist_backend_url.
         // It may also contain external_login_password_mz_system, which will be used as
-        // the password for the mz_system user if authenticator_kind is Password.
+        // the password for the mz_system user if authenticator_kind is Password or Sasl.
         pub backend_secret_name: String,
-        // How to authenticate with Materialize. Valid options are Password and None.
-        // If set to Password, the backend secret must contain external_login_password_mz_system.
+        // How to authenticate with Materialize. Valid options are Password, Sasl, and None.
+        // If set to Password or Sasl, the backend secret must contain external_login_password_mz_system.
+        // Sasl enables SCRAM-SHA-256 authentication for PostgreSQL wire protocol connections.
         #[serde(default)]
         pub authenticator_kind: AuthenticatorKind,
         // Whether to enable role based access control. Defaults to false.

src/orchestratord/src/controller/materialize/environmentd.rs

@@ -1394,7 +1394,10 @@ fn create_environmentd_statefulset_object(
             ..Default::default()
         });
         args.push("--listeners-config-path=/listeners/listeners.json".to_owned());
-        if mz.spec.authenticator_kind == AuthenticatorKind::Password {
+        if matches!(
+            mz.spec.authenticator_kind,
+            AuthenticatorKind::Password | AuthenticatorKind::Sasl
+        ) {
             args.push("--system-parameter-default=enable_password_auth=true".into());
             env.push(EnvVar {
                 name: "MZ_EXTERNAL_LOGIN_PASSWORD_MZ_SYSTEM".to_string(),
@@ -1628,12 +1631,21 @@ fn create_connection_info(
         &config.default_certificate_specs.internal,
         &mz.spec.internal_certificate_spec,
     );
-    let authenticator_kind = mz.spec.authenticator_kind;
+    let auth_kind = mz.spec.authenticator_kind;
+
+    // SASL authentication is only supported for SQL (PostgreSQL wire protocol).
+    // HTTP listeners must use Password authentication when SASL is enabled.
+    // This is validated at environmentd startup via ListenerConfig::validate().
+    let (sql_auth, http_auth) = match auth_kind {
+        AuthenticatorKind::Sasl => (AuthenticatorKind::Sasl, AuthenticatorKind::Password),
+        other => (other, other),
+    };
+
     let mut listeners_config = ListenersConfig {
         sql: btreemap! {
             "external".to_owned() => SqlListenerConfig{
                 addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::new(0,0,0,0)), config.environmentd_sql_port),
-                authenticator_kind,
+                authenticator_kind: sql_auth,
                 allowed_roles: AllowedRoles::Normal,
                 enable_tls: external_enable_tls,
             },
@@ -1649,7 +1661,7 @@ fn create_connection_info(
             "external".to_owned() => HttpListenerConfig{
                 base: BaseListenerConfig {
                     addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::new(0,0,0,0)), config.environmentd_http_port),
-                    authenticator_kind,
+                    authenticator_kind: http_auth,
                     allowed_roles: AllowedRoles::Normal,
                     enable_tls: external_enable_tls,
                 },
@@ -1679,7 +1691,11 @@ fn create_connection_info(
             },
         },
     };
-    if authenticator_kind == AuthenticatorKind::Password {
+
+    if matches!(
+        auth_kind,
+        AuthenticatorKind::Password | AuthenticatorKind::Sasl
+    ) {
         listeners_config.sql.remove("internal");
         listeners_config.http.remove("internal");
 
@@ -1732,8 +1748,8 @@ fn create_connection_info(
         },
     };
 
-    let (scheme, leader_api_port, mz_system_secret_name) = match mz.spec.authenticator_kind {
-        AuthenticatorKind::Password => {
+    let (scheme, leader_api_port, mz_system_secret_name) = match auth_kind {
+        AuthenticatorKind::Password | AuthenticatorKind::Sasl => {
             let scheme = if external_enable_tls { "https" } else { "http" };
             (
                 scheme,

test/orchestratord/mzcompose.py

@@ -1030,7 +1030,7 @@ def default(cls) -> Any:
 
     def modify(self, definition: dict[str, Any]) -> None:
         definition["materialize"]["spec"]["authenticatorKind"] = self.value
-        if self.value == "Password":
+        if self.value == "Password" or self.value == "Sasl":
             definition["secret"]["stringData"][
                 "external_login_password_mz_system"
             ] = "superpassword"
@@ -1046,9 +1046,13 @@ def validate(self, mods: dict[type[Modification], Any]) -> None:
         if self.value == "Password" and version <= MzVersion.parse_mz("v0.147.6"):
             return
 
+        if self.value == "Sasl" and version < MzVersion.parse_mz("v0.147.16"):
+            return
+
         port = (
             6875
-            if version >= MzVersion.parse_mz("v0.147.0") and self.value == "Password"
+            if (version >= MzVersion.parse_mz("v0.147.0") and self.value == "Password")
+            or (version >= MzVersion.parse_mz("v0.147.16") and self.value == "Sasl")
             else 6877
         )
         for i in range(120):
@@ -1098,7 +1102,7 @@ def validate(self, mods: dict[type[Modification], Any]) -> None:
             # psycopg.connect(
             #     host="127.0.0.1",
             #     user="mz_system",
-            #     password="superpassword" if self.value == "Password" else None,
+            #     password="superpassword" if (self.value == "Password" or self.value == "Sasl") else None,
             #     dbname="materialize",
             #     port=port,
             # )