Roles

A role is a named set of privileges, granted to users and groups. Privileges are never granted directly to a user, so a role is the only way a privilege reaches anyone.

A role holds objects, and for each one a list of privileges, each carrying an ALLOW or DENY condition. A privilege binds only to object types it supports, so CREATE_TABLE binds to a metalake, catalog, or schema, never to a table. Whoever creates a role owns it and can delete it. A role belongs to one metalake, and its members are users and groups of that metalake.

When authorization is enabled, the server evaluates every request against the roles the caller holds and the objects the caller owns, before the operation runs. A request it denies ends there. How the evaluation works, including how DENY interacts with ALLOW, is described in Privileges.

Quick start

The example creates a role that can read one schema and gives it to a group. Reading one schema takes three privileges: USE_CATALOG and USE_SCHEMA to reach it, and SELECT_TABLE to read what is in it.

UI

1. Create the role. Select the metalake, open Authorize → Roles, click + Role, enter the Role name, and click Add role. Members can also be chosen here, under Member type.

2. Grant privileges on the catalog. Open the role, select its Privileges tab, and click + Privilege. Choose Catalog as the Object type and the catalog as the Object, leave the Effect at Allow, select Use Catalog, and click Grant privilege. The privileges offered depend on the object type, and for a catalog or schema also on the catalog's type, so table privileges appear once a relational catalog is chosen.

3. Grant privileges on the schema. Click + Privilege again, choose Schema and the schema, select Use Schema and Select Table, and click Grant privilege.

4. Give the role to a group. Select the role's Members tab, click + Members, choose Groups, select the group, and click Add members. Granting to a group reaches every member, which is how access is usually managed for a team.

Adding a user or group to a role also adds it to the metalake, so assigning a role is how someone from the server's Directory gets access to a metalake; see Users. To give several users the same roles at once, select them on Authorize → Users and click + Roles.

REST

1. Create the role with its privileges. Every object the role names must exist, or the role is not created.

   Create a schema reader role

   curl -sS -X POST "https://{gravitino_host}/api/metalakes/{metalake}/roles" \
     -H "Accept: application/vnd.gravitino.v1+json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -d '{
     "name": "schema_reader",
     "properties": {},
     "securableObjects": [
       {
         "fullName": "{catalog}",
         "type": "CATALOG",
         "privileges": [{"name": "USE_CATALOG", "condition": "ALLOW"}]
       },
       {
         "fullName": "{catalog}.{schema}",
         "type": "SCHEMA",
         "privileges": [
           {"name": "USE_SCHEMA", "condition": "ALLOW"},
           {"name": "SELECT_TABLE", "condition": "ALLOW"}
         ]
       }
     ]
   }'

2. Give the role to a group. The group must already be in the metalake; see Groups. Granting to a single user works the same way with users in the path.

   Grant the role to a 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": ["schema_reader"]}'

Roles in the UI

The roles list

Authorize → Roles lists the roles in the selected metalake with each role's Owner and Members, a count of the groups and users it is granted to. Selecting one or more roles and clicking + Members adds the same users or groups to all of them at once.

To delete a role, click the trash icon on its row and confirm Delete role?. Every member loses the privileges it grants. Deleting a role takes ownership of the role or of the metalake.

A role's members and privileges

Opening a role shows its owner and two tabs.

• Members lists each user and group the role is granted to, with the user's origin or the group's member count under Detail, and when it was Assigned. Click + Members to add more, or the trash icon on a row and Remove from this role? to take the role away.
• Privileges lists one row for each object and effect: the Object, its Type, the Effect (Allow or Deny), and the Privileges. Click + Privilege to grant more, or the trash icon on a row and Delete this grant? to revoke every privilege in that row.

Adding members takes MANAGE_GRANTS on the metalake, plus MANAGE_USERS to add users or MANAGE_GROUPS to add groups, or ownership of the metalake. Creating a role with + Role takes CREATE_ROLE. See Required privileges.

Grant from the object

Privileges can also be granted from the object they apply to. In Explore, open the metalake, catalog, schema, or other object, click Privileges beside the allowed and denied counts in its header, choose the role under Role, pick the Effect and the Privileges, and click Update privileges. The grant appears on the role's Privileges tab like any other, and every grant in the metalake can be reviewed under Govern → Privileges.

Endpoints

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

Operation	Method	Path
Create a role	POST	/roles
List roles	GET	/roles
Get a role	GET	/roles/{role}
Delete a role	DELETE	/roles/{role}
Grant privileges to a role	PUT	/permissions/roles/{role}/{object_type}/{object_name}/grant
Revoke privileges from a role	PUT	/permissions/roles/{role}/{object_type}/{object_name}/revoke
Replace a role's privileges	PUT	/permissions/roles/{role}/
List the roles bound to an object	GET	/objects/{object_type}/{object_name}/roles

Add ?details=true to the list path to get full roles instead of names. Granting a role to a user or group is covered on Users and Groups.

Replacing a role's privileges is destructive: afterwards the role holds exactly what the request body contains, and any object absent from it is dropped.

A revoke removes a privilege only when both its name and its condition match the grant, so revoking SELECT_TABLE with DENY leaves an ALLOW grant of SELECT_TABLE in place.

Java client

Most calls map directly onto a GravitinoClient method and are covered by the Java doc. Two take arguments that are hard to derive from the signature alone.

A role's objects are built as a nested path rather than a dotted string:

Build a securable table object

SecurableObject table =
    SecurableObjects.ofTable(
        SecurableObjects.ofSchema(
            SecurableObjects.ofCatalog("catalog1", Collections.emptyList()),
            "schema1",
            Collections.emptyList()),
        "table1",
        Lists.newArrayList(Privileges.SelectTable.allow()));

Role role = client.createRole("table_reader", ImmutableMap.of(), Lists.newArrayList(table));

Privileges are passed as a Set, and each carries its condition. The List overloads of these two methods are deprecated:

Grant and revoke privileges on a role

MetadataObject schema =
    MetadataObjects.of(Lists.newArrayList("catalog1", "schema1"), MetadataObject.Type.SCHEMA);

client.grantPrivilegesToRole("table_reader", schema, ImmutableSet.of(Privileges.SelectTable.allow()));
client.revokePrivilegesFromRole("table_reader", schema, ImmutableSet.of(Privileges.SelectTable.allow()));

Related

• Users, for how users get into a metalake and receive roles
• Groups, for granting a role to every member of a group
• Privileges, for the full privilege list, what each operation requires, ownership, and reviewing grants
• Authorization pushdown, for writing grants into Apache Ranger so that engines reading data without going through Datastrato Enterprise enforce them too