Skip to content

FGAP v2: Introduce RESET_PASSWORD scope and evaluation; scope-first with fallback to MANAGE when no policies#42307

Merged
pedroigor merged 1 commit intokeycloak:mainfrom
Bagautdino:main
Sep 3, 2025
Merged

FGAP v2: Introduce RESET_PASSWORD scope and evaluation; scope-first with fallback to MANAGE when no policies#42307
pedroigor merged 1 commit intokeycloak:mainfrom
Bagautdino:main

Conversation

@Bagautdino
Copy link
Contributor

Closes #41901
Supersedes #42298
Restores and replaces the context from #41904

Summary

Introduce a dedicated RESET_PASSWORD scope for the FGAP v2 USERS resource and evaluate password-reset access via explicit policies first.
If no reset-password policies exist for the target, evaluation falls back to MANAGE (backward-compatible path).
Self-service password change (caller == target user) remains allowed without FGAP checks.

Motivation

Currently, password resets can be implicitly allowed via MANAGE_USERS, which weakens governance/auditing.
With FGAP v2, password resets should be controlled by explicit policies with deny-overrides semantics.

Behavior (FGAP v2)

  • If there is at least one policy referencing reset-password:
    • Decisions come only from these policies (deny-overrides, secure-by-default).
  • If there are no reset-password policies:
    • We fallback to MANAGE evaluation to keep compatibility.
  • Self-service flows are unaffected.

Note: If the team prefers a configuration switch instead of unconditional fallback, this PR can be trivially adjusted to use fgap.v2.resetPassword.fallbackToManageUsers (default true/false) and documented accordingly.

Implementation

  • Add RESET_PASSWORD to AdminPermissionsSchema.USERS.
  • Require RESET_PASSWORD in UserResource.resetPassword() rather than MANAGE_USERS.
  • Expose canResetPassword() / requireResetPassword() in the user permissions API.
  • Implement scope-first evaluation in UserPermissionsV2, with fallback to MANAGE only when no reset-password policies exist.
  • Deny-overrides decision model; secure-by-default once policies are present.
  • Include getAccess(user).resetPassword for Admin Console (hide the Reset Password button when false).
  • Preserve self-service behavior.
  • Auditing/logging shows whether access was granted by policy or by fallback.

Tests

  • Added coverage for:
    • Policies present: ALLOW/DENY paths, deny-overrides.
    • No policies: fallback to MANAGE (ALLOW/DENY).
    • Self-service unaffected.
    • Access flag propagation to getAccess(user).resetPassword.

Documentation

  • Server Admin Guide: Admin Permissions section updated with the new RESET_PASSWORD scope and evaluation flow.
  • Upgrading Guide: note on behavior and fallback path; guidance on migrating to explicit reset-password policies.

UI

  • Admin Console hides Reset Password when getAccess(user).resetPassword == false.

Backward compatibility & Security

  • Backward-compat maintained via fallback when no policies exist.
  • Once policies exist, model becomes secure-by-default with deny-overrides.

Performance

  • Scope-first check plus optional fallback adds a minor evaluation step; negligible in practice.

Follow-ups

  • Group-based RESET_PASSWORD permissions (separate PR).

@Bagautdino Bagautdino requested a review from a team as a code owner September 3, 2025 10:36
- Add RESET_PASSWORD to AdminPermissionsSchema.USERS
- Require RESET_PASSWORD in UserResource.resetPassword()
- Expose canResetPassword()/requireResetPassword()
- Implement FGAP v2 deny-overrides + secure-by-default + optional fallback
- Include access.resetPassword for Admin Console

Closes #41901

Co-authored-by: Pedro Igor <pigor.craveiro@gmail.com>
Signed-off-by: Bagautdino <336373@edu.itmo.ru>
@pedroigor
Copy link
Contributor

Thanks, @Bagautdino !

@pedroigor pedroigor merged commit d225bce into keycloak:main Sep 3, 2025
76 of 77 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

FGAP v2: RESET_PASSWORD capability for USERS

2 participants