Narrative

Problem
Customers need to enforce least-privilege access per client inside a single Keycloak realm—i.e., a user may authenticate to the realm, but must not be allowed to log in to specific clients unless they hold required roles/groups.

A common pattern is environment segregation (DEV/QA/PROD) where the same realm hosts multiple clients or multiple deployments, and access must be restricted so that, for example, DEV users cannot authenticate to QA/PROD clients.

Today, customers attempt to implement this via authentication flow conditions (e.g., Condition - User Role with Deny Access) but this approach:

• becomes difficult to maintain at scale (per-client overrides, duplicated subflows, fragile configuration)
• is prone to bypass/misconfiguration in brokered/SSO scenarios (e.g., social login / Azure AD or existing SSO sessions)
• does not provide an obvious, declarative "required roles for this client" configuration directly at the client level

Expectations
Provide a native, built-in per-client configuration that allows administrators to specify:

• one or more required roles (realm roles and/or client roles, and optionally groups) that a user must have to successfully authenticate to that client
• clear enforcement semantics for OIDC/SAML login requests so that tokens are not issued if the user does not meet the client's required-role policy
• consistent enforcement for all login paths (fresh login, SSO cookie, identity brokering such as Azure AD)

Value proposition

• Enterprise-grade least privilege: prevents unauthorized users from obtaining tokens for sensitive clients/environments even if they can authenticate to the realm.
• Simpler administration: replaces brittle flow duplication/overrides with a single client-level setting; lowers configuration error risk.
• Security posture improvement: reduces accidental secret/token exposure to unintended users and supports separation-of-duties policies.
• Better brokered IdP experience: allows Azure AD/social login users to be gated purely by Keycloak roles/groups (after mapping), without relying on application code changes.

Goals

• Client-level "Required roles for login" setting
  → Add a client configuration section that supports:

• Require any of these roles (OR)
• Require all of these roles (AND)
  → Roles should include:
• realm roles
• client roles (e.g., clientId.role)
  → (Optional / nice-to-have): support groups as a separate toggle, or treat group membership via role mapping.

• Enforce the policy during authentication such that:
  → if the user lacks required roles → deny login and do not issue tokens for that client
  → error response is consistent with protocol (OIDC/SAML) and provides an admin-configurable user-facing message (optional)
• Admin Console + Admin REST API parity
  → Expose configuration in Admin Console.
  → Extend Admin REST API client representation to include these settings.
  → Ensure changes are auditable (admin events).
• Observability
  → Emit a clear admin/audit event on denial (realm, client, user, reason).
  → Log with an actionable message for support debugging.

Non-goals

• Not a replacement for fine-grained authorization (resource-level permissions). This is login/token issuance gating, not in-app authorization.
• Not requiring clients to enable Authorization Services or change application code.
• Not a new organizations/tenant binding model (e.g., "IdP linked to clients"). This is independent of IdP linkage; it relies on roles/groups in Keycloak.
• Not auto-provisioning roles from external IdPs; customers must still define a role mapping strategy (IdP mappers, group/role import, etc.).

Implementation Details and/or Other Related Discussions/Issues (GHI)