Roles & Session variables¶

Roles¶

Every table/view can have permission rules for users based on their role.

By default, there is an admin role that can perform any operation on any table.

You can define roles and then create permissions for each of these roles:

Examples:

See this page on how to configure permission rules.

Dynamic session variables¶

Permission rules can also refer to session variables. Session variables are key-value pairs returned from the authentication service for each request.

For example: If a user makes a request, the session token maps to a user-id. This user-id can be used in a permission to show that inserts into a table are only allowed if the user_id column has a value equal to that of user-id, the session variable.

When you are constructing permission rules, however, there might be several variables that represent the business logic of having access to data. For example, if you have a SaaS application, you might restrict access based on a client_id variable. If you want to provide different levels of access on different devices, you might restrict access based on a device_type variable.

Hasura allows you to create permission rules that can use any dynamic variable that is a property of the request. All your dynamic variables must follow the naming convention X-Hasura-*.

Examples:

{
  "user_id": {
    "_eq": "X-Hasura-User-Id"
  }
}

{
  "project_id": {
    "_eq": "X-Hasura-Project-Id"
  }
}

Modelling Roles in Hasura¶

General guidelines for modelling roles in Hasura.

Roles are typically modelled in two ways:

1. Hierarchical roles: Access scopes are nested depending on available roles. Roles in GitHub for organisations is a great example of such modelling where access scopes are inherited by deeper roles:

   

2. Flat roles: Non-hierarchical roles with each role requiring an independent access scope to be defined.

Roles in Hasura have to be defined in the latter way i.e. in a flat, non-hierarchical model.

To convert the above hierarchical roles model into the one expected by Hasura, you will need to model roles as partially captured by the table below (showing access permissions for the user & org-member roles, repositories table and select operation):

{
  "creator_id": {
    "_eq": "X-Hasura-User-Id"
   }
 }

{
  "_or": [
    {
      "creator_id": {
        "_eq": "X-Hasura-User-Id"
      }
    },
    {
      "organization": {
        "members": {
          "member_id" : {
            "_eq" : "X-Hasura-User-Id"
          }
        }
      }
    }
  ]
}

{
  "_or": [
    {
      "creator_id": {
        "_eq": "X-Hasura-User-Id"
      }
    },
    {
      "organization_id": {
        "_in": "X-Hasura-Allowed-Organisations"
      }
    }
  ]
}

Format of session variables¶

Session variables are currently expected to be Strings and should be encoded as Postgres’s literals for the relevant type.

For example, in the above example, let’s say creator_id and organisation_id columns are of type integer, then the values of X-Hasura-User-Id and X-Hasura-Allowed-Organisations should be of type integer and integer[] (an integer array) respectively. To pass say a value 1 for X-Hasura-User-Id, it’ll be “1” and if the allowed organisations are 1, 2 and 3, then X-Hasura-Allowed-Organisations will be “{1,2,3}”. {} is the syntax for specifying arrays in Postgres.

The types and their formats are detailed here. When in doubt about the Postgres format for a type, you can always test it in the SQL window. To check if s is a valid literal for type t then, you can check it as follows:

select 's'::t;

If the above command returns data, then s is a valid literal of type t. For example, to check if {hello,world} is a valid format of type text[], you can run:

select '{hello,world}'::text[];