Skip to content

Commit cfe654a

Browse files
loserwang1024loserwang1024
committed
[docs] Add security documents including authentication and authorization.
1 parent 8317092 commit cfe654a

File tree

4 files changed

+365
-0
lines changed

4 files changed

+365
-0
lines changed

‎website/docs/security/_category_.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "Security",
3+
"position": 10
4+
}

‎website/docs/security/authentication.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
sidebar_label: Authentication
3+
title: Security Authentication
4+
sidebar_position: 2
5+
---
6+
7+
<!--
8+
Copyright (c) 2025 Alibaba Group Holding Ltd.
9+
10+
Licensed under the Apache License, Version 2.0 (the "License");
11+
you may not use this file except in compliance with the License.
12+
You may obtain a copy of the License at
13+
14+
http://www.apache.org/licenses/LICENSE-2.0
15+
16+
Unless required by applicable law or agreed to in writing, software
17+
distributed under the License is distributed on an "AS IS" BASIS,
18+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19+
See the License for the specific language governing permissions and
20+
limitations under the License.
21+
-->
22+
23+
# Authentication
24+
Fluss provides a pluggable authentication mechanism, allowing users to configure client and server authentication methods based on their security requirements.
25+
26+
## Overview
27+
Authentication in Fluss is handled through listeners, where each connection triggers a specific authentication protocol based on the configuration. Supported mechanisms include:
28+
* **PLAINTEXT**: Default, no authentication.
29+
* **SASL/PLAIN**: Username/password-based authentication.
30+
* **Custom plugins**: Extendable via interfaces for enterprise or third-party integrations.
31+
32+
You can configure different authentication protocols per listener using the `security.protocol.map` property.
33+
34+
## PLAINTEXT
35+
The PLAINTEXT authentication method is the default used by Fluss. It does not perform any identity verification and is suitable for:
36+
* Local development and debugging.
37+
* Internal communication within trusted clusters.
38+
* Lightweight deployments without access control.
39+
40+
No additional configuration is required for this mode.
41+
42+
## SAS/PLAIN
43+
SASL/PLAIN is a username/password-based authentication method that provides basic but effective security for production environments.
44+
45+
### sasl server related configuration
46+
| Property Name | Description | Default Value |
47+
|----------------------------------------------------------------|---------------------------------------------------------------------------| --- |
48+
| security.sasl.enabled.mechanisms | Comma-separated list of enabled SASL mechanisms (e.g., PLAIN). | PLAIN |
49+
| `security.sasl.listener.name.{listenerName}.plain.jaas.config` | JAAS configuration for a specific listener and mechanism. | (none) | | (none) |
50+
| `security.sasl.plain.jaas.config` | Global JAAS configuration for all listeners using the PLAIN mechanism. | (none) | | |
51+
52+
⚠️ The system tries to load JAAS configurations in the following order:
53+
1. Listener-specific config: `security.sasl.listener.name.{listenerName}.{mechanism}.jaas.config`
54+
2. Mechanism-wide config: `security.sasl.{mechanism}.jaas.config`
55+
3. System-level fallback: `-Djava.security.auth.login.config` JVM option
56+
57+
58+
59+
60+
Here is an example that Port 9093 requires SASL/PLAIN authentication with who user "admin" and "fluss":
61+
```yaml title="conf/server.yaml"
62+
# port 9092 use SASL authentication for clients
63+
listeners: INTERNAL://localhost:9092, CLIENT://localhost:9093
64+
advertised.listeners: CLIENT://host1:9093, INTERNAL://host2:9092
65+
security.protocol.map: CLIENT:SASL, INTERNAL:PLAINTEXT
66+
internal.listener.name: INTERNAL
67+
# use SASL/PLAIN
68+
security.sasl.enabled.mechanisms: PLAIN
69+
security.sasl.plain.jaas.config: com.alibaba.fluss.security.auth.sasl.plain.PlainLoginModule required user_admin="admin-pass" user_fluss="fluss-pass";
70+
```
71+
72+
73+
### sasl client related configuration
74+
Clients must specify the appropriate security protocol and authentication mechanism when connecting to Fluss brokers.
75+
76+
| Property Name | Description | Default Value |
77+
| --- | --- |-----------------------------------------------------------------------|
78+
| client.security.protocol | The security protocol used to communicate with brokers. | PLAINTEXT |
79+
| client.security.sasl.mechanism | The SASL mechanism used for authentication. Only support PLAIN now, but will support more mechanisms in the future. | (none) |
80+
| client.security.sasl.jaas.config | JAAS configuration for SASL. If not set, falls back to system property -Djava.security.auth.login.config. |
81+
82+
83+
Here is an example client configuration(flink catalog):
84+
```sql title="Flink SQL"
85+
CREATE CATALOG fluss_catalog WITH (
86+
'type' = 'fluss',
87+
'bootstrap.servers' = 'fluss-server-1:9123',
88+
'client.security.protocol' = 'SASL',
89+
'client.sasl.mechanism' = 'PLAIN',
90+
'client.sasl.jaas.plain.config' = 'com.alibaba.fluss.security.auth.sasl.plain.PlainLoginModule required username="fluss" password="fluss-pass";'
91+
);
92+
```
93+
94+
95+
## Extending Authentication Methods (For Developers)
96+
97+
Fluss supports custom authentication logic through its plugin architecture.
98+
99+
Steps to implement a custom authenticator:
100+
1. **Implement AuthenticationPlugin Interfaces**: Implement ClientAuthenticationPlugin for client-side logic and implement ServerAuthenticationPlugin for server-side logic.
101+
2. **Package the Plugin**: Compile your implementation into a JAR file, and then place it in the Fluss plugin directory for automatic loading.
102+
3. **Enable the Plugin**: Configure the desired protocol via:
103+
* `security.protocol.map` – for server-side listener authentication.
104+
* `client.security.protocol` – for client-side authentication.

‎website/docs/security/authorization.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
sidebar_label: Authorization
3+
title: Security Authorization
4+
sidebar_position: 3
5+
---
6+
7+
<!--
8+
Copyright (c) 2025 Alibaba Group Holding Ltd.
9+
10+
Licensed under the Apache License, Version 2.0 (the "License");
11+
you may not use this file except in compliance with the License.
12+
You may obtain a copy of the License at
13+
14+
http://www.apache.org/licenses/LICENSE-2.0
15+
16+
Unless required by applicable law or agreed to in writing, software
17+
distributed under the License is distributed on an "AS IS" BASIS,
18+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19+
See the License for the specific language governing permissions and
20+
limitations under the License.
21+
-->
22+
23+
# Authorization
24+
25+
## Configuration
26+
Fluss provides a pluggable authorization framework that uses Access Control Lists (ACLs) to determine whether a given FlussPrincipal is allowed to perform an operation on a specific resource.
27+
28+
29+
| Property Name | Description | Default Value |
30+
|--------------------|------------------------------------------------------------------|---------------|
31+
| authorizer.enabled | Specifies whether to enable the authorization feature. | false |
32+
| authorizer.type | Specifies the type of authorizer to be used for access control. This value corresponds to the identifier of the authorization plugin. The default value is `default`, which indicates the built-in authorizer implementation. Custom authorizers can be implemented by providing a matching plugin identifier.| default |
33+
| super.users | A semicolon-separated list of superusers who have unrestricted access to all operations and resources. Each super user should be specified in the format `principal_type:principal_name`, e.g., `User:admin;User:bob`, This configuration is critical for defining administrative privileges in the system. | (none) |
34+
35+
## Core Components of ACLs
36+
37+
Fluss uses an Access Control List (ACL) mechanism to enforce fine-grained permissions on resources such as clusters, databases, and tables. This allows administrators to define who (principals) can perform what actions (operations) on which objects (resources).
38+
39+
Fluss ACLs are defined in the general format:
40+
```
41+
Principal {P} is [Allowed|Denied] Operation {O} From Host {H} on any Resource {R}.
42+
```
43+
44+
### Resource
45+
In Fluss, a Resource represents an object to which access control can be applied. **Resources are organized in a hierarchical structure**, enabling fine-grained permission management as well as permission inheritance from higher-level scopes (e.g., database-level permissions apply to all tables within that database).
46+
47+
There are three main types of resources:
48+
| Resource Type | Resource Name Format Example | Description |
49+
| --- | --- | --- |
50+
| Cluster | fluss-cluster | The cluster resource represents the entire Fluss cluster and is used for cluster-wide permissions. |
51+
| Database | default_db | A database resource represents a specific database within the Fluss cluster and is used for database-level permissions. |
52+
| Table | default_db.default_table | A table resource represents a specific table within a database and is used for table-level permissions. |
53+
54+
This hierarchy follows this pattern:
55+
```text
56+
Cluster
57+
└── Database
58+
└── Table
59+
```
60+
61+
### Operation
62+
In Fluss, an OperationType defines the type of action a principal (user or role) is attempting to perform on a resource (cluster, database, or table).
63+
64+
| Operation Type | Description |
65+
|----------------| --- |
66+
| ANY | Matches any operation type and is used exclusively in filters or queries to match ACL entries. It should not be used when granting actual permissions.|
67+
| ALL | Grants permission for all operations on a resource. |
68+
| READ | Allows reading data from a resource (e.g., querying tables).|
69+
| WRITE | Allows writing data to a resource (e.g., inserting or updating data in tables).|
70+
| CREATE | Allows creating a new resource (e.g., creating a new database or table).|
71+
| DELETE | Allows deleting a resource (e.g., deleting a database or table).|
72+
| ALTER | Allows modifying the structure of a resource (e.g., altering the schema of a table).|
73+
| DESCRIBE | Allows describing a resource (e.g., retrieving metadata about a table).|
74+
75+
76+
Fluss implements a permission inheritance model, where certain operations imply others. This helps reduce redundancy in ACL rules by avoiding the need to explicitly grant every low-level permission.
77+
* ALL implies all other operations.
78+
* READ, WRITE, CREATE, DROP, ALTER each imply DESCRIBE.
79+
80+
### Fluss Principal
81+
The FlussPrincipal is a core concept in the Fluss security architecture. It represents the identity of an authenticated entity (such as a user or service) and serves as the central bridge between authentication and authorization.Once a client successfully authenticates via a supported mechanism (e.g., SASL/PLAIN, Kerberos), a FlussPrincipal is created to represent that client's identity.
82+
This principal is then used throughout the system for access control decisions, linking who the user is with what they are allowed to do.
83+
84+
The principal type indicates the category of the principal (e. g., "User", "Group", "Role"), while the name identifies the specific entity within that category. By default, the simple authorizer uses "User" as the principal type, but custom authorizers can extend this to support role-based or group-based access control lists (ACLs).
85+
Example usage:
86+
* `new FlussPrincipal("admin", "User")` – A standard user principal.
87+
* `new FlussPrincipal("admins", "Group")` – A group-based principal for authorization.
88+
89+
## Operations and Resources on Protocols
90+
Below is a summary of the currently public protocols and their relationship with operations and resource types:
91+
| Protocol | Operations | Resources | Note |
92+
| --- | --- | --- | --- |
93+
| CREATE_DATABASE | CREATE | Cluster | |
94+
| DROP_DATABASE | DELETE | Database | |
95+
| LIST_DATABASES | DESCIBE | Database | Only databases that the user has permission to access are returned. Databases for which the user lacks sufficient privileges are automatically filtered from the results. |
96+
| CREATE_TABLE | CREATE | Database | |
97+
| DROP_TABLE | DELETE | Table | |
98+
| GET_TABLE_INFO | DESCRIBE | Table | |
99+
| LIST_TABLES | DESCRIBE | Table | Only tables that the user has permission to access are returned. Tables for which the user lacks sufficient privileges are automatically filtered from the results. |
100+
| LIST_PARTITION_INFOS | DESCRIBE | Table | Only partitions that the user has permission to access are returned. Partitions for which the user lacks sufficient privileges are automatically filtered from the results. |
101+
| GET_METADATA | DESCRIBE | Table | Only metadata that the user has permission to access is returned. Metadata for which the user lacks sufficient privileges is automatically filtered from the results.|
102+
| PRODUCE_LOG | WRITE | Table | |
103+
| FETCH_LOG | READ | Table | |
104+
| PUT_KV | Write | Cluster | |
105+
| LOOKUP | Read | Cluster | |
106+
| INIT_WRITER | READ | TABLE | |
107+
| LIMIT_SCAN | READ | TABLE | |
108+
| PREFIX_LOOKUP | READ | TABLE | |
109+
| GET_DATABASE_INFO | DESCRIBE | Database | |
110+
| CREATE_PARTITION | WRITE | Table | |
111+
| DROP_PARTITION | DELETE | Table | |
112+
| CREATE_ACLS | ALTER | Cluster | |
113+
| DROP_ACLS | ALTER | Cluster | |
114+
| LIST_ACLS | DESCRIBE | Cluster | |
115+
116+
## ACL Operation
117+
Fluss provides a FLINK SQL interface to manage Access Control Lists (ACLs) using the Flink CALL statement. This allows administrators and users to dynamically control access permissions for principals (users or roles) on various resources such as clusters, databases, and tables.
118+
119+
The general syntax is:
120+
```sql title="Flink SQL"
121+
-- -- Use named argument
122+
CALL [catalog].sys.acl( action => 'LIST', resource => '%s', permission => 'ALLOW', principal => '%s', operation => '%s');
123+
124+
-- Use indexed argument
125+
CALL [catalog].sys.acl(
126+
'[action]',
127+
'[resource_type.resource_name]',
128+
'[permission]'
129+
'[principal_type:principal_name]',
130+
'[operation_type]'
131+
);
132+
```
133+
134+
| Parameter | Description |
135+
|----------|---------------------------------------------------------------------------------------------------------------------------------|
136+
| action | The action to perform on the ACL. One of: 'ADD', 'DROP', 'LIST' |
137+
| resource | The resource to apply the ACL to (e.g., fluss-cluster, fluss-cluster.db1, fluss-cluster.db1.table1) |
138+
| permission | The permission to grant or deny to the principal on the resource (e.g., ALLOW, DENY) | |
139+
| principal | The principal to apply the ACL to (e.g., user:alice, role:admin) |
140+
| operation | The operation to allow or deny for the principal on the resource (e.g., READ, WRITE, CREATE, DELETE, ALTER, DESCRIBE, ANY, ALL) |
141+

0 commit comments

Comments
 (0)