Add support for different claims for authentication by prashah-confluent · Pull Request #5336 · confluentinc/librdkafka

pranav shah (prashah-confluent) · 2026-03-02T03:57:35Z

PR description

Problem

For OIDC / SASL_OAUTHBEARER flows using librdkafka’s built‑in OIDC helper, we currently hard‑require that the JWT payload contain a sub claim. If the IdP omits sub or uses another claim (for example client_id) as the primary subject, librdkafka fails token acquisition with an error such as:

Failed to acquire SASL OAUTHBEARER token: Expected JSON JWT response with "sub" field

Fix

We have introduced a new config sub_claim_name using which customers can provide a different claim. The claim value will be honored and used for client side validation.

Note
Requires users to keep broker and client configs aligned for the subject claim name to avoid confusion and consistency.

Testing

Unit tests

To test the core JWT payload parsing and claim extraction logic inside rd_kafka_oidc_token_try_validate() in isolation (no broker, network, oidc server).

Default Configuration & Backward Compatibility
Implicit Default Behavior: Validate that when sub.claim.name is not provided, the system defaults to extracting the subject from the "sub" claim.
Legacy Parity: Ensure that existing JWTs containing only the "sub" claim continue to be processed correctly, maintaining no regressions for standard OIDC flows.
Explicit Claim Configuration (KIP-768 Parity)
Custom Claim Extraction: Verify that setting sub.claim.name (e.g., to client_id) successfully extracts the value from the specified field instead of the hardcoded "sub" key.
Configuration Precedence: Test that when both "sub" and a custom claim (e.g., "client_id") coexist in a JWT, the system honors the user-defined configuration over the OIDC default.
Error Handling & Validation Logic
Missing Claim Detection: Verify that providing a sub.claim.name that does not exist in the JWT triggers a specific "Claim not found" error, rather than failing on a hardcoded "sub".
Empty Value Rejection: Ensure the system rejects empty string subjects with a "non-empty value required" error, addressing previous bugs where empty strings passed silently.
Invalid Configuration Recovery: Validate that if sub.claim.name is set to an empty string, the system gracefully falls back to the OIDC default ("sub") to ensure continuous operation.
librdkafka & Java Client Alignment
Functional Parity: Ensure all scenarios are cross-validated against the Java KIP-768 implementation to guarantee identical extraction logic and exception triggers (e.g., ValidateException equivalents).

Integration tests

To validate end-to-end OIDC authentication against a real Kafka cluster (via trivup) with different sasl.oauthbearer.sub.claim.name configurations
The trivup setup requires changes for returning JWT response with multiple claims

Design Doc

confluent-cla-assistant · 2026-03-02T03:57:45Z

🎉 All Contributor License Agreements have been signed. Ready to merge.
_{Please push an empty commit if you would like to re-run the checks to verify CLA status for all contributors.}

…ts.txt

Emanuele Sabellico (emasab)

Thanks Pranav! This is my feedback:

Emanuele Sabellico (emasab) · 2026-03-12T11:55:08Z

src/rdkafka_conf.c

+     "JWT claim name to use as the subject (principal) when validating "
+     "OIDC access tokens. Must be present in the JWT payload with a "
+     "non-empty value. Should match the broker's "
+     "sasl.oauthbearer.sub.claim.name configuration for consistent "


Suggested change

"sasl.oauthbearer.sub.claim.name configuration for consistent "

"`sasl.oauthbearer.sub.claim.name` configuration for consistent "

rebuild CONFIGURATION.md as well.

Changed to "sasl.oauthbearer.sub.claim.name" and rebuilt CONFIGURATION.md

Emanuele Sabellico (emasab) · 2026-03-12T12:03:06Z

src/rdkafka_sasl_oauthbearer_oidc.c

+        /* Safety check to default to "sub" if not set */
+        if (!sub_claim_name || !*sub_claim_name)
+                sub_claim_name = "sub";


it shoud be a rd_dassert here, not reverting to the default. The configuration should be validated in rd_kafka_conf_finalize_oauthbearer_oidc and using rd_kafka_conf_is_modified on the field and then check for NULL or a an empty string or whitespace string ("\s+") you can write a function like the Java method ClaimValidationUtils.validateString.

Added rd_dassert and as suggested added helper api which validates string only if config is modified.

Emanuele Sabellico (emasab) · 2026-03-12T12:05:22Z

tests/0126-oauthbearer_oidc.c

+                        do_test_produce_consumer_with_OIDC(test_name,
+                                                           sub_claim_conf);
+                } else {
+                        /* These variations should fail due to missing claim */


This function should be agnostic to the failure cause (at the moment it's only this one but in future there can be other test cases).

Suggested change

/* These variations should fail due to missing claim */

/* These variations should fail */

Modified the comment to make the function failure agnostic

Emanuele Sabellico (emasab) · 2026-03-12T12:07:12Z

CHANGELOG.md

+
+librdkafka v2.14.0 is a feature release:
+
+* [KIP-768](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=186877575#KIP768:ExtendSASL/OAUTHBEARERwithSupportforOIDC-ClientConfiguration) Extend SASL/OAUTHBEARER to support OIDC claim mapping beyond the default `sub` claim [(#5336)](https://github.com/confluentinc/librdkafka/pull/5336)


Suggested change

* [KIP-768](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=186877575#KIP768:ExtendSASL/OAUTHBEARERwithSupportforOIDC-ClientConfiguration) Extend SASL/OAUTHBEARER to support OIDC claim mapping beyond the default `sub` claim [(#5336)](https://github.com/confluentinc/librdkafka/pull/5336)

* [KIP-768](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=186877575#KIP768:ExtendSASL/OAUTHBEARERwithSupportforOIDC-ClientConfiguration) Extend SASL/OAUTHBEARER to support OIDC claim mapping beyond the default `sub` claim (#5336).

The link is already added by GH in the release page, so we don't put the link here.

Removed the link

Emanuele Sabellico (emasab) · 2026-03-12T12:09:46Z

src/rdkafka_sasl_oauthbearer_oidc.c

+            {"NULL sub_claim_name defaults to 'sub'", UT_JWT_SUB_ONLY, NULL,
+             rd_true, "subject"},
+            {"Empty sub_claim_name defaults to 'sub'", UT_JWT_SUB_ONLY, "",
+             rd_true, "subject"},


We can remove these two cases after putting an assert there as it must not reach this function if those preconditions aren't satisfied.

Suggested change

{"NULL sub_claim_name defaults to 'sub'", UT_JWT_SUB_ONLY, NULL,

rd_true, "subject"},

{"Empty sub_claim_name defaults to 'sub'", UT_JWT_SUB_ONLY, "",

rd_true, "subject"},

Removed the test cases since they can't be valid at this point.

Emanuele Sabellico (emasab) · 2026-03-12T12:12:26Z

tests/0126-oauthbearer_oidc.c

+        case OIDC_CONFIGURATION_SUB_CLAIM_VARIATION_EMPTY_STRING:
+                test_conf_set(conf, "sasl.oauthbearer.sub.claim.name", "");
+                break;


This one should fail as well. Similarly to the Java client, in case it's set it should be valid otherwise the user could want to set something but there was a bug in their code so an empty string was received instead.

This should pass due to librdkafka convention which sets the config to default values if empty/NULL string is provided.

pranav shah (prashah-confluent) added 5 commits March 2, 2026 08:06

Add documentation for new sub claim config

fa126b4

Add new config in rdkafka_conf

9367a9b

Modify logic based on subclaim name value

442bf87

Add unit tests

47588bd

Fix style format errors for the modified files

16b6a39

pranav shah (prashah-confluent) added 3 commits March 3, 2026 11:15

Add integration tests for sub claim name

d9b9195

Fix style check for 0126-oauthbearer_oidc

0172920

Add new trivup version 0.15.0 and update the dependency in requiremen…

f3c70a2

…ts.txt

pranav shah (prashah-confluent) marked this pull request as ready for review March 4, 2026 12:19

pranav shah (prashah-confluent) requested a review from a team as a code owner March 4, 2026 12:19

pranav shah (prashah-confluent) added 2 commits March 4, 2026 17:52

Remove redundant comments

c3dd826

Update Change log

6b53ca4

pranav shah (prashah-confluent) assigned pranav shah (prashah-confluent) and Emanuele Sabellico (emasab) and unassigned pranav shah (prashah-confluent) and Emanuele Sabellico (emasab) Mar 10, 2026

pranav shah (prashah-confluent) requested a review from Emanuele Sabellico (emasab) March 10, 2026 04:58

Emanuele Sabellico (emasab) mentioned this pull request Mar 12, 2026

How to set oauthbearer.sub.claim.name for OIDC/oauth #4985

Open

Emanuele Sabellico (emasab) requested changes Mar 12, 2026

View reviewed changes

pranav shah (prashah-confluent) added 10 commits March 12, 2026 18:22

Remove the link for PR as GH adds it automatically

d00ec20

Add validation for subclaim string configuration

6b36a83

Remove tests as preconditions will already be validated before

583981b

Function should fail agnostic of reason. Corrected the comment

4d3c24d

Modify integration test to fail at configuration finalization

3c3b9bf

Fix comment for configuration.md consistency

92e16bd

Add back the default value for sub_claim_name configuration

e11f97c

Rebuilt CONFIGURATION.md and fix style check

2b16b0c

Fix style check

432fca4

Add unit tests for rd_kafka_conf_validate_str

2d1d8c3

Fix style check

3822efb

	"sasl.oauthbearer.sub.claim.name configuration for consistent "
	"`sasl.oauthbearer.sub.claim.name` configuration for consistent "

	/* These variations should fail due to missing claim */
	/* These variations should fail */


		librdkafka v2.14.0 is a feature release:

		* [KIP-768](https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=186877575#KIP768:ExtendSASL/OAUTHBEARERwithSupportforOIDC-ClientConfiguration) Extend SASL/OAUTHBEARER to support OIDC claim mapping beyond the default `sub` claim [(#5336)](https://github.com/confluentinc/librdkafka/pull/5336)

Conversation

pranav shah (prashah-confluent) commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR description

Problem

Fix

Testing

Unit tests

Integration tests

Uh oh!

confluent-cla-assistant bot commented Mar 2, 2026

Uh oh!

Emanuele Sabellico (emasab) left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pranav shah (prashah-confluent) Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

pranav shah (prashah-confluent) commented Mar 2, 2026 •

edited

Loading

pranav shah (prashah-confluent) Mar 13, 2026 •

edited

Loading