Users

Overview

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 added to it and granted a role there, directly or through a group.

Quick Start

1. Add the user to the metalake. The name must be the same string the user signs in as.

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

2. Grant the user a role. See Roles for creating one.

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

Users in the Directory and in a Metalake

Every user the server knows appears in its directory, with an origin recording how they got there.

Origin	How the User Got There
Local	Created in Gravitino with a password, for installations without an identity provider or as a fallback when it is down
Provisioned	Pushed by the identity provider over SCIM. Changes made to it in Gravitino are overwritten on the next cycle
JIT	Signed in through the identity provider with a verified token, with no local or provisioned record beforehand

Being in the directory lets a user sign in and grants nothing inside a metalake. A user is added to each metalake they work in, and provisioned users in particular arrive with no metalake membership, so adding them is a step taken in Gravitino rather than in the identity provider. See Directory for local accounts and SCIM provisioning for provisioned ones.

For users who sign in through the identity provider, the name a user signs in as is the value of the token claim named by principalFields, so that is the name to add. See Authentication.

Service Administrators

A service administrator is a user whose name appears in gravitino.authorization.serviceAdmins. They are added to metalakes, granted roles, and made owners like anyone else. The list adds what no metalake grant can cover: creating metalakes, managing local accounts, 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.

Suspending a User

Every user carries an enabled flag. Clearing it suspends the user's access without removing the user, and setting it again restores access. A user created with an externalId, the identifier from an external identity provider, starts enabled.

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 user	POST	/users
List users	GET	/users
Get a user	GET	/users/{user}
Remove a user	DELETE	/users/{user}
Grant roles to a user	PUT	/permissions/users/{user}/grant
Revoke roles from a user	PUT	/permissions/users/{user}/revoke

Add ?details=true to the list path to get full users instead of names. Removing a user from a metalake leaves them in the directory, so they can still sign in.