Feature Overview (aka. Goal Summary)   __ 

Provide enterprises using OpenShift with a scalable, reliable method to access all relevant group membership information from OIDC providers, overcoming token size limitations and ensuring consistent access control for users in large organizations.

OpenShift Container Platform currently syncs group membership from OIDC identity providers but is limited by provider token size constraints (for example, Azure AD restricts tokens to 200 groups). This feature introduces support for Aggregated and Distributed Claims via a webhook authenticator, enabling KAS to fetch additional identity information dynamically from the IdP. This ensures that users with large group memberships retain full access and functionality without token truncation issues.

Goals (aka. expected user outcomes)

Users with more than 200 group memberships can access OpenShift resources without token truncation issues.

OpenShift administrators can configure the webhook authenticator to fetch distributed claims without modifying existing structured authentication configurations.

Alignment with the structured authentication configuration API ensures consistency with current OpenShift authentication patterns.

Enterprise personas (IdP administrators, OpenShift cluster admins, and security teams) can maintain secure and compliant access policies across large-scale environments.

Extend current Bring Your Own External Auth with OpenID Connect functionality to support aggregated and distributed claims across all supported OCP deployments

Requirements (aka. Acceptance Criteria):

• Webhook authenticator capable of fetching additional claims from OIDC providers dynamically.
• Compatible with Azure AD and other major OIDC providers supporting aggregated/distributed claims.
• Optional configuration: if not configured, KAS defaults to existing structured authentication.
• NetworkPolicy ensures only KAS can communicate with the webhook authenticator.
• Secure handling of credentials and tokens during claims fetching.
• Performance impact minimized to avoid slowing authentication requests.
• Alignment with KAS authentication API surface.
• Documentation updates reflect configuration and operational guidance.
• Backward compatibility for clusters not using aggregated/distributed claims.

Anyone reviewing this Feature needs to know which deployment configurations that the Feature will apply to (or not) once it's been completed.  Describe specific needs (or indicate N/A) for each of the following deployment scenarios. For specific configurations that are out-of-scope for a given release, ensure you provide the OCPSTRAT (for the future to be supported configuration) as well.

Use Cases (Optional):

Include use case diagrams, main success scenarios, alternative flow scenarios.  Initial completion during Refinement status.

Main success scenario: A user with more than 200 group memberships logs in; KAS fetches full group claims via webhook authenticator; user receives appropriate access without token truncation.
Alternative flow: If IdP is unreachable, KAS falls back to existing structured authentication with a warning logged.

Questions to Answer (Optional):

How should failure scenarios in fetching distributed claims be surfaced to admins?

Is there a preferred mechanism for gathering telemetry/performance metrics for the webhook? 

Out of Scope

High-level list of items that are out of scope.  Initial completion during Refinement status.

<your text here>

Background

 __ OpenShift’s current OIDC implementation works well for most customers but fails when tokens are truncated due to provider limits (like Azure AD’s 200-group cap). Aggregated and Distributed Claims allow KAS to fetch full user group membership dynamically. A webhook authenticator is the most feasible approach to implement this while preserving alignment with upstream OpenShift API patterns.

Customer Considerations

 __ Customers with large enterprises using Azure AD will benefit most.

Admins must configure network policies to secure the webhook authenticator.
Transparent fallback ensures clusters not requiring this feature continue to function normally.

Documentation Considerations

Provide information that needs to be considered and planned so that documentation will meet customer needs.  If the feature extends existing functionality, provide a link to its current documentation. Initial completion during Refinement status.

<your text here>

Interoperability Considerations

ROSA/OSD/ARO: Ensure webhook authenticator is compatible with managed clusters.
Existing OIDC integrations must continue to function if distributed claims are not enabled.
Test scenarios should include high-group-count users across multi-node and compact cluster deployments.

Ui/CLI implications TBD