groups

pkg/handler/groups

This package manages the primary local delegation unit inside an organization.

Intent

Groups are the main attachment point between identities and authority.

They answer three related questions:

• which users are members of the group
• which service accounts are members of the group
• which roles those members inherit through the group

Projects then refer to groups rather than directly to users or roles, so this package sits at the center of organization-local delegation.

What Is Specific Here

Primary Binding Layer For Local Authority

This client is where organization membership turns into inherited permissions.

Users and service accounts do not receive roles directly through this handler layer. Instead, they become members of groups, and groups carry the RoleIDs that define the granted authority.

That makes groups the main local delegation unit for both human and non-human actors.

Compatibility Bridge Between UserIDs And Subjects

The package still supports both:

• legacy UserIDs, which refer to OrganizationUser records
• newer Subjects, which can refer to local or external identities

When a request uses one of those representations, the client populates the other where possible so old and new clients can coexist during the migration period.

This compatibility behaviour is one of the main reasons the package is more than simple CRUD.

Role Assignment Guard Rails

Group role assignment is where the handler layer turns the deeper RBAC security model into a concrete write-time check.

When roles are attached to a group, this client:

• verifies the role exists
• rejects protected roles
• rejects roles the caller is not permitted to grant in that organization

So group writes are also authority-delegation checks.

Project Reference Cleanup

Projects use groups as access boundaries.

Because of that, deleting a group is not a local-only operation. The client must first remove the group from any project groupIDs that still reference it, otherwise project-scoped access state would drift.

Invariants

• groups are the primary organization-local attachment point between members and roles
• RoleIDs are the actual delegated-authority payload of the group
• protected roles must never be attached to a group
• callers may only attach roles they are allowed to grant in that organization
• internal compatibility between UserIDs and Subjects should be maintained where possible
• projects should not retain references to groups that no longer exist

Caveats

• The package is partly a migration bridge because it must support both deprecated UserIDs and forward-looking Subjects.
• Groups may include external subjects that do not resolve to local User objects, so not every group member is necessarily backed by a local user record.
• Referential integrity across groups, users, service accounts, and projects is best-effort on top of Kubernetes storage rather than atomically enforced by the backing store.

Related Documentation

• pkg/handler/users, which establishes organization membership that groups then bind to roles
• pkg/handler/serviceaccounts, which establishes the organization-local non-human identities that groups also bind to roles
• pkg/handler/projects, which uses groups as project access boundaries
• pkg/rbac, which defines the security rules around protected and grantable roles enforced here
• pkg/apis/unikorn/v1alpha1, which defines the stored Group resource and the UserIDs to Subjects migration context