apache / apache/fluss

[security] Support group-based ACL authorization for authenticated identities

Open
#3,829 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Java
Stars
2.1k
Forks
625
Avg merge
3d 14h
Merged PRs (30d)
97

Description

### Search before asking

- [x] I searched in the [issues](https://github.com/apache/fluss/issues) and found nothing similar.

### Motivation

Fluss ACL entries can represent principals such as `User`, `Group`, and `Role`, but the current authentication and authorization path only carries and evaluates one `FlussPrincipal`.

For example, SASL/PLAIN always creates one `User` principal from the authorization ID. `Session` stores only that principal, and `DefaultAuthorizer` evaluates ACLs only against `session.getPrincipal()`.

This prevents an authenticated identity from carrying group membership such as:

```text
User:alice
Group:data-engineers
Group:fluss-readers
```

This is particularly relevant to [#3495](https://github.com/apache/fluss/issues/3495), where a validated JWT can provide the user identity through `sub` and group membership through a `groups` claim. Mapping only `sub` to a single `FlussPrincipal` cannot support group-based ACL policies.

This feature should provide authentication-mechanism-independent support for additional principals. It should be usable by OAUTHBEARER, Kerberos, mTLS, LDAP, and custom authentication plugins rather than being implemented only inside the OAuth mechanism.

Related design: [FIP-2: Fluss Authentication and Authorization](https://cwiki.apache.org/confluence/display/FLUSS/FIP-2%3A+Fluss+Authentication+and+Authorization).

### Solution

Extend the authenticated session identity from one primary principal to:

- One primary principal, preserving the existing `Session#getPrincipal()` behavior.
- Zero or more additional principals, such as `Group` or `Role`.
- An immutable, validated, and deduplicated collection of all authenticated principals.

Preserve source compatibility for existing authentication plugins, for example through a default server-authenticator method that returns no additional principals.

Update the default authorizer so an operation is allowed when the existing resource, operation, and host rules match an `ALLOW` ACL for any authenticated principal. Existing SASL/PLAIN behavior must remain unchanged because it produces only the primary `User` principal.

OAUTHBEARER support from #3495 can then map:

```text
sub -> primary User principal
groups[] -> additional Group principals
```

The implementation should also define which identity is used for logs and user metrics, avoid logging JWTs or credentials, and bound the number and size of additional principals.

Add tests covering:

- Existing single-user SASL/PLAIN authorization behavior.
- Authorization granted through a Group ACL.
- Multiple groups where only one matches.
- No matching user or group ACL.
- Duplicate and empty group values.
- Preservation of resource, operation, and host matching.
- Backward compatibility for authentication plugins that return only one principal.

### Anything else?

This proposal adds group-based ACL authorization. It does not introduce a complete RBAC management system with role creation, user-to-role assignment, role hierarchies, or role lifecycle APIs. Those capabilities can be designed separately if needed.

### Willingness to contribute

- [x] I'm willing to submit a PR!

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading the FIP-2 design and tracing FlussPrincipal through Session, DefaultAuthorizer, SASL/PLAIN, and the server-authenticator path. Define the compatibility and identity semantics before implementing the authenticated-principal collection; done means the listed single-user, group, duplicate, matching, and plugin-compatibility tests pass without changing existing SASL/PLAIN behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
authentication, authorization, backend, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.