Authentication

By default, only SCRAM-SHA-256 is advertised to clients. The advertised mechanisms are controlled by korvet.broker.sasl.mechanisms (default SCRAM-SHA-256).

Enable SASL authentication in your Korvet configuration:

Or using environment variables:

PLAIN is not advertised by default. To use it, add it explicitly to korvet.broker.sasl.mechanisms. Because PLAIN transmits credentials without encryption, Korvet requires TLS to be enabled when PLAIN is advertised. Starting the broker with PLAIN advertised while korvet.broker.tls=false fails validation at startup with:

Clients using PLAIN must therefore connect with the SASL_SSL security protocol, not SASL_PLAINTEXT.

Add OAUTHBEARER to the advertised mechanisms and configure the identity provider. Because bearer tokens travel in the SASL exchange and are replayable if intercepted, Korvet requires TLS to be enabled when OAUTHBEARER is advertised — same as PLAIN. Starting the broker with OAUTHBEARER advertised while korvet.broker.tls=false fails validation at startup with:

issuer-uri and audience are required when OAUTHBEARER is advertised. The JWKS endpoint is resolved from <issuer-uri>/.well-known/openid-configuration unless jwks-uri is set. Only asymmetrically signed tokens (RSA and EC families) are accepted; unsigned (alg=none) and HMAC-signed tokens are rejected.

The claim named by korvet.broker.sasl.oauth.principal-claim (default sub) becomes the connection principal. Topic ACL rules apply to that principal exactly as they do for SCRAM usernames. Many IdPs use an opaque identifier for sub; point principal-claim at a human-friendly claim such as client_id or preferred_username if you prefer to write ACL rules against those.

Writing one ACL rule per workload principal does not scale when the IdP already organizes workloads into groups. Setting korvet.broker.sasl.oauth.groups-claim maps a token’s group claim onto ACL principals: each value g of the claim contributes the rules granted to the principal group:g, unioned with the rules granted to the principal claim’s value. Grants are allow-only, so the union is order-insensitive — an operation is allowed if the principal or any of its groups has been granted it. The policy is resolved once per (re)authentication.

The group: prefix is a reserved principal namespace: local SASL credentials and console usernames may not contain :, so a group principal can never collide with a literal username. SCRAM and PLAIN connections are unaffected — they always resolve exactly one principal.

Walkthrough with Keycloak groups:

Every token whose groups claim contains payments-team may now produce to orders; membership changes are managed entirely in the IdP and take effect at the next (re-)authentication — see the revocation window below.

The authenticated session is bounded by the smaller of the token’s exp claim and the korvet.broker.sasl.oauth.max-reauth cap (default 5 minutes). The broker returns the session lifetime in the SASL response (session_lifetime_ms), so compliant Kafka clients (2.2+) re-authenticate on the same connection with a fresh token before the deadline (KIP-368). A connection that keeps sending requests past the deadline without a successful re-authentication is closed.

Because tokens are validated locally against the IdP’s signing keys, IdP-side changes — disabling a client, removing it from a group — only take effect when the broker sees the next token. max-reauth bounds that revocation window: lower it for faster revocation at the cost of more frequent re-authentications. A per-token denylist is intentionally not provided.

Create a confidential client with the client-credentials grant in your realm:

The standard Java client fetches tokens itself using the client-credentials grant:

The client obtains a token from the IdP’s token endpoint at login (and again before each re-authentication); the broker never sees the client secret, only the resulting signed token.

Create the broker’s service principal and keytab in your KDC, then add GSSAPI to the advertised mechanisms and point Korvet at the keytab:

keytab-file and principal are required when GSSAPI is advertised; the broker logs in from the keytab at startup and fails fast if the keytab, principal, or Kerberos configuration (/etc/krb5.conf, or the file named by the java.security.krb5.conf system property) is invalid. GSSAPI tokens are not replayable secrets, so — matching Kafka — TLS is not mandatory for GSSAPI, though it is still recommended to encrypt message traffic. Only quality-of-protection auth is supported (no GSSAPI integrity or confidentiality layers), and tokens must arrive in SaslAuthenticate frames (any client from Kafka 0.10 on).

The authenticated Kerberos identity is mapped to its short name by keeping only the primary component: alice@EXAMPLE.COM and alice/host.example.com@EXAMPLE.COM both become alice. Topic ACL rules apply to the short name exactly as they do for SCRAM usernames — grant ACLs to alice, not the full principal. Kerberos carries no tenant identifier, so GSSAPI connections have no tenant id.

Use SASL_SSL instead of SASL_PLAINTEXT when the broker listener has TLS enabled. The client requests a ticket for <service-name>/<broker-host>@REALM, so every advertised broker host must have a matching service principal in the KDC (or in the broker keytab when all brokers share one).

When enabled is true, issuer-uri, client-id, audience, and at least one of roles.admin-group / roles.viewer-group are required; startup fails fast with a clear message otherwise. Endpoint and JWKS discovery is lazy, so the console starts (and password login works) even while the IdP is unreachable — only single sign-on attempts fail in that window.

The claim named by roles.claim (default groups) is read from the validated id_token. A user whose groups contain roles.admin-group signs in as ADMIN; otherwise a match on roles.viewer-group grants VIEWER; a user matching neither is rejected with a clear error on the login page. Role changes at the IdP take effect on the next login — the console session keeps the role it was minted with until it expires or is logged out.

In your realm (for example korvet):

Sign-out clears and revokes the local console session; IdP single logout is currently not propagated (signing in again while the IdP session is still alive will not prompt for credentials).

Credentials are stored in Redis using secure PBKDF2 password hashing:

Use the Korvet admin API or Redis CLI to create user credentials. The admin API (see Deployment for enabling it) exposes credential management over HTTP; the Redis CLI approach below is shown for direct access.

To update a user’s password, store a new credential with the same username:

Or using Redis CLI:

For PLAIN clients, use the SASL_SSL security protocol (PLAIN requires TLS) and Kafka’s PLAIN login module:

For PLAIN, set security.protocol=SASL_SSL, sasl.mechanism=PLAIN, and use the PlainLoginModule (PLAIN requires TLS).

Login attempts are rate-limited per username and client IP address:

Logging out revokes the session token immediately:

Legacy tokens without a jti claim (issued by versions before session revocation existed) are rejected and cannot be used.

Changing your own password requires the current password in the request (currentPassword); admin resets of other accounts must omit it. See Admin API for the endpoint details.

korvet.broker.acl.enabled requires korvet.broker.sasl.enabled=true; enabling ACLs without SASL fails validation at startup.

ACL rules are allow-only grants of the form (principal, resourceType, resource, operation):

Resource names match in one of three ways. The precedence below is documentation of intent — because rules are allow-only, a grant by any match allows the operation:

When ACL enforcement is enabled, a principal may only perform operations it has been granted; everything else — including resources with no rules at all — is denied with the standard Kafka error: TOPIC_AUTHORIZATION_FAILED (TopicAuthorizationException) for topics, GROUP_AUTHORIZATION_FAILED (GroupAuthorizationException) for consumer groups. Consuming through a group therefore needs both a TOPIC/READ grant for the topic and a GROUP/READ grant for the group id.

Rules are stored in Redis in a single JSON document at {namespace}:broker:acls, one member per principal. The principal’s policy is resolved once per connection at authentication time, so rule changes apply to connections established afterwards.

ACL rules are managed through the admin REST API. The pre-group request shape ({principal, topic, operation}) still works and creates a TOPIC rule:

SASL/PLAIN transmits credentials in base64 encoding (not encrypted). Korvet therefore requires TLS whenever PLAIN is advertised, so PLAIN clients must use the SASL_SSL security protocol. SCRAM-SHA-256 does not send the password and can be used over SASL_PLAINTEXT, though TLS is still recommended in production:

Enable debug logging for authentication:

To disable authentication:

Clients can then connect without authentication.