Skip to content

Commit bf15621

Browse files
kay-kimkay-kim
authored
docs: sasl/scram auth for self-managed (#34116)
docs portion of #34045
1 parent f3e9621 commit bf15621

File tree

4 files changed

+96
-15
lines changed

4 files changed

+96
-15
lines changed

‎doc/user/content/releases/_index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,12 @@ menu:
1313

1414
### Self-Managed v26.0.0
1515

16+
#### SASL/SCRAM-SHA-256 support
17+
18+
Starting in v26.0.0, Self-Managed Materialize supports SASL/SCRAM-SHA-256
19+
authentication for PostgreSQL wire protocol connections. For more information,
20+
see [Authentication](/security/self-managed/authentication/).
21+
1622
#### License Key
1723

1824
{{< include-md file="shared-content/license-key-required.md" >}}

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

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,71 @@ users:
8282
[^1]: The `mz_system` user is also used by the Materialize Operator for upgrades
8383
and maintenance tasks.
8484

85+
## Configuring SASL/SCRAM authentication
86+
87+
{{< note >}}
88+
SASL/SCRAM-SHA-256 authentication requires Materialize `v26.0.0` or later.
89+
{{</ note >}}
90+
91+
SASL/SCRAM-SHA-256 authentication is a challenge-response authentication mechanism
92+
that provides security for **PostgreSQL wire protocol connections**. It is
93+
compatible with PostgreSQL clients that support SCRAM-SHA-256.
94+
95+
To configure Self-Managed Materialize for SASL/SCRAM authentication:
96+
97+
| Configuration | Description
98+
|---------------| ------------
99+
|`spec.authenticatorKind` | Set to `Sasl` to enable SASL/SCRAM-SHA-256 authentication for PostgreSQL connections.
100+
|`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.
101+
102+
For example, if using Kind, in the `sample-materialize.yaml` file:
103+
104+
```hc {hl_lines="14 24"}
105+
apiVersion: v1
106+
kind: Namespace
107+
metadata:
108+
name: materialize-environment
109+
---
110+
apiVersion: v1
111+
kind: Secret
112+
metadata:
113+
name: materialize-backend
114+
namespace: materialize-environment
115+
stringData:
116+
metadata_backend_url: "..."
117+
persist_backend_url: "..."
118+
external_login_password_mz_system: "enter_mz_system_password"
119+
---
120+
apiVersion: materialize.cloud/v1alpha1
121+
kind: Materialize
122+
metadata:
123+
name: 12345678-1234-1234-1234-123456789012
124+
namespace: materialize-environment
125+
spec:
126+
environmentdImageRef: materialize/environmentd:v0.147.2
127+
backendSecretName: materialize-backend
128+
authenticatorKind: Sasl
129+
```
130+
131+
### Logging in and creating users
132+
133+
The process is the same as for [password authentication](#logging-in-and-creating-users):
134+
135+
1. Login as the `mz_system` user using the `external_login_password_mz_system` password
136+
2. Use [`CREATE ROLE ... WITH LOGIN PASSWORD ...`](/sql/create-role) to create new users
137+
138+
User passwords are automatically stored in SCRAM-SHA-256 format in the database.
139+
140+
### Authentication behavior
141+
142+
When SASL authentication is enabled:
143+
144+
- **PostgreSQL connections** (e.g., `psql`, client libraries) use SCRAM-SHA-256 authentication
145+
- **HTTP/Web Console connections** use standard password authentication
146+
147+
This hybrid approach provides maximum security for SQL connections while maintaining
148+
compatibility with web-based tools.
149+
85150
## Enabling RBAC
86151

87152
{{< include-md file="shared-content/enable-rbac.md" >}}

‎doc/user/data/self_managed/authentication_setting.yml‎

Lines changed: 24 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,28 @@ columns:
33
- column: "Description"
44

55
rows:
6-
- "authenticatorKind Value": "**None**"
7-
"Description": |
8-
Disables authentication. All users are trusted based on their claimed
9-
identity **without** any verification. **Default**
10-
- "authenticatorKind Value": "**Password**"
11-
"Description": |
12-
Enables [password authentication](#configuring-password-authentication) for
13-
users. When enabled, users must authenticate with their password.
6+
- "authenticatorKind Value": "**None**"
7+
"Description": |
8+
Disables authentication. All users are trusted based on their claimed
9+
identity **without** any verification. **Default**
10+
- "authenticatorKind Value": "**Password**"
11+
"Description": |
12+
Enables [password authentication](#configuring-password-authentication) for
13+
users. When enabled, users must authenticate with their password.
1414
15-
{{< tip >}}
16-
When enabled, you must also set the `mz_system` user password in
17-
`external_login_password_mz_system`. See [Configuring password
18-
authentication](#configuring-password-authentication) for details.
19-
{{</ tip >}}
15+
{{< tip >}}
16+
When enabled, you must also set the `mz_system` user password in
17+
`external_login_password_mz_system`. See [Configuring password
18+
authentication](#configuring-password-authentication) for details.
19+
{{</ tip >}}
20+
- "authenticatorKind Value": "**Sasl**"
21+
"Description": |
22+
Enables [SASL/SCRAM-SHA-256 authentication](#configuring-saslscram-authentication) for
23+
**PostgreSQL wire protocol connections**. This is a challenge-response authentication
24+
mechanism that provides enhanced security compared to simple password authentication.
25+
26+
{{< tip >}}
27+
When enabled, you must also set the `mz_system` user password in
28+
`external_login_password_mz_system`. See [Configuring SASL/SCRAM
29+
authentication](#configuring-saslscram-authentication) for details.
30+
{{</ tip >}}

‎doc/user/shared-content/rbac-sm/enable-rbac.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,7 @@ If RBAC is not enabled, all users have <red>**superuser**</red> privileges.
33
{{</ warning >}}
44

55
By default, role-based access control (RBAC) checks are not enabled (i.e.,
6-
enforced) when turning on [password
7-
authentication](/security/self-managed/authentication/#configuring-password-authentication). To
6+
enforced) when using [authentication](/security/self-managed/authentication/#configuring-authentication-type). To
87
enable RBAC, set the system parameter `enable_rbac_checks` to `'on'` or `True`.
98
You can enable the parameter in one of the following ways:
109

0 commit comments

Comments
 (0)