Groups

A group is a set of users. A role granted to a group applies to every member, which is how access is usually managed for a team: grant once to the group, and people gain and lose access as they join and leave it.

Like users, groups live in two places: the server-wide Directory, under Configure → Directory, and each metalake's own list, under Authorize → Groups. Roles are granted to a group in a metalake.

Quick start

The example gives a Directory group a role in a metalake. See Roles for creating the role.

UI

1. Open the role. Select the metalake, open Authorize → Roles, and click the role.

2. Add the group. On the Members tab, click + Members, choose Groups under Member type, select the group, and click Add members. The group is added to the metalake and granted the role in one step.

To give a group that already belongs to the metalake more roles, open Authorize → Groups, select the group, click + Roles, choose the roles, and click Assign roles.

REST

1. Add the group to the metalake. The name must match the group name the members arrive with.

   Add a group to the metalake

   curl -sS -X POST "https://{gravitino_host}/api/metalakes/{metalake}/groups" \
     -H "Accept: application/vnd.gravitino.v1+json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -d '{"name": "{group}"}'

2. Grant the group a role.

   Grant a role to the group

   curl -sS -X PUT "https://{gravitino_host}/api/metalakes/{metalake}/permissions/groups/{group}/grant" \
     -H "Accept: application/vnd.gravitino.v1+json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -d '{"roleNames": ["{role}"]}'

How groups get into a metalake

Groups in the Directory

A group enters the Directory in one of three ways, recorded as its origin.

Origin	How the group got there
Local	Created by a service administrator under Configure → Directory
Provisioned	Pushed by the identity provider over SCIM, with its members. The identity provider owns it
JIT	Recorded just in time from the groups claim of a valid token presented by a user who is not provisioned. The identity provider owns it

JIT groups are recorded only when SCIM provisioning is enabled in the chart, as JIT users are; see Users. A group name the identity provider already provisions over SCIM is never recorded as JIT. See Directory for local groups and SCIM provisioning for provisioned ones.

A local group holds local users only for now: adding a provisioned or JIT user to one fails, and the member pickers under Configure → Directory list local users only. That is a defect being fixed, not a design limit.

Add a group to a metalake

In the UI, assigning a role to a Directory group adds that group to the metalake. The + Role and + Members drawers under Authorize → Roles list Directory groups, and on submit the server checks each one that is not yet in the metalake against the Directory, adds it to the metalake, and then grants the role. There is no separate step to add a group to a metalake in the UI.

Over the REST API, the two steps are separate. Add the group with POST /api/metalakes/{metalake}/groups, then grant roles with PUT /api/metalakes/{metalake}/permissions/groups/{group}/grant. Granting a role to a group that is not in the metalake fails with a not-found error.

The member lists in those drawers are read from the Directory, which only a service administrator can read, so a metalake owner who is not a service administrator adds groups over REST and then assigns roles to them from Authorize → Groups. Groups carried only in token claims, with SCIM provisioning disabled, are not recorded in the Directory and are added over REST as well.

Assigning a role to a group in the UI takes both MANAGE_GRANTS and MANAGE_GROUPS on the metalake, or ownership of it. See Required privileges.

Where membership comes from

A role granted to a group reaches the users the server counts as its members when it evaluates a request, and where that membership comes from depends on how the user signs in.

Source	Applies to	Where membership is set
SCIM groups	Provisioned users, when SCIM provisioning is enabled	The identity provider, which adds and removes members over SCIM
JIT groups	Users signing in with a token who are not provisioned, with SCIM on	The token's groups claim, replaced with the latest list on every validated token
Token claim	Users signing in with a token, with SCIM provisioning off	The claim named by groupsFields, read on every request and not recorded in the Directory
Local groups	Local users	Configure → Directory, by a service administrator

With SCIM provisioning enabled, the chart empties groupsFields, so a provisioned user's groups come from SCIM alone and token claims cannot add to them. The claim JIT groups are read from is set by gravitino.scim.jit.groupsFields, which defaults to groups and can be changed under gravitino.additionalConfigItems in my-values.yaml.

Roles are granted to a group by name, so the names have to line up: the group in the metalake, the name the identity provider puts in the token claim, and, where groups are provisioned, the name it provisions. Some identity providers put opaque group IDs in the claim by default, which never match a readable group name, so configure the claim to carry names. See Authentication for groupsFields.

The groups list

Authorize → Groups lists the groups in the selected metalake, with each group's Members count, Roles, and Origin. Origin is Provisioned, Local, or JIT, checked in that order, and - for a group added over REST under a name the Directory does not hold.

Opening a group shows three tabs. Overview shows the group name, origin, member count, and when the group was created. Members lists the group's members with their roles and origin; membership is changed in the Directory or the identity provider, not here. Roles lists the roles granted to the group in this metalake, with + Roles to assign more and Unassign to remove them.

Remove a group from a metalake

Click the trash icon on the group's row and confirm Remove from metalake?. The group's members lose the roles granted through it, and the group stays in the Directory. A group that owns the metalake cannot be removed. Over REST, send DELETE /api/metalakes/{metalake}/groups/{group}.

Deleting a local group under Configure → Directory currently leaves the group, and the roles granted to it, in each metalake it belonged to. That is a defect being fixed. Until then, remove the group from each metalake under Authorize → Groups first.

Groups as owners

Ownership can be held by a group as well as a user, in which case every member of that group holds it. Assigning ownership to a group rather than a person keeps an object administrable when that person leaves, changes teams, or is removed from the identity provider.

Endpoints

Paths are relative to https://{gravitino_host}/api/metalakes/{metalake}. Each operation links to its request and response schema.

Operation	Method	Path
Add a group	POST	/groups
List groups	GET	/groups
Get a group	GET	/groups/{group}
Remove a group	DELETE	/groups/{group}
Grant roles to a group	PUT	/permissions/groups/{group}/grant
Revoke roles from a group	PUT	/permissions/groups/{group}/revoke

Add ?details=true to the list path to get full groups instead of names. Adding a group over REST does not check the Directory, so the name is taken as given.

Related

• Directory, for local groups and the server-wide Directory
• SCIM provisioning, for groups pushed by your identity provider
• Users, for how individual users get into a metalake
• Roles, for creating roles and granting privileges to them
• Privileges, for the full privilege model and what each operation requires