(fluss) branch main updated: [docs] Document security.sasl.plain.credentials for multi-user SASL/PLAIN (#4168)

[ho...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

loserwang1024 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fluss.git


The following commit(s) were added to refs/heads/main by this push:
     new 3fea920cfa [docs] Document security.sasl.plain.credentials for multi-user SASL/PLAIN (#4168)
3fea920cfa is described below

commit 3fea920cfab2f5acb48893766efe3c1e3fdc7f99
Author: Keith Lee <le...@apache.org>
AuthorDate: Tue Sep 8 03:49:28 2026 +0100

    [docs] Document security.sasl.plain.credentials for multi-user SASL/PLAIN (#4168)
---
 .../maintenance/operations/updating-configs.md     |  1 +
 website/docs/security/authentication.md            | 33 ++++++++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/website/docs/maintenance/operations/updating-configs.md b/website/docs/maintenance/operations/updating-configs.md
index f6d3b12e38..7b32f3ee0c 100644
--- a/website/docs/maintenance/operations/updating-configs.md
+++ b/website/docs/maintenance/operations/updating-configs.md
@@ -21,6 +21,7 @@ Currently, the supported dynamically updatable server configurations include:
 - `datalake.format`: Specify the lakehouse format, e.g., `paimon`, `iceberg`. When enabling lakehouse storage explicitly, use it together with `datalake.enabled = true`.
 - Options with prefix `datalake.${datalake.format}`
 - `kv.rocksdb.shared-rate-limiter.bytes-per-sec`: Control RocksDB flush and compaction write rate shared across all RocksDB instances on the TabletServer. The rate limiter is always enabled. Set to a lower value (e.g., 100MB) to limit the rate, or a very high value to effectively disable rate limiting.
+- `security.sasl.plain.credentials`: Add, change, or remove the users that can authenticate with SASL/PLAIN, see [Authentication](security/authentication.md#managing-multiple-users).
 
 
 You can update the configuration of a cluster with [Java client](#using-java-client) or [Flink SQL](#using-flink-sql).
diff --git a/website/docs/security/authentication.md b/website/docs/security/authentication.md
index f4a661bd09..1879b0e9fa 100644
--- a/website/docs/security/authentication.md
+++ b/website/docs/security/authentication.md
@@ -32,6 +32,7 @@ This mechanism is based on SASL (Simple Authentication and Security Layer) authe
 | security.sasl.enabled.mechanisms                               | List   | PLAIN         | Comma-separated list of enabled SASL mechanisms. Only support PLAIN(which involves authentication using a username and password) now. |
 | `security.sasl.listener.name.{listenerName}.plain.jaas.config` | String | (none)        | JAAS configuration for a specific listener and PLAIN mechanism.                                                                       |
 | `security.sasl.plain.jaas.config`                              | String | (none)        | Global JAAS configuration for all listeners using the PLAIN mechanism.                                                                |
+| `security.sasl.plain.credentials`                              | Map    | (none)        | Map of users in `username:password` format, e.g. `admin:admin-secret,bob:bob-secret`. Syntactic sugar that generates the PLAIN JAAS config, and can be updated without a restart. |
 
 
 ⚠️ The system tries to load JAAS configurations in the following order:
@@ -52,6 +53,38 @@ security.sasl.plain.jaas.config: org.apache.fluss.security.auth.sasl.plain.Plain
 ```
 
 
+### Managing Multiple Users
+Instead of writing a JAAS config string by hand, you can declare users with the map option `security.sasl.plain.credentials`.
+Fluss generates the equivalent `security.sasl.plain.jaas.config` from it, so the example above can be written as:
+
+```yaml title="conf/server.yaml"
+security.sasl.enabled.mechanisms: PLAIN
+security.sasl.plain.credentials: admin:admin-pass,fluss:fluss-pass
+```
+
+Usernames may only contain letters, digits, and underscores, because they become part of the JAAS option key `user_<username>`.
+Passwords may not contain commas, colons, double quotes, semicolons, backslashes, or control characters, since these would break the map format or the generated JAAS config string.
+
+Unlike `security.sasl.plain.jaas.config`, this option is a [dynamic cluster config](maintenance/operations/updating-configs.md#updating-cluster-configs): users can be added, changed, and removed on a running cluster, and the change takes effect for new connections on all servers.
+
+```sql title="Flink SQL"
+-- Add user "bob"
+CALL sys.append_cluster_configs(
+  config_pairs => 'security.sasl.plain.credentials', 'bob:bob-secret'
+);
+
+-- Remove user "bob" (the supplied secret is ignored, removal matches on the username)
+CALL sys.subtract_cluster_configs(
+  config_pairs => 'security.sasl.plain.credentials', 'bob:any-secret'
+);
+```
+
+Note the following when using both options together:
+* Users defined in the `security.sasl.plain.jaas.config` of `conf/server.yaml` stay valid; the credentials map is merged on top of them and wins on a username conflict. Removing a user from the map therefore only revokes it if the user is not also defined in `conf/server.yaml`.
+* The map applies to the mechanism-wide JAAS config only. A listener that sets `security.sasl.listener.name.{listenerName}.plain.jaas.config` keeps using that config and ignores the map.
+* Passwords are redacted when configs are read back, for example via `sys.get_cluster_configs`.
+
+
 ### SASL Client-Side Configuration
 Clients must specify the appropriate security protocol and authentication mechanism when connecting to Fluss brokers.