Groups

Overview

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 a user, a group is added to each metalake before roles are granted to it there.

Quick Start

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

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. See Roles for creating one.

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}"]}'

Where Membership Comes From

Membership has more than one source, depending on how a user signs in.

Source	Applies To	Where Membership Is Set
Token claim	Users signing in through the identity provider	The claim named by groupsFields, read from the token
Provisioned groups	Groups pushed by the identity provider over SCIM	The identity provider, which adds and removes members
Local groups	Local users	Gravitino, by a service administrator

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, and Directory for local groups.

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}. For request and response schemas, see the Gravitino REST API.

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.