apache / apache/fluss

[TLS] Add mTLS authentication (certificate-based FlussPrincipal)

Open
#3,793 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.

### Description

Part of #3786 ([FIP-29: (m)TLS Support](https://cwiki.apache.org/confluence/spaces/FLUSS/pages/406620533/FIP-29+m+TLS+Support)).

**Wave 2** — depends on: SSL principal mapping (#3795), server pipeline integration (#3792).

Add mutual TLS as a new authentication mechanism — the server derives the authenticated `FlussPrincipal` from the client's X.509 certificate.

- `MutualTlsAuthenticationPlugin`, `MutualTlsClientAuthenticator`, `MutualTlsServerAuthenticator`, registered via the existing SPI (`META-INF/services`).
- Client authenticator returns a zero-length, non-null token on its first call — no real token exchange (the cert is presented at the TLS layer already); this just triggers the `AuthenticateRequest` round-trip so the server can extract the principal.
- Server authenticator reads the peer certificate from the connection's `SSLSession`, maps it via `SslPrincipalMapper` (#3795), returns `FlussPrincipal`; fails clearly if TLS isn't enabled on the connection.
- Non-breaking SPI addition: default method `SSLSession sslSession()` on `ServerAuthenticator.AuthenticateContext` (returns `null` for non-TLS connections).
- Per-listener `ClientAuth.REQUIRE` derivation: a listener whose `security.protocol.map` entry is `mTLS` now requires a client certificate — every other TLS listener stays encryption-only; no global `client.auth` option.
- `TlsAuthenticationITCase` — end-to-end mTLS handshake, principal derivation, and authorization test.

**Depends on:** SSL principal mapping (#3795), server pipeline integration (#3792).

_Estimated diff size: ~875 lines._

_(Note: narrower scope than originally drafted here — DN→principal mapping is now its own ticket, #3795.)_

### 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 existing authentication SPI, especially ServerAuthenticator.AuthenticateContext, and review dependent issues #3795 and #3792. Trace the mentioned MutualTlsAuthenticationPlugin, client and server authenticators, META-INF/services registration, and listener security.protocol.map handling. Run TlsAuthenticationITCase; done means mTLS handshake, principal derivation, authorization, and non-TLS behavior are covered.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
authentication, 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.