Authentication

Configuring Authentication Type

To configure the authentication type used by Self-Managed Materialize, use the spec.authenticatorKind setting in conjunction with any specific configuration for the authentication method.

The spec.authenticatorKind setting determines which authentication method is used:

authenticatorKind Value	Description
None	Disables authentication. All users are trusted based on their claimed identity without any verification. Default
Password	Enables 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 for details.
Sasl	Enables SASL/SCRAM-SHA-256 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 for details.

WARNING! Ensure that the authenticatorKind field is set for any future version upgrades or rollouts of the Materialize CR. Having it undefined will reset authenticationKind to None.

Configuring password authentication

PREVIEW This feature is in public preview. It is under active development and may have stability or performance issues. It isn't subject to our backwards compatibility guarantees.

Password authentication requires users to log in with a password.

To configure Self-Managed Materialize for password authentication, update the following fields in the Materialize CR. For all Materialize CR settings, see here.

Configuration	Description
`spec.authenticatorKind`	Set to `Password` to enable password authentication.
`external_login_password_mz_system`	Set 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 ¹, who is the only user initially available when password authentication is enabled.

An example Materialize CR 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: Password

Logging in and creating users

Initially, only the mz_system user ¹ is available. To create additional users:

Login as the mz_system user, using the external_login_password_mz_system password,
Use CREATE ROLE ... WITH LOGIN PASSWORD ... to create new users:
```
CREATE ROLE <user> WITH LOGIN PASSWORD '<password>';
```

Configuring SASL/SCRAM authentication

NOTE: SASL/SCRAM-SHA-256 authentication requires Materialize v26.0.0 or later.

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, update the following fields in the Materialize CR. For all Materialize CR settings, see here.

Configuration	Description
`spec.authenticatorKind`	Set to `Sasl` to enable SASL/SCRAM-SHA-256 authentication for PostgreSQL connections.
`external_login_password_mz_system`	Set 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 ¹, who is the only user initially available when SASL authentication is enabled.

An example Materialize CR 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:

Login as the mz_system user using the external_login_password_mz_system password
Use CREATE ROLE ... WITH LOGIN PASSWORD ... 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, connection poolers) 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.

Deploying authentication

Using the configured Materialize CR YAML file, we recommend rolling out the changes by adding the following fields:

spec:
  ...
  requestRollout: <SOME_NEW_UUID> # Generate new UUID for rollout
  forceRollout: <SOME_NEW_UUID> # Rollout without requiring a version change

For more information on rollout configuration, view our installation overview.

WARNING! Ensure that the authenticatorKind field is set for any future version upgrades or rollouts of the Materialize CR. Having it undefined will reset authenticationKind to None.

Enabling RBAC

See Access Control for details on role based authorization.

The mz_system user is also used by the Materialize Operator for upgrades and maintenance tasks. ↩︎ ↩︎ ↩︎