RBAC Concepts

Role Based Access Control (RBAC) definitively grants permissions to accounts in a positive, additive way.

This page defines terms used in the RBAC system along with examples.

Users

Every user with access to a Hydrolix cluster has an account. Users are identified by the email address used to activate the account.

Roles have unique names. Administrators associate users with roles by name.

Each user is associated with at least one role when invited to a cluster.

Resources

Resources are the entities that organize data within a Hydrolix cluster.

Resource hierarchy

The following chart shows how Hydrolix organizes resources. At the highest level, organizations contain all other resources.

Global
   Organization
       Project
           Table
               SQL
               Transform
           Dictionary
           Function

When a user has a permission to a resource, Hydrolix grants permissions for all resources below that resource in the hierarchy that belong to the higher-level resource. For instance, granting a user "view" permission to a table also grants transitive view permission to all rows, columns, and transforms in the table.

Positive permissions

Hydrolix permissions can only be expressed in a "positive" way: roles can only grant permissions, never restrict permissions. For instance, consider a Hydrolix cluster that contains the following configuration:

Organization A
    Project X
        Table 1
        Table 2
        Table 3
    Project Y
        Table alpha
        Table beta
    Project Z
        Table canis
        Table felis

A user with view permissions for Project X has view access to tables 1, 2, and 3. There is no way to restrict a user with full project view permissions from viewing a table nested within that project. To grant a user permissions to only tables 1 and 3, but NOT 2, you must individually grant the user permissions to tables 1 and 3 instead of granting permissions at the project level.

Similarly, if you grant a user all permissions for organization A, that user gains access to projects X, Y, and Z, tables 1, 2, 3, alpha, beta, canis, and felis. This happens because Hydrolix only grants, and never restricts, permissions to users based on the hierarchy of resources. Restricted permissions are defined only by omission, so use the hierarchy of organizations, projects, and tables to simplify your permission scheme.

Roles

Roles determine whether or not an action executes within your Hydrolix cluster. Roles are comprised of a unique name, a description, and a collection of policies. You can reuse roles across multiple users.

Think of roles as a function with the following inputs:

• user
• action
• resource

Hydrolix administrators write roles to define that function. When a user performs an action on a resource in your cluster, RBAC computes the function based on the user, action, and resource inputs. If the function says "yes", Hydrolix executes the action for the user. If the function says "no", Hydrolix skips the action and informs the user that they don't have access to that action on that resource.

For example,

• user is "Tessa"
• action is "read"
• resource is "table"
• the role name is "MyProjectReader"

Tessa can read a table. Another way to say this is that user "Tessa" has a "MyProjectReader" role, and that role has a policy in its collection that allows it to read tables, so Tessa is able to read tables.

Policies

Policies combine a Scope and a set of Permissions. They are assigned to Roles. The scope determines which resources the policy applies to, e.g. a specific organization or project or table. The permissions set determines what actions users can take within that scope, e.g. editing or viewing data.

For example, can Tessa in the example above read any table in a project? The answer is yes, if there is a policy with a scope of 'project' that contains the select_sql permission in its permissions set. The "MyProjectReader" role in the previous example should have this policy in its policy collection, allowing Tessa to read all tables in this project.

Permissions

In Hydrolix, permissions control whether or not a user can perform a given action for a particular resource. Each permission corresponds to an action (denoted with prefixes at the beginning of the permission name) and a resource (denoted by suffixes at the end of the permission name). For instance, the view_table permission describes the view action executed on the table resource.

Hydrolix RBAC provides the following actions, each of which corresponds to multiple permission:

View

The view action allows users to list and retrieve information about a resource. Examples of permissions that require the view action include:

• view_dictionary: see the contents of a custom dictionary
• view_function: see the definition of a custom function
• view_transform: see the definition of a transform

ℹ️

Intelligent list filtering

Note that Hydrolix doesn't have an explicit list action. This is because Hydrolix intelligently determines which objects a user has permission to list according to all their other permissions. An endpoint that returns a list will rarely return a 403 Forbidden error code -- instead, Hydrolix calculates permissions for parent, child, and sibling scope objects and returns only the relevant objects.

Add

The add action allows users to create new data in a resource. Examples of permissions that require the add action include:

• add_dictionary: insert a new key-value pair into a custom dictionary
• add_function: define a new function in a project
• add_table: create a new table in a project
• add_transform: create a new transform

Change

The change action allows users to alter existing data in a resource. Examples of permissions that require the change action include:

• change_table: edit data in a column of an existing row in a table
• alter_table_sql: alter the name of a table
• change_dictionary: change the value of a key in a custom dictionary
• change_transform: alter a transform definition

Delete

The delete action allows users to remove existing data from a resource. Examples of permissions that require the delete action include:

• delete_function: remove a custom function
• delete_transform: remove a transform
• delete_table: remove a table from a project

ALL

The ALL permission grants a user every possible action for a given resource. A user with the ALL permission can perform any action on the specified resource.

SQL

SQL operations in Hydrolix require a model with more nuance than the basic view permission can provide. As a result, SQL operations have their own set of permissions in the Hydrolix RBAC system, indicated by the _sql suffix.

For example:

• select_catalog_sql allows users to read the catalog, which contains metadata about table partitions
• insert_sql allows users to insert data into a table with INSERT statements
• select_sql allows users to read data from a table with SELECT statements, and also implicitly grants show_project_sql, show_table_sql, and show_columns_sql
• alter_table_sql allows users to change data within a table using ALTER statements
• show_columns_sql allows users to view column information within a table using SHOW COLUMNS
• show_tables_sql allows users to view a list of tables within a project using SHOW TABLES
• show_project_sql allows users to view a list of projects
• select_metadata_sql allows users to query table metadata

Users must have a subset of these permissions to perform SQL queries on data stored within the Hydrolix cluster.

Other permissions

Not all API endpoints perform operations that fit cleanly into the action categories of view, add, change, delete, or SQL operations. In these cases, Hydrolix provides additional permissions, including the following:

• retry to attempt a failed action again
• status to fetch the status of an action
• verify to confirm the validity of a proposed action
• commit to submit an action for later execution
• cancel to stop a submitted action from executing
• generate to create data using an automated process
• stats to fetch general information about a system
• activity to fetch a summary of activity within a resource
• populate to generate metadata based on existing data
• truncate to remove data based on some criteria