[litiliu]

Purpose

Linked issue: close #3829

Allow authentication mechanisms to return user, group, and role principals through one Iterable<FlussPrincipal> createPrincipals() contract. An authenticated session carries one collection of principals for authorization.

Brief change log

• Replace ServerAuthenticator.createPrincipal() with createPrincipals() and remove the separate additional-principals API.
• Snapshot all authenticated principals in FlussRequest and Session.
• Evaluate ACL and superuser matches against all session principals, independently of iteration order, while retaining one ACL cache snapshot per authorization operation.
• Use the first principal as the client identity for logging, user metrics, and resource ownership.
• Adapt PLAINTEXT, SASL/PLAIN, the SASL mechanism delegate, Kafka PLAIN, and test authenticators to the new contract.
• Update security documentation with authorization semantics and custom authenticator migration guidance.

Tests

112 focused tests passed with no failures, errors, or skips.

• Focused unit and integration suites: AuthenticationFactoryTest, PlainSaslServerTest, SaslAuthenticatorFactoryTest, AuthenticationTest, SessionTest, RequestChannelTest, DefaultAuthorizerTest, SaslAuthenticationITCase, FlussAuthorizationITCase, KafkaSaslConnectionTest, KafkaSaslConfigTest, and KafkaSaslPlainAuthenticationITCase.
• Coverage includes immutable snapshots from an arbitrary iterable, group ACL matching, principal-type mismatches, superuser matching at different collection positions, and existing client authorization and Kafka PLAIN behavior.
• Affected-module compilation and packaging, Checkstyle, Spotless, Apache RAT, and git diff --check.

API and Format

This changes the PublicEvolving ServerAuthenticator interface. Custom implementations must replace createPrincipal() with Iterable<FlussPrincipal> createPrincipals() and be recompiled. Single-identity mechanisms can return Collections.singletonList(principal). The iterable must be non-null and non-empty, without null elements.

All authenticated principals participate in ACL and superuser checks. The first principal remains the client identity for logging, user metrics, and resource ownership.

No RPC wire format or storage format changes.

Documentation

Updated the authorization and security overview documentation, including the custom authenticator migration contract.

[litiliu]

@loserwang1024 Please help review this PR when you have time, Thanks in advance!

[litiliu]

@affo Please take a look when you have time, Thanks!

[litiliu]

@polyzos PTAL, Thanks!

[affo]

Hello and thanks for the amazing contribution!
While the contribution holds valuable, this looks to me as a divergence from the original https://cwiki.apache.org/confluence/spaces/FLUSS/pages/372214350/FIP-2+Fluss+Authentication+and+Authorization in that it replaces a single-principal model with a multi-principal model. It also touches a PublicEvolving interface.
I would favor an explicit FIP round, or even something lighter, but disclosed to the entire community in order to change the model.

For example, why having the concept of "additional principals" and not change FlussPrincipal createPrincipal(); to Iterable<FlussPrincipal> createPrincipals();?

Maybe I am just being picky, I suggest to involve into this review a committer/PMC with a solid grasp of this part of the codebase 🤝

[github-actions]

This PR has been marked as stale because it has had no activity for 60 days. It will be closed in 10 days unless it receives a new comment, commit or other update.

[litiliu]

@loserwang1024 I've merged the latest main and resolved the conflicts, preserving ACL snapshot consistency for primary and additional principals. Authentication and ACL authorization tests pass. Could you please help review this PR when you have time? Thanks!