keycloak · ahus1 · Apr 7, 2025 · Apr 3, 2025 · Apr 3, 2025
@@ -122,6 +122,7 @@ Due to fundamental changes in the permission model, **automatic migration from V
 * Permission model changes:
   ** The *user-impersonated* user permission has been _removed_.
   ** The *configure* client permission has been _removed_. With the introduction of explicit operation scoping in V2, the distinction between manage and configure became ambiguous.
+  ** The *user-impersonated* user permission has been _removed_. Instead, you can use the `impersonate-members` scope of the `Groups` resource type to allow or deny impersonation of group members.
 * Flexible resource scoping:
   ** Unlike V1, where permissions were granted either to *a single resource* (for clients, groups, and roles) or *all resources* (for users), V2 introduces greater flexibility.
   ** Administrators can now define permissions for:

@@ -83,6 +83,7 @@ public class AdminPermissionsSchema extends AuthorizationSchema {
     public static final String MANAGE_MEMBERSHIP = "manage-membership";
     public static final String MANAGE_MEMBERS = "manage-members";
     public static final String VIEW_MEMBERS = "view-members";
+    public static final String IMPERSONATE_MEMBERS = "impersonate-members";
 
     // role specific scopes
     public static final String MAP_ROLE = "map-role";
@@ -95,9 +96,9 @@ public class AdminPermissionsSchema extends AuthorizationSchema {
     public static final String MANAGE_GROUP_MEMBERSHIP = "manage-group-membership";
 
     public static final ResourceType CLIENTS = new ResourceType(CLIENTS_RESOURCE_TYPE, Set.of(MANAGE, MAP_ROLES, MAP_ROLES_CLIENT_SCOPE, MAP_ROLES_COMPOSITE, VIEW));
-    public static final ResourceType GROUPS = new ResourceType(GROUPS_RESOURCE_TYPE, Set.of(MANAGE, VIEW, MANAGE_MEMBERSHIP, MANAGE_MEMBERS, VIEW_MEMBERS));
+    public static final ResourceType GROUPS = new ResourceType(GROUPS_RESOURCE_TYPE, Set.of(MANAGE, VIEW, MANAGE_MEMBERSHIP, MANAGE_MEMBERS, VIEW_MEMBERS, IMPERSONATE_MEMBERS));
     public static final ResourceType ROLES = new ResourceType(ROLES_RESOURCE_TYPE, Set.of(MAP_ROLE, MAP_ROLE_CLIENT_SCOPE, MAP_ROLE_COMPOSITE));
-    public static final ResourceType USERS = new ResourceType(USERS_RESOURCE_TYPE, Set.of(MANAGE, VIEW, IMPERSONATE, MAP_ROLES, MANAGE_GROUP_MEMBERSHIP), Map.of(VIEW, Set.of(VIEW_MEMBERS), MANAGE, Set.of(MANAGE_MEMBERS)), GROUPS.getType());
+    public static final ResourceType USERS = new ResourceType(USERS_RESOURCE_TYPE, Set.of(MANAGE, VIEW, IMPERSONATE, MAP_ROLES, MANAGE_GROUP_MEMBERSHIP), Map.of(VIEW, Set.of(VIEW_MEMBERS), MANAGE, Set.of(MANAGE_MEMBERS), IMPERSONATE, Set.of(IMPERSONATE_MEMBERS)), GROUPS.getType());
     public static final AdminPermissionsSchema SCHEMA = new AdminPermissionsSchema();
 
     private final PartialEvaluator partialEvaluator = new PartialEvaluator();

@@ -25,10 +25,13 @@
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.junit.jupiter.api.Assertions.fail;
 import static org.keycloak.authorization.AdminPermissionsSchema.GROUPS_RESOURCE_TYPE;
+import static org.keycloak.authorization.AdminPermissionsSchema.IMPERSONATE;
+import static org.keycloak.authorization.AdminPermissionsSchema.IMPERSONATE_MEMBERS;
 import static org.keycloak.authorization.AdminPermissionsSchema.MANAGE;
 import static org.keycloak.authorization.AdminPermissionsSchema.MANAGE_GROUP_MEMBERSHIP;
 import static org.keycloak.authorization.AdminPermissionsSchema.MANAGE_MEMBERS;
 import static org.keycloak.authorization.AdminPermissionsSchema.MANAGE_MEMBERSHIP;
+import static org.keycloak.authorization.AdminPermissionsSchema.USERS_RESOURCE_TYPE;
 import static org.keycloak.authorization.AdminPermissionsSchema.VIEW;
 import static org.keycloak.authorization.AdminPermissionsSchema.VIEW_MEMBERS;
 
@@ -64,6 +67,9 @@ public class GroupResourceTypeEvaluationTest extends AbstractPermissionTest {
     @InjectUser(ref = "alice")
     ManagedUser userAlice;
 
+    @InjectUser(ref = "jdoe")
+    ManagedUser userJdoe;
+
     @InjectAdminClient(mode = InjectAdminClient.Mode.MANAGED_REALM, client = "myclient", user = "myadmin")
     Keycloak realmAdminClient;
 
@@ -380,6 +386,67 @@ public void testEvaluateAllResourcePermissionsForSpecificResourcePermission() {
         } catch (ForbiddenException expected) {}
     }
 
+    @Test
+    public void testImpersonateMembers() {
+        UserRepresentation myadmin = realm.admin().users().search("myadmin").get(0);
+        UserPolicyRepresentation allowMyAdminPermission = createUserPolicy(realm, client, "Only My Admin User Policy", myadmin.getId());
+
+        // my admin should not be able to manage yet
+        try {
+            realmAdminClient.realm(realm.getName()).users().get(userAlice.getId()).impersonate();
+            fail("Expected Exception wasn't thrown.");
+        } catch (Exception ex) {
+            assertThat(ex, instanceOf(ForbiddenException.class));
+        }
+
+        // allow my admin to impersonate members of the group where Alice is member of
+        createGroupPermission(topGroup, Set.of(IMPERSONATE_MEMBERS), allowMyAdminPermission);
+
+        realmAdminClient.realm(realm.getName()).users().get(userAlice.getId()).impersonate();
+        realmAdminClient.tokenManager().logout();
+    }
+
+    @Test
+    public void testImpersonateMembersFromChildGroups() {
+        // my admin should not be able to manage yet
+        try {
+            realmAdminClient.realm(realm.getName()).users().get(userJdoe.getId()).impersonate();
+            fail("Expected Exception wasn't thrown.");
+        } catch (Exception ex) {
+            assertThat(ex, instanceOf(ForbiddenException.class));
+        }
+
+        GroupRepresentation subGroup = new GroupRepresentation();
+        subGroup.setName("testSubGroup");
+        String testGroupId = ApiUtil.handleCreatedResponse(realm.admin().groups().add(subGroup));
+        subGroup.setId(testGroupId);
+        realm.admin().groups().group(topGroup.getId()).subGroup(subGroup).close();
+        realm.admin().users().get(userJdoe.getId()).joinGroup(subGroup.getId());
+        assertTrue(userJdoe.admin().groups().stream().map(GroupRepresentation::getName).allMatch(subGroup.getName()::equals));
+
+        // allow my admin to impersonate members of the group and its children
+        UserRepresentation myadmin = realm.admin().users().search("myadmin").get(0);
+        UserPolicyRepresentation allowMyAdminPermission = createUserPolicy(realm, client, "Only My Admin User Policy", myadmin.getId());
+        createGroupPermission(topGroup, Set.of(IMPERSONATE_MEMBERS), allowMyAdminPermission);
+
+        realmAdminClient.realm(realm.getName()).users().get(userJdoe.getId()).impersonate();
+        realmAdminClient.tokenManager().logout();
+
+        UserPolicyRepresentation denyPolicy = createUserPolicy(Logic.NEGATIVE, realm, client, "Deny My Admin User Policy", myadmin.getId());
+        createPermission(client, userAlice.getId(), USERS_RESOURCE_TYPE, Set.of(IMPERSONATE), denyPolicy);
+        try {
+            realmAdminClient.realm(realm.getName()).users().get(userAlice.getId()).impersonate();
+            fail("Expected Exception wasn't thrown.");
+        } catch (Exception ex) {
+            assertThat(ex, instanceOf(ForbiddenException.class));
+        } finally {
+            realmAdminClient.tokenManager().logout();
+        }
+
+        realmAdminClient.realm(realm.getName()).users().get(userJdoe.getId()).impersonate();
+        realmAdminClient.tokenManager().logout();
+    }
+
     private ScopePermissionRepresentation createAllGroupsPermission(UserPolicyRepresentation policy, Set<String> scopes) {
         return createAllPermission(client, AdminPermissionsSchema.GROUPS_RESOURCE_TYPE, policy, scopes);
     }