User Roles and Permissions Design Doc [DRAFT]

[mattdailis]

Table of Contents

1. Context and scope
2. Goals and non-goals
3. Design overview
   1. Default permissions
   2. System context diagram
   3. Implementing permissions
   4. API client implications
   5. UI implications
   6. User IDs

Context and scope

Up until recently, Aerie has had (UI-only) authentication, and no
differentiated authorization. The scope of this work is to imbue Aerie
with a first-class notion of users, and to introduce mechanisms for
restricting the actions of these users.

Goals and non-goals

Primary goal: give Aerie users some peace of mind:

• that their data is not visible to unauthenticated users
• that they can control who has write access to their plan
• that they themselves cannot accidentally make a change to a plan that they are not authorized to change

To achieve this goal, we set out to:

• Require all API access to be authenticated
• Limit the actions that authenticated users can take based on rules
• Facilitate plan access controls by adding the notion of a plan owner, and plan collaborators

We acknowledge that different deployments may have different needs, so we additionally wish to:

• Allow for flexibility for deployment-specific access controls

Non-goals:

• Explicit LDAP integration
• User groups
• UI support for customizing deployment permission rules
• Machine users
• Github-style access tokens

Design overview

In our initial cut of roles and permissions, we identified four distinct roles:

• Admin
• User
• Viewer
• Unauthenticated

Roles are coarse grained, and serve to put a user into a broad
category. The Admin role has no restrictions. The Unauthenticated role
applies to users who have not logged in, and it restricts all capabilities.

The Viewer role, by default, gives a user read-only access to all data
in Aerie.

In addition to read-only access to all data, the User role, by
default, gives a user selective access to certain data and
actions. For certain data and actions, access can be granted to users
on an individual basis. A single user at a time can be given ownership
of a particular plan (referred to as "plan owner"), and multiple users
can simulaneously be given write access to a plan (referred to as
"plan collaborators"). Plan owners and collaborators have write access
to the plans they are associated with, but not to other plans.

Default permissions

Expand below to see the full table of default permissions.

Table of default permissions

These are the default permissions defined by the Aerie system

Action	User	Viewer
Upload Mission Model	n	n
Delete Mission Model	n	n
View Mission Models	y	y
Update Mission Model	n	n
View Plan Metadata	y	y
Create a Plan	y	n
Update Plan Metadata	y (if plan owner)	n
Delete a Plan	y (if plan owner or collaborator)	n
Assign User as Plan Collaborator	y (if plan owner)	n
Assign User as Plan Owner	y (if plan owner)	n
Remove User as Plan Collaborator	y (if plan owner or collaborator)	n
Remove User as Plan Owner	y (if plan owner)	n

Activity Directives:

Action	User	Viewer
View Activities	y	y
Create Activities	y (if plan owner or collaborator)	n
Update Activities	y (if plan owner or collaborator)	n
Delete Activities	y (if plan owner or collaborator)	n
View Activity_Directives_Extended	y	y
View Activity Presets	y	y
Create Activity Presets	y	n
Update Activity Presets	y (if preset owner)	n
Delete Activity Presets	y (if preset owner)	n
Assign a Preset to an Activity Directive	y (if plan owner or collaborator)	n
View a Simulation Configuration	y	y
Update Simulation Arguments	y (if plan owner or collaborator)	n
Update Simulation Bounds	y (if plan owner or collaborator)	n
Delete a Simulation Configuration	n	n
Create a Simulation Configuration	n	n
View Simulation Presets	y	y
Create Simulation Preset	y	n
Delete Simulation Preset	y (if preset owner)	n
Update Simulation Preset	y (if preset owner)	n
Assign a Simulation Preset to a Simulation Configuration	y (if plan owner or collaborator)	n
View Simulation Datasets	y	y
Delete a Simulation Dataset	y (if plan owner or collaborator)	y
Update a Simulation Dataset	n	n
Create a Simulation Dataset	n	n
View External Datasets	y	y
Upload External Datasets	y (if plan owner)	n
Delete External Datasets	y (if plan owner)	n
Extend External Datasets	y (if plan owner)	n

Scheduling Goals and Conditions:

Action	User	Viewer
View Scheduling Goals	y	y
Create Scheduling Goals	y (if plan owner or collaborator)	n
Update a Scheduling Goal	y (if plan owner or collaborator)	n
Delete a Scheduling Goal	y (if plan owner or collaborator)	n
View Scheduling Conditions	y	y
Create Scheduling Conditions	y (if plan owner or collaborator)	n
Update a Scheduling Condition	y (if plan owner or collaborator)	n
Delete a Scheduling Condition	y (if plan owner or collaborator)	n

Constraints:

Action	User	Viewer
View Constraints	y	y
Create a Constraint	y (if plan owner or collaborator)	n
Update a Constraint	y (if plan owner or collaborator)	n
Delete a Constraint	y (if plan owner or collaborator)	n

Plan Branching and Merging (the "supplying" plan is being merged into the "receiving" plan):

Action	User	Viewer
Branch a Plan	y	n
Create a Merge Request	y (if owner of supplying)	n
Initiate a Merge Request Review	y (if owner of receiving)	n
Cancel a Merge Request Review	y (if owner of receiving)	n
Approve a Merge Request	y (if owner of receiving)	n
Reject a Merge Request	y (if owner of receiving)	n
Withdraw a Merge Request	y (if owner of supplying)	n
View an In-Progress Merge Request	y	y
Resolve a merge conflict	y (if owner of receiving)	n
Create a Comment on Merge Request	y (if owner or collaborator of either)	n
Edit a Comment on Merge Request	y (if comment author)	n
Delete a Comment on Merge Request	y (if comment author)
View Comments on Merge Request	y	y

Command Dictionaries:

Action	User	Viewer
Upload a Command Dictionary	y (should be customizable)	n
Delete a Command Dictionary	y (should be customizable)	n
View Command Dictionaries	y	y
Upload a SeqJson	y	n
Create a Sequence	y	n
Update a Sequence	y (if sequence author)	n
View a SeqJson	y	y
View a Sequence	y	y
Generate a SeqJson	y	y
Download a SeqJson	y	y
Delete a Sequence	y (if sequence author)	n

Command expansion rules:

Action	User	Viewer
Create an Expansion Rule	y	n
View an Expansion Rule	y	y
Update an Expansion Rule	y (if rule owner)	n
Delete an Expansion Rule	y (if rule owner)	n

UI Views:

Action	User	Viewer
Create a UI View	y	y
Upload a UI View	y	n
Update a UI View	y (if creator)	n
Delete a UI View	y (if creator)	n
Use a UI View	y	y

Actions:

Action	User	Viewer
Run Simulation	y (if plan owner or collaborator)	n
Run Scheduling	y (if plan owner or collaborator)	n
Run Scheduling Analysis	y	n
Run Constraints Checks	y (if plan owner or collaborator)	n
Run Command Expansion	y (if plan owner or collaborator))	n
Validate a Plan	y	y
Validate Mission Model Arguments	y	y
Validate Activity Arguments	y	y
Get Resource Samples	y	y
Get Resource Types	y	y
Get Effective Model Arguments	y	y
Make calls to Get Typescript	y	y
Run Migrations	n	n
Define New Roles	n	n

Other

Action	User	Viewer
View Activity Directive Metadata Schemas	y	y
Insert Activity Directive Metadata Schemas	y	n
Update Activity Directive Metadata Schemas	y	n
Delete Activity Directive Metadata Schemas	n	n
View Activity Anchor Validations	y	y
Insert Activity Anchor Validations	n	n
Update Activity Anchor Validations	n	n
Delete Activity Anchor Validations	n	n
Get Activity Types	y	y
Insert Activity Types	n	n
Update Activity Types	n	n
Delete Activity Types	n	n
View Mission Model Parameters Definition	y	y
Insert Mission Model Parameters Definition	n	n
Update Mission Model Parameters Definition	n	n
Delete Mission Model Parameters Definition	n	n

System context diagram

We wish to configure Hasura and the Gateway to levy access controls on the Client. The Gateway interfaces with CAM for authentication. See the runtime components and connectors diagram below to see which components communicate. Note that all interactions of a Client with the Aerie system happen through the Gateway and Hasura.

Connectors between entities in this diagram represent any form of network communication.

    flowchart TD
        C --- G[Gateway]
        C[\Client/] --- H[Hasura]
        H --- MSV[Merlin Service]
        H --- MDB[(Merlin Database)]
        H --- SSV[Scheduler Service]
        H --- SDB[(Scheduler Database)]
        H --- CSV[Sequencing Service]
        H --- CDB[(Sequencing Database)]
    
        MSV --- MDB
        SSV --- SDB
        CSV --- CDB
    
        %% H --- G
        G --- MDB
    
        subgraph Aerie
            G
            H
    
        subgraph Merlin
            MDB
            MSV
        end
    
        subgraph Scheduler
            SDB
            SSV
        end
    
        subgraph Sequencing
            CDB
            CSV
        end
    
        end
    
        CAM --- G

Loading

flowchart TD
    subgraph Legend
      DB[(Database)]
      SV[Service]
      CL[\API Client/]
    end

Loading

The authentication process starts with a login request to the Gateway
service. The Gateway forwards the request to CAM, and, if it succeeds,
receives a CAM session token. The Gateway uses a secret key to sign a
JSON Web Token (abbreviated JWT). This signed token contains the following information:

• The username used to log in
• The CAM session token
• Additional role information (to be discussed later in this document)

This token is not encrypted, but it is signed using symmetric
encryption key. This means that Hasura can use that same secret key to
verify the authenticity and integrity of this token.

    sequenceDiagram
        Client->>Gateway: Login request (username, password)
        Gateway->>CAM: Login request (username, password)
        CAM -->> Gateway: CAM session token
        Gateway -->> Client: JWT token
        Client ->> Hasura: API request, including JWT token in the Authorization header
        Hasura -->> Client: API response, if Hasura determined that the user has sufficient permissions for this request. "Unauthorized" otherwise.

Loading

Certain trusted clients can be given the Hasura "Admin" secret, which they can provide in requests to Hasura without going through the gateway.

    sequenceDiagram
        Client ->> Hasura: API request, including Admin token in the Authorization header
        Hasura -->> Client: API response (always authorized)

Loading

Implementing permissions

Hasura provides an expressive declarative rules language that we have
chosen to use to specify the majority of our permissions. It has the
advantage of being very granular, allowing for fine-grained control of
select, insert, update, and delete permissions on individual
tables. It is customizable via yaml files, making it easier to tweak
for a particular deployment.

Note: One of the docker containers we ship, aerie_hasura, internalizes
these yaml files. A mission would need to deploy hasura themselves to
and manage their own metadata make use of custom yaml files.

The tradeoff associated with fine granularity is that it can get a
little repetitive to set select, insert, update, and delete
permissions on every single table, for every role. Traversing long
chains of table relationships can also get quite verbose.

Here is an example of the Hasura permissions definition syntax. This
defines restrictions on operations involving activity directives. This
lives in the same API definition files that we use to expose certain
tables via the API:

    select_permissions:
      - role: user
        permission:
          # Need to specify all columns manually
          columns: [ id, plan_id, name, tags, source_scheduling_goal_id, created_at, last_modified_at, start_offset, type,
                     arguments, last_modified_arguments_at, metadata, anchor_id, anchored_to_start]
          filter: {}
          allow_aggregations: true
      - role: viewer
        permission:
          columns: [ id, plan_id, name, tags, source_scheduling_goal_id, created_at, last_modified_at, start_offset, type,
                     arguments, last_modified_arguments_at, metadata, anchor_id, anchored_to_start ]
          filter: {}
          allow_aggregations: true
    update_permissions:
      - role: user
        permission:
          columns: [name, tags, start_offset, arguments, metadata, anchor_id, anchored_to_start]
          filter: {"plan":{"_or":[{"owner":{"_eq":"X-Hasura-User-Id"}},{"collaborators":{"collaborator":{"_eq":"X-Hasura-User-Id"}}}]}}
    insert_permissions:
      - role: user
        permission:
          columns: [name, tags, start_offset, arguments, metadata, anchor_id, anchored_to_start, plan_id, type]
          check: {"plan":{"_or":[{"owner":{"_eq":"X-Hasura-User-Id"}},{"collaborators":{"collaborator":{"_eq":"X-Hasura-User-Id"}}}]}}
    delete_permissions:
      - role: user
        permission:
          filter: {"plan":{"_or":[{"owner":{"_eq":"X-Hasura-User-Id"}},{"collaborators":{"collaborator":{"_eq":"X-Hasura-User-Id"}}}]}}

Note that the filter field cross references the session header named
"X-Hasura-User-Id" with that activity directive's plan's owners and
collaborators.

As mentioned earlier in this document, the default set of roles
includes Admin, User, and Viewer. (Unauthenticated is a pseudo-role
that allows for permissions to be defined for clients who have not
logged in). These roles are to be stored in a table in the merlin
database. A mission that wishes to add new roles will need to add
these new roles to this table, as well as add permissions definitions
referring to these roles in the yaml files.

Notions such as "Plan owner" and "Plan collaborators" are not "Roles"
in the Hasura sense. A mission cannot add new concepts of this
sort. What they can do is customize the abilities of a plan owner or
collaborator.

API client implications

API clients are now required to provide an Authorization header with all requests. This header can be obtained using the Gateway's login endpoint, or it can be the admin key.

Queries from unauthenticated clients will receive error
responses. Similarly, queries that attempt to perform actions for
which a user does not have permission will also be rejected.

UI implications

In order to tailor a user interface to a particular user's
permissions, it is necessary to be able to query for the set of
permissible queries. Using the role of the given user, Hasura returns
a pared down version of the API schema. The absence of certain parts
of the schema indicates that the current user's role does not have
permission to take these actions - and a user interface can display
that information accordingly.

    query GetPermissibleQueries {
      queries: __schema {
        queryType {
          fields {
            name
          }
        }
        mutationType {
          fields {
            name
          }
        }
      }
    }

Note that notions of plan owners, collaborators, and similar notions
of ownership in other entities need to be handled separately - the
query above cannot provide nuance based on filters defined in the
permissions rules.

User IDs

We consider usernames to be mutable, and thus unreliable identifiers,
so we will assign each user a numeric user id.

This does introduce some difficulty in migrating existing data, which
has thus far used username strings. See "Problems left to solve" below.

Some changes involve:

• The JWT created by the Gateway will likely need to provide the user
  id either in place of or in addition to the username.
  • In the merlin database, we could get away with defining
    permissions that use a relationship to the users table. In other
    databases, we will need this id to be in a session header.
• Existing usernames will need to be assigned numeric ids.
• Records with such usernames will need to have their ids supplemented
  or replaced with their numeric counterparts.
  • In merlin this can be done using a hasura migration script that
    first collects the full set of existing usernames, bulk inserts
    them into the users table, and then proceeds to supplement or
    replace them by joining on the username.
  • In other databases, this migration cannot be done using a SQL
    migration script, since it relies on data from a different
    database.

[Mythicaeda]

Thanks for transcribing all of this information here!

I'd like to specify where the Additional role information (to be discussed later in this document) comes from, as I didn't see it mentioned: After the Gateway has authenticated the User via CAM, it will then get the User's role information from Hasura, specifically from a view in the AerieMerlin DB. This role information consists of the list of roles the User is allowed to use, as well as the default role the User makes queries under. If a User does not exist in this table, it will be added with a default role of user and an allowed role list of [user, viewer]. Only an admin may update these permissions.

[Mythicaeda]

Action and Hasura Function permissions:

Context:

Hasura only permits Actions and Hasura Functions to have binary allow/deny permissions per role. However, we need more fine-grained control while not hard-coding any permissions into our Java or SQL code. The solution we settled on was having these permissions declared per-role in the DB that our actions and functions will check before executing.

Design:

A new table will be created in Merlin, named user_role_permissions containing the following columns: role, which is a user role (and PK/FK), action_permissions, which is a jsonb, and function_permissions, which is a jsonb. A new table is being created rather than adding these to the user_roles table so that user_roles remains an enum compatible table, which allows for a cleaner GQL interface.

Each JSONB will have the structure { KEY_1: PERMISSION, KEY_2: PERMISSION, ... , KEY_N: PERMISSION }. The absence of a key will be considered equivalent to a role NOT having permission to perform the Action or Function.

Keys Permitted for `action_permissions`

Key	Hasura Action
check_constraints	constraintViolations
create_expansion_rule	addCommandExpansionTypeScript
create_expansion_set	createExpansionSet
expand_all_activities	expandAllActivities
insert_ext_dataset	addExternalDataset
resource_samples	resourceSamples
schedule	schedule
sequence_seq_json_bulk	getSequenceSeqJsonBulk
simulate	simulate

Any Actions not listed above will only have coarse-grained control.

Keys Permitted for `function_permissions`

Key	Hasura Function
apply_preset	apply_preset_to_activity
begin_merge	begin_merge
branch_plan	duplicate_plan
cancel_merge	cancel_merge
commit_merge	commit_merge
create_merge_rq	create_merge_request
create_snapshot	create_snapshot
deny_merge	deny_merge
delete_activity_reanchor	delete_activity_by_pk_reanchor_to_anchor
delete_activity_reanchor_bulk	delete_activity_by_pk_reanchor_to_anchor_bulk
delete_activity_reanchor_plan	delete_activity_by_pk_reanchor_plan_start
delete_activity_reanchor_plan_bulk	delete_activity_by_pk_reanchor_plan_start_bulk
delete_activity_subtree	delete_activity_by_pk_delete_subtree
delete_activity_subtree_bulk	delete_activity_by_pk_delete_subtree_bulk
get_conflicting_activities	get_conflicting_activities
get_non_conflicting_activities	get_non_conflicting_activities
get_plan_history	get_plan_history
restore_activity_changelog	restore_activity_changelog
restore_snapshot	restore_from_snapshot
set_resolution	set_resolution
set_resolution_bulk	set_resolution_bulk
withdraw_merge_rq	withdraw_merge_request

Any Functions not included here will only have coarse-grained control.

Allowed Values for `PERMISSION`

Permission	Meaning
NO_CHECK	The user may run the action/function with no restrictions. The aerie_admin role will always be treated as having NO_CHECK permissions on all Actions and Functions.
OWNER	The user must be the owner of all relevant objects directly used by the KEY
MISSION_MODEL_OWNER	The user must own the relevant Mission Model
PLAN_OWNER	The user must be the Owner of the relevant Plan
PLAN_COLLABORATOR	The user must be a Collaborator of the relevant Plan. The Plan Owner is NOT considered a Collaborator of the Plan
PLAN_OWNER_COLLABORATOR	The user must be either the Owner or a Collaborator of the relevant Plan

In general, OWNER is equivalent to PLAN_OWNER. Exceptions are as follows:

• apply_preset, where OWNER means a user must own both the plan and the preset

On Plan Merge Keys

The following Function Keys are in a group known as "Plan Merge Keys": begin_merge, cancel_merge, create_merge_rq, commit_merge, deny_merge, get_conflicting_activities, get_non_conflicting_activities, set_resolution, set_resolution_bulk, withdraw_merge_rq.

Plan Merge Keys are special, as they involve multiple plans. As such, there are special Permissions that may be used on these Keys. Additionally, the other Permissions take on a slightly different meaning when applied to a Plan Merge Key.

A complete list of what Permissions are allowed on Plan Merge Keys follows. Recall that the Source Plan is the one providing changes in a merge, and the Target Plan is the one to receive changes in a merge.

Permission	Meaning
NO_CHECK	The user may run the action/function with no restrictions. The aerie_admin role will always be treated as having NO_CHECK permissions on all Actions and Functions.
OWNER	The user must be the Owner of both Plans
MISSION_MODEL_OWNER	The user must be the Owner of the relevant Mission Model
PLAN_OWNER	The user must be the Owner of either Plan
PLAN_COLLABORATOR	The user must be a Collaborator of either Plan. The Plan Owner is NOT considered a Collaborator of the Plan
PLAN_OWNER_COLLABORATOR	The user must be either the Owner or a Collaborator of either Plan
PLAN_OWNER_SOURCE	The user must be the Owner of the Source Plan.
PLAN_COLLABORATOR_SOURCE	The user must be a Collaborator of the Source Plan.
PLAN_OWNER_COLLABORATOR_SOURCE	The user must be either the Owner or a Collaborator of the Source Plan.
PLAN_OWNER_TARGET	The user must be the Owner of the Target Plan.
PLAN_COLLABORATOR_TARGET	The user must be a Collaborator of the Target Plan.
PLAN_OWNER_COLLABORATOR_TARGET	The user must be either the Owner or a Collaborator of the Target Plan.