Skip to main content

Directory

The Directory is the server-wide list of every user and group the server knows, across all metalakes. Each identity carries an origin recording how it got there. In the UI it is Configure → Directory.

OriginWhere it comes from
LocalCreated in the Directory, with a user name and password stored and managed by Datastrato
ProvisionedSent by your identity provider through SCIM. The identity provider owns it, and the Directory does not add, delete, or change its password
JITDiscovered from the token a user presents at sign-in, for users the identity provider has not provisioned. The identity provider owns it

A service administrator creates local identities, the identity provider provisions identities over SCIM, and a first sign-in by an unprovisioned user creates a JIT identity; all three land in the server-wide Directory with their origin, and a metalake owner adds them to the metalake and grants roles

Local accounts sign in with a password and are the recovery path when the identity provider is unavailable.

A user name is unique only within its origin, so a local user and a provisioned user can share a name. Metalake membership is keyed on the metalake and the user name alone, so the two share one metalake user and every role granted to it.

A local group is meant to hold users of any origin, so an administrator can collect provisioned and JIT users for role assignment when the identity provider's groups do not fit. In this release it holds local users only: adding a provisioned or JIT user fails (over REST, with IdP user not found), and the member pickers in the UI list local users only. That is a defect being fixed, not a design limit.

Quick start​

Creating a local user takes two things: the basic authenticator enabled on the server, and a service administrator to create the account with.

  1. Enable local sign-in. In my-values.yaml, list basic among the authenticators and set the initial administrator account, then apply the values. The install in Install already does both.

    my-values.yaml
    gravitino:
      authorization:
        enable: true
        serviceAdmins: admin
      authenticators: "basic"
      admin:
        initPassword: "{admin_password}"

    The commands below read that password from the shell variable ADMIN_PASSWORD.

    Where users also sign in through an identity provider, list both, with the provider first: gravitino.authenticators: "oauth,basic".

  1. Sign in as the administrator. Sign in to the UI as admin with that password.

  2. Create a local user. Open Configure → Directory, select Users, and click + Local user. Enter the Username and Password, optionally choose Local groups, and click Add local user.

The new user can sign in immediately and reaches no metadata until granted a role in a metalake, which Grant access to metadata covers.

Directory and authorize​

The Directory manages identities. Authorize manages what those identities can do in a metalake.

AreaWhat it covers
Directory, for service administratorsCreate, suspend, and delete local users and groups. List every identity with its origin. Show which metalakes each identity belongs to, read-only
Authorize, for metalake ownersAdd a user to the metalake, grant roles to users and groups, and remove members. Authorize cannot create or delete identities

In the UI, assigning a role to a directory user or group adds it to the metalake. Over REST, the user or group must be added to the metalake before a role can be granted to it there. See Authorize for roles, grants, and metalake membership.

Deleting a local user removes the account and its local group memberships. The user stays listed under Authorize → Users in each metalake it belonged to, with its roles, and a user created later under the same name inherits them. Until that defect is fixed, remove the user from each metalake under Authorize → Users before deleting it here. Deleting a local group likewise leaves the group under Authorize → Groups in each metalake.

Local users and groups​

A local account holds its user name, password hash, and group membership in the server's own relational metadata store, alongside the rest of its metadata. Clients authenticate with HTTP Basic credentials, and nothing outside the server is required.

Local accounts authenticate callers to the server. They do not issue tokens or assertions that other services can consume, so they are not a single sign-on system and not a replacement for Okta, Microsoft Entra ID, or Keycloak. Use them for proofs of concept, isolated deployments, and as the way in when the identity provider is unavailable. For everything else, see Authentication.

Credentials travel in an HTTP header on every request, so run the server behind HTTPS wherever the network is not fully trusted.

The UI reads gravitino.authenticators from the server and presents a user name and password form when basic is the authenticator in use.

Name and password rules​

The rules below apply to creation and password changes alike.

RuleValue
User nameRequired, at most 128 characters, no colon
Group nameRequired, at most 128 characters
Group descriptionOptional, at most 1024 characters
Password length12 to 64 characters inclusive

Manage users​

All user tasks are on Configure → Directory, under Users.

  1. Add a user. Click + Local user, fill in Username, Password, and optionally Local groups, and click Add local user.

  2. Add users to groups. Select one or more local users, click + Local groups, choose the groups, and click Add local groups.

  3. Delete a user. Click the trash icon on the user's row and confirm Delete this user?. A lock icon replaces the trash icon for users that cannot be deleted: provisioned and JIT users, service administrators, and yourself.

Change a password​

  1. Open your user. On Configure → Directory, under Users, click your user name. The Password tab appears for local users only.

  2. Set the new password. On the Password tab, enter Current password, New password, and Confirm new password, and click Update password. Changing it signs out your other sessions.

The Password tab always asks for the current password, so the UI cannot reset another user's forgotten password. A service administrator resets one over REST.

Suspend and activate a user​

A suspended user keeps their group memberships and roles but cannot authenticate: every request they make is rejected with 401 and Account is suspended. Activating the user restores access at once. Only local users can be suspended here, and service administrators and yourself cannot be. A provisioned user is deactivated by the identity provider.

  1. Select the users. On Configure → Directory, under Users, select one or more local users.

  2. Suspend or activate them. Click Suspend and confirm. The confirmation reads "They keep their roles but cannot authenticate until reactivated." To restore access, select suspended users, click Activate, and confirm.

Manage groups​

All group tasks are on Configure → Directory, under Groups.

  1. Add a group. Click + Local group, enter the Group name and an optional Description, choose Members, and click Add local group.

  2. Add members. Click the group, open its Members tab, click + Add members, choose the users, and click Add members.

  3. Remove a member. On the Members tab, click the trash icon on the member's row and confirm Remove member from group?.

  4. Delete a group. On Groups, click the trash icon on the group's row and confirm Delete group?. Groups that are not local show a lock icon instead.

Provisioned and JIT users​

Provisioned and JIT identities appear in the Directory on their own, one pushed by your identity provider and the other read from a verified token at sign-in. Both are owned by the identity provider, so add, change, and remove them there rather than in the Directory. See SCIM provisioning for provisioned identities and Authentication for the token claims a JIT user is built from.

Metalake membership is not owned by the identity provider. A provisioned or JIT user arrives with none, so adding them to a metalake is done under Authorize.

Grant access to metadata​

A user can authenticate as soon as the Directory knows them, and reaches metadata only once they belong to a metalake and hold a role there, directly or through a group. The user name must match the name the user signs in as.

  1. Open the roles. Select the metalake, then open Authorize → Roles.

  2. Assign the role. Click + Role to create a role and choose its members there, or select an existing role and click + Members. Assigning a role adds the user or group to the metalake.

When gravitino.authorization.enable is set to true, only service administrators can create metalakes. See Roles for creating roles, Privileges for roles, privileges, and ownership, and Create a metalake for metalake creation.

Connect engines​

An engine reaches the server by one of two paths, and each takes its own Basic credentials.

Through the Gravitino connector​

Configure the connector for each engine, then add the credentials below. See Spark authentication, Flink authentication, and Trino authentication for the rest of the connector setup.

Spark connector settings
spark.sql.gravitino.authType=basic
spark.sql.gravitino.basic.username={username}
spark.sql.gravitino.basic.password={password}
Flink connector settings
table.catalog-store.gravitino.gravitino.client.auth.type: basic
table.catalog-store.gravitino.gravitino.client.basic.username: {username}
table.catalog-store.gravitino.gravitino.client.basic.password: {password}
etc/catalog/gravitino.properties
gravitino.client.authType=basic
gravitino.client.basic.username={username}
gravitino.client.basic.password={password}

Trino also needs catalog.management=dynamic in etc/config.properties and a restart before the catalogs appear.

Through the Iceberg REST endpoint​

Engines can connect straight to the Iceberg REST service at https://{iceberg_host}/iceberg with no Gravitino connector plugin. See Connect Spark via Iceberg REST, Connect Flink via Iceberg REST, and Connect Trino via Iceberg REST for the rest of the setup.

Spark Iceberg REST settings
spark.sql.catalog.{catalog}.rest.auth.type=basic
spark.sql.catalog.{catalog}.rest.auth.basic.username={username}
spark.sql.catalog.{catalog}.rest.auth.basic.password={password}
Flink Iceberg REST options
'rest.auth.type' = 'basic',
'rest.auth.basic.username' = '{username}',
'rest.auth.basic.password' = '{password}'

Trino has no native Basic mode for Iceberg REST, so the header is set directly with iceberg.rest-catalog.http-headers, which requires Trino 481 or later. Generate the encoded credentials with echo -n '{username}:{password}' | base64.

etc/catalog/{catalog}.properties
connector.name=iceberg
iceberg.catalog.type=rest
iceberg.rest-catalog.uri=https://{iceberg_host}/iceberg
iceberg.rest-catalog.http-headers=Authorization: Basic {base64_credentials}
  • Authorize, for adding identities to a metalake and granting them roles
  • SCIM provisioning, for identities pushed by your identity provider
  • Authentication, for how a caller proves who they are
  • OpenAPI definition, for full request and response schemas of the local account endpoints
  • HTTPS, for protecting credentials in transit
  • Privileges, for what an authenticated user is allowed to do
Last updated on