OIDC: Essential claims parameter not supported #9

New Issue

2026-01-02T23:50:19Z

Claude commented

2026-01-02 23:50:19 +00:00

Issue

The OIDC claims parameter is not being captured or used, causing a WARNING in the OpenID Connect conformance test suite (test: oidcc-claims-essential).

Background

Per OIDC Core §5.5, the claims parameter allows clients to request specific claims with optional essential flags:

claims={"userinfo":{"name":{"essential":true}}}

This tells the IdP: "I specifically need the name claim for this app to function."

Current Behavior

The claims parameter is never captured in the authorize endpoint (app/controllers/oidc_controller.rb:59-320)
The consent screen only shows scopes, not individual claims
Essential claims are never highlighted to users
Userinfo only returns claims based on scope, ignoring the claims parameter

Test Results

WARNING OIDCC-5.5  OIDCC-5.5.1  EnsureUserInfoContainsName: name not found in userinfo

The test passes (SUCCESS) but with a WARNING because the essential name claim was not returned.

Privacy Consideration

This is arguably correct behavior for a privacy-preserving IdP. Per Connect2ID's documentation:

"How the IdP determines which claims to release and which not is up to its policy."

The essential flag is the client's way of saying "I need this" - it doesn't force the IdP to share data without proper consent.

Options

A) Accept the warning (current approach, minimal changes)

Keep current behavior
Only return claims based on consented scopes
Privacy-first approach

B) Full essential claims support

Add claims column to oidc_authorization_codes and oidc_access_tokens tables
Capture claims parameter in authorize endpoint
Show essential claims on consent screen (e.g., "This app requires: name")
Return essential claims even without corresponding scope (after consent)

C) UX-only improvement

Capture claims parameter
Show essential claims on consent screen as informational
Still require proper scope consent before returning claims
Doesn't change data sharing behavior, just improves transparency

Recommendation

Start with Option C (UX-only improvement) to improve user transparency without changing privacy behavior. This:

Shows users what the app is requesting (including essential claims)
Maintains privacy-first approach (consent = scope-based)
Makes the consent screen more informative
Could trigger re-consent if new essential claims are requested

## Issue The OIDC `claims` parameter is not being captured or used, causing a WARNING in the OpenID Connect conformance test suite (test: `oidcc-claims-essential`). ## Background Per [OIDC Core §5.5](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter), the `claims` parameter allows clients to request specific claims with optional `essential` flags: ``` claims={"userinfo":{"name":{"essential":true}}} ``` This tells the IdP: "I specifically need the `name` claim for this app to function." ## Current Behavior 1. The `claims` parameter is never captured in the authorize endpoint (`app/controllers/oidc_controller.rb:59-320`) 2. The consent screen only shows scopes, not individual claims 3. Essential claims are never highlighted to users 4. Userinfo only returns claims based on scope, ignoring the `claims` parameter ## Test Results ``` WARNING OIDCC-5.5 OIDCC-5.5.1 EnsureUserInfoContainsName: name not found in userinfo ``` The test passes (SUCCESS) but with a WARNING because the essential `name` claim was not returned. ## Privacy Consideration This is arguably **correct behavior** for a privacy-preserving IdP. Per [Connect2ID's documentation](https://connect2id.com/products/server/docs/guides/requesting-openid-claims): > "How the IdP determines which claims to release and which not is **up to its policy**." The `essential` flag is the client's way of saying "I need this" - it doesn't force the IdP to share data without proper consent. ## Options ### A) Accept the warning (current approach, minimal changes) - Keep current behavior - Only return claims based on consented scopes - Privacy-first approach ### B) Full essential claims support - Add `claims` column to `oidc_authorization_codes` and `oidc_access_tokens` tables - Capture `claims` parameter in authorize endpoint - Show essential claims on consent screen (e.g., "This app requires: name") - Return essential claims even without corresponding scope (after consent) ### C) UX-only improvement - Capture `claims` parameter - Show essential claims on consent screen as informational - Still require proper scope consent before returning claims - Doesn't change data sharing behavior, just improves transparency ## Related - [OIDC Core §5.5 - Claims Parameter](https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter) - [Connect2ID: How to request OpenID Connect claims](https://connect2id.com/products/server/docs/guides/requesting-openid-claims) - [Rodauth-OAuth supports essential claims](https://rubytalk.org/t/ruby-talk-443111-ann-rodauth-oauth-1-0-0-pre-beta2-released/76002) ## Recommendation Start with **Option C** (UX-only improvement) to improve user transparency without changing privacy behavior. This: - Shows users what the app is requesting (including essential claims) - Maintains privacy-first approach (consent = scope-based) - Makes the consent screen more informative - Could trigger re-consent if new essential claims are requested

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: dkam/clinch#9