Skip to main content

Users

A user is a principal that roles are granted to and that can own objects. Signing in and reaching metadata are separate: a user can sign in as soon as the server knows them, but reaches nothing in a metalake until they belong to it and hold a role there, directly or through a group.

Users live in two places. The Directory, under Configure → Directory, is the server-wide list of every identity the server knows. A metalake has its own list of members, under Authorize → Users, and roles are granted to those members.

Quick start​

The example gives an existing Directory user a role in a metalake. See Roles for creating the role.

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

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

To give a user who already belongs to the metalake more roles, open Authorize → Users, select the user, click + Roles, choose the roles, and click Assign roles.

How users get into a metalake​

Users in the Directory​

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

OriginHow the user got there
LocalCreated by a service administrator under Configure → Directory, with a password stored on the server
ProvisionedPushed by the identity provider over SCIM. The identity provider owns the record
JITRecorded just in time, when a user presents a valid token from the identity provider and has no provisioned record. The identity provider owns the record

JIT recording is wired in by the chart when SCIM provisioning is enabled (gravitino.scim.enabled), and only then. It runs in the background after the token is validated, so a JIT user appears in the Directory shortly after their first request, not before it. Group names in the token's groups claim are recorded with the user as JIT groups; see Groups. If the identity provider later provisions the same user over SCIM, the provisioned record takes over and the JIT record is retired.

Being in the Directory lets a user sign in and grants nothing inside a metalake. Provisioned and JIT users arrive with no metalake membership. See Directory for local accounts and SCIM provisioning for provisioned ones.

For users who sign in through the identity provider, the user name is the value of the token claim named by principalFields, so that is the name the Directory records and the name to grant roles to. See Authentication.

Add a user to a metalake​

In the UI, assigning a role to a Directory user adds that user to the metalake. The + Role and + Members drawers under Authorize → Roles list Directory users, 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 user to a metalake in the UI.

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

Users who sign in through the identity provider without SCIM provisioning need the REST path. With SCIM disabled, no JIT record is made, so these users are not in the Directory and the UI cannot add them.

Adding users and granting roles each need their own privilege on the metalake, so assigning a role to a user in the UI takes both MANAGE_GRANTS and MANAGE_USERS, or ownership of the metalake. See Required privileges.

The users list​

Authorize → Users lists the members of the selected metalake, one row per user.

ColumnWhat it shows
UsernameThe user name. Click it to open the user
RolesRoles granted to the user directly
GroupsDirectory groups the user belongs to: local, provisioned, and JIT
StatusActive or Suspended, read from the Directory
OriginProvisioned, Local, or JIT, checked in that order. None means the user is in no Directory store

A user added over REST under a name the Directory does not hold shows None. A JIT user is always Active.

Opening a user shows three tabs. Overview shows the username, status, origin, External ID for a provisioned user, and when the user was created. Groups lists the user's groups. Roles lists the roles granted to the user directly in this metalake, with + Roles to assign more and Unassign to remove them.

Remove a user from a metalake​

Click the trash icon on the user's row and confirm Remove from metalake?. The user loses every role granted to them in the metalake and stays in the Directory, so they can still sign in. The metalake's owner cannot be removed. Over REST, send DELETE /api/metalakes/{metalake}/users/{user}.

Delete a Directory user​

Deleting a local user under Configure → Directory also removes it, with every role granted to it, from each metalake it belonged to.

Suspend a user​

Suspension belongs to the Directory, not to a metalake. The Status column under Authorize → Users shows it and cannot change it.

  • Local users are suspended and activated by a service administrator under Configure → Directory. A suspended local user keeps their roles, and every request they make is rejected with 401. See Suspend and activate a user.
  • Provisioned users are deactivated in the identity provider, which sends active: false over SCIM, and show as Suspended. A suspended provisioned user loses the roles that came through groups at once, but a token the identity provider issued before the deactivation is still accepted until it expires, with the roles granted to the user directly. Revoke those roles, or remove the user from the metalake, when access has to end immediately. See Deprovisioning.
  • JIT users have no status of their own in the Directory.

Service administrators​

A service administrator is a user whose name appears in the chart value gravitino.authorization.serviceAdmins, a comma-separated list that defaults to admin. Set it in my-values.yaml and apply it with helm upgrade as in Install.

my-values.yaml
gravitino:
  authorization:
    serviceAdmins: "admin,{user}"

Service administrators are added to metalakes, granted roles, and made owners like anyone else. The list adds what no metalake grant can cover: creating metalakes, reading and managing the Directory, and creating the tokens an identity provider uses to provision users. Being server configuration rather than a role, it cannot be granted or revoked through the API. The metalake check reads the list alone, which is what lets the first metalake be created before any membership exists.

Every metalake therefore starts out owned by the service administrator who created it, and letting anyone else create metalakes means adding them to the list. Transfer each new metalake to whoever will run it, as the Walkthrough does.

Endpoints​

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

OperationMethodPath
Add a userPOST/users
List usersGET/users
Get a userGET/users/{user}
Remove a userDELETE/users/{user}
Grant roles to a userPUT/permissions/users/{user}/grant
Revoke roles from a userPUT/permissions/users/{user}/revoke

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

  • Directory, for local users and the server-wide Directory
  • SCIM provisioning, for users pushed by your identity provider
  • Groups, for granting roles to many users at once
  • Roles, for creating roles and granting privileges to them
  • Privileges, for the full privilege model and what each operation requires
Last updated on