Add Groups resource type and scopes to authorization schema

Hi there 👋

Review of the MR adding the Groups resource type and scopes to the authorization schema. The schema definition itself — resource type name Groups, the five scope names (manage, view, manage-membership, manage-members, view-members), resource creation, and scope validation in AdminPermissionsSchema — is correct and consistent with the V1 GroupPermissions constants, the V2 GroupPermissionsV2 consumers, and the admin-console message keys. However, the V2 evaluation layer contains several blocking defects:

• Privilege escalation: GroupPermissionsV2.canManage() (no-arg) returns true for a VIEW-only grant, allowing a view-only admin to create/rename top-level groups. The per-group overload and the user counterpart correctly require only MANAGE.
• Broken group-membership filtering: the new GroupPermissionsV2.getGroupIdsWithViewPermission() returns resource UUIDs instead of group IDs and never evaluates individual group resources, breaking group-scoped user search/count in UsersResource and BruteForceUsersResource under V2.
• False-negative access control: the UserPermissionsV2.hasPermission() "all-users" fallback is shadowed as soon as an unrelated per-user resource exists, wrongly denying legitimate access to admins holding an all-users grant.
• Functional regressions: legacy group management endpoints (GET/PUT /groups/{id}/management/permissions) surface UnsupportedOperationException (HTTP 500) in V2; the event-listener cleanup gate is inconsistent with the V1/V2 dispatch, causing exceptions during group/client removal when both features are enabled and leaving orphaned resources when only V2 is on; and the hierarchy vs flat group-listing paths diverge in visibility under V2.

Also noted: getResourceName does not resolve the new Groups type (null policy display names), getGroupCount leaks realm-wide counts regardless of per-group view permission, and a few minor cleanup items (javadoc mismatch, missing resourceId guard, test cleanup). Status: REQUEST_CHANGES.

These might need a close look

• 🔴 services/.../admin/permissions/GroupPermissionsV2.java (L76)
  The no-arg canManage() includes AdminPermissionsSchema.VIEW in the permission check, so an admin holding only the view scope on all groups is granted manage access and can create/rename top-level groups (GroupsResource.addTopLevelGroup gates on requireManage()). This is a privilege escalation, inconsistent with the per-group canManage(GroupModel) override (MANAGE only) and with UserPermissionsV2.canManage(). Remove VIEW so canManage() requires only MANAGE; also correct the GroupPermissionEvaluator.canManage() javadoc that documents VIEW-or-MANAGE.
• 🔴 services/.../admin/permissions/GroupPermissionsV2.java (L128)
  getGroupIdsWithViewPermission() is broken and breaks group-scoped user search/count (consumed by UsersResource.searchForUser/getUsersCount and BruteForceUsersResource.searchForUser in their DB group filter): (1) it adds groupResource.getId() (a resource UUID) instead of the group ID into the returned set, so downstream group-membership filtering matches nothing; (2) hasPermission(groupResource.getId(), ...) re-resolves by name using the resource UUID, which never matches group resources that are named by group ID, falling through to the all-groups fallback; (3) findByType only yields the all-groups resource because individual group resources are not typed. As a result group-scoped filters are ineffective or wrong (empty set or non-group UUIDs). Rework to evaluate each group resource directly and return/use groupResource.getName(), mirroring V1 GroupPermissions.
• 🔴 services/.../admin/permissions/UserPermissionsV2.java (L104)
  The "all-users" fallback in hasPermission() only applies when the target user has no per-user resource. Once any admin creates a scope permission on a specific user (materializing a per-user resource named after the user id), the all-users grant is never evaluated for that user. Admin B holding an all-users VIEW/MANAGE grant is then wrongly denied for a user that Admin A has a per-user resource on — a false-negative access-control bug affecting canView/canManage/canMapRoles/canManageGroupMembership/canImpersonate. The all-users resource should be evaluated in addition to (OR with) the per-user resource rather than only as a fallback. The same pattern exists in GroupPermissionsV2.hasPermission.

Worth checking

• 🟡 server-spi-private/.../AdminPermissionsSchema.java (L331)
  getResourceName (used to set policy display names) only special-cases USERS_RESOURCE_TYPE. The new Groups resource type falls through to resource.getDisplayName(), which is null because group resources (individual and the all-groups resource) are created without a displayName. Consequently group scope-permission policies render a null/blank resource name. Add a GROUPS branch returning "All groups" for the type-level resource and resolving the group name for individual group resources (mirroring the USERS handling).
• 🟡 services/.../admin/permissions/GroupPermissionsV2.java (L167)
  Several legacy GroupPermissionManagement methods (isPermissionsEnabled, setPermissionsEnabled, viewPermission, managePermission, resource(group), getPermissions(group), etc.) throw UnsupportedOperationException. These are reachable via GroupResource.getManagementPermissions() / setManagementPermissionsEnabled(), so GET/PUT /groups/{id}/management/permissions return HTTP 500 in V2-enabled realms. Guard these endpoints (e.g., return 404/403 or an explicit unsupported response) instead of surfacing the exception.
• 🟡 services/.../admin/GroupsResource.java (L113)
  The two group-listing paths diverge under the V2 evaluator: hierarchy mode filters by g -> canView() || canView(g), while the flat path (populateHierarchy=false, this line) filters by canView(g) only. Under GroupPermissionsV2, canView() and canView(group) are evaluated independently, so a caller with only an all-groups VIEW/MANAGE grant sees a group in hierarchy mode but it disappears in flat mode. The same divergence exists in GroupResource.getSubGroups (filters by canView(group) only). Make all listing paths use the same predicate (g -> canView() || canView(g)) or make canView(group) honor the all-groups permission.
• 🟡 services/.../admin/GroupsResource.java (L157)
  getGroupCount is guarded only by requireList() and returns realm.getGroupsCount(...) for the whole realm without per-group view filtering, so a caller that can list but holds view permission for only a subset of groups still receives the total count, leaking the existence/count of groups it cannot view. Consider filtering the count by viewable groups (pre-existing, but made more visible by the fine-grained group scopes).
• 🟡 services/.../admin/permissions/AdminPermissions.java (L101)
  registerListener is gated on the V1 flag (ADMIN_FINE_GRAINED_AUTHZ) while the factory methods dispatch on the V2 flag (ADMIN_FINE_GRAINED_AUTHZ_V2). This produces two broken scenarios: (1) with both features on, removing a group/client calls GroupPermissionsV2/ClientPermissionsV2.setPermissionsEnabled(...) which throw UnsupportedOperationException, raising an exception during removal instead of cleaning up; (2) with only V2 on, the listener is never registered, so orphaned V2 permission resources are never cleaned up. Base the registration on the same condition as the factories and handle the V2 path by deleting orphaned resources instead of calling the throwing methods.

✅ Feature-level checklist

Partially covered

• ⚠️ Add the Groups resource type and scopes to the authorization schema and evaluate permission checks for the new Groups resource type.
  The schema definition (resource type name 'Groups', scope names, resource creation and scope validation) is correct and consistent with the V1/V2 consumers. However, the V2 permission evaluation for groups has multiple defects — a canManage() privilege escalation allowing view-only admins to manage top-level groups, a broken getGroupIdsWithViewPermission() that breaks group-scoped user search/count, the all-users fallback shadowing in user evaluation, and HTTP 500s on the management/permissions endpoints — so the evaluation part is not fully met and requires fixes before the feature behaves correctly.