Permissions

Introduction

Access control rules are essential for securing your data and ensuring that only authorized users can access it. In Hasura, these are referred to as permissions. You can use permissions to control access to certain rows or columns in your database, or to restrict access to certain operations or fields in your GraphQL API.

The following types of permissions can be defined:

Type	Description
TypePermissions	Define which fields are allowed to be accessed by a role on an output type.
ModelPermissions	Define which objects or rows within a model are allowed to be accessed by a role.
CommandPermissions	Define whether the command is executable by a role.

VS Code extension assisted authoring

Permissions are written in your various HML files. If you're using a compatible editor (such as VS Code with the Hasura VS Code extension), assisted authoring will help you write permissions more efficiently. It will provide you with auto-completion, syntax highlighting, and error checking as you write your permissions.

Argument presets

Argument presets can be used to enforce row-level security. They can be defined on arguments for Types, Models and Commands.

Argument presets

Literals

For example, given a Command called get_article_by_id, with a single argument called id, you can prepopulate that argument for the user role.

kind: CommandPermissions
version: v1
definition:
  commandName: get_article_by_id
  permissions:
    - role: admin
      allowExecution: true
    - role: user
      allowExecution: true
      argumentPresets:
        - argument: id
          value:
            literal: 100

This means that admin users are able to provide whatever id they like to get_article_by_id, but the argument is not available in the GraphQL schema for the user role, and instead they always receive the same article every time.

Session variables

What might be a little more helpful is a a Command called get_articles_by_author_id, with a single argument called author_id. Here you can make it so that a user can only fetch articles with an author_id that matches their x-hasura-user-id header.

kind: CommandPermissions
version: v1
definition:
  commandName: get_articles_by_author_id
  permissions:
    - role: admin
      allowExecution: true
    - role: user
      allowExecution: true
      argumentPresets:
        - argument: id
          value:
            sessionVariable: x-hasura-user-id

This means admin users, once again, are able to provide their own author_id, but a user can only see the articles they have written.

Boolean expressions

We can also use argument presets to pass actual logical expressions to our data sources to control how they do things.

For example, a data connector might expose a Command called delete_user_by_id with two arguments - user_id and pre_check. user_id is the primary key of the user you'd like to remove, and pre_check lets you provide a custom boolean expression.

kind: CommandPermissions
version: v1
definition:
  commandName: delete_user_by_id
  permissions:
    - role: admin
      allowExecution: true
    - role: user
      allowExecution: true
      argumentPresets:
        - argument: pre_check
          value:
            booleanExpression:
              fieldComparison:
                field: is_invincible
                operator: _eq
                value:
                  literal: false

Now, when admin runs this command, once again, they can do what they want, and provide their own pre_check if they want. The user however, is able to pass a user_id argument, but the pre_check expression is passed to the data connector which will only let them delete the row if the row's is_invincible value is set to false.

Metadata structure

TypePermissions

Definition of permissions for an OpenDD type.

Key	Value	Required	Description
kind	TypePermissions	true
version	v1	true
definition	TypePermissionsV1	true	Definition of permissions for an OpenDD type.

Example:

kind: TypePermissions
version: v1
definition:
  typeName: article
  permissions:
    - role: admin
      output:
        allowedFields:
          - article_id
          - author_id
          - title
    - role: user
      output:
        allowedFields:
          - article_id
          - author_id

TypePermissionsV1

Definition of permissions for an OpenDD type.

Key	Value	Required	Description
typeName	CustomTypeName	true	The name of the type for which permissions are being defined. Must be an object type.
permissions	[TypePermission]	true	A list of type permissions, one for each role.

TypePermission

Defines permissions for a particular role for a type.

Key	Value	Required	Description
role	Role	true	The role for which permissions are being defined.
output	TypeOutputPermission / null	false	Permissions for this role when this type is used in an output context. If null, this type is inaccessible for this role in an output context.
input	TypeInputPermission / null	false	Permissions for this role when this type is used in an input context. If null, this type is accessible for this role in an input context.

Example:

role: user
output:
  allowedFields:
    - article_id
    - author_id
input:
  fieldPresets:
    - field: author_id
      value:
        sessionVariable: x-hasura-user-id

TypeInputPermission

Permissions for a type for a particular role when used in an input context.

Key	Value	Required	Description
fieldPresets	[FieldPreset]	false	Preset values for fields of the type

FieldPreset

Preset value for a field

Key	Value	Required	Description
field	FieldName	true	Field name for preset
value	ValueExpression	true	Value for preset

ValueExpression

An expression which evaluates to a value that can be used in permissions and various presets.

Must have exactly one of the following fields:

Key	Value	Required	Description
literal		false
sessionVariable	string	false	Used to represent the name of a session variable, like "x-hasura-role".
booleanExpression	ModelPredicate	false

ModelPredicate

A predicate that can be used to restrict the objects returned when querying a model.

Must have exactly one of the following fields:

Key	Value	Required	Description
fieldComparison	FieldComparisonPredicate	false	Field comparison predicate filters objects based on a field value.
fieldIsNull	FieldIsNullPredicate	false	Predicate to check if the given field is null.
relationship	RelationshipPredicate	false	Relationship predicate filters objects of a source model based on a predicate on the related model.
and	[ModelPredicate]	false
or	[ModelPredicate]	false
not	ModelPredicate	false

Example:

fieldComparison:
  field: author_id
  operator: _eq
  value:
    sessionVariable: x-hasura-user-id

RelationshipPredicate

Relationship predicate filters objects of a source model based on a predicate on the related model.

Key	Value	Required	Description
name	RelationshipName	true	The name of the relationship of the object type of the model to follow.
predicate	ModelPredicate / null	false	The predicate to apply on the related objects. If this is null, then the predicate evaluates to true as long as there is at least one related object present.

RelationshipName

The name of the GraphQL relationship field.

Value: string

FieldIsNullPredicate

Predicate to check if the given field is null.

Key	Value	Required	Description
field	FieldName	true	The name of the field that should be checked for a null value.

FieldComparisonPredicate

Field comparison predicate filters objects based on a field value.

Key	Value	Required	Description
field	FieldName	true	The field name of the object type of the model to compare.
operator	string	true	The name of the operator to use for comparison.
value	ValueExpression	true	The value expression to compare against.

TypeOutputPermission

Permissions for a type for a particular role when used in an output context.

Key	Value	Required	Description
allowedFields	[FieldName]	true	Fields of the type that are accessible for a role

FieldName

The name of a field in a user-defined object type.

Value: string

Role

The role for which permissions are being defined.

Value: string

CustomTypeName

The name of a user-defined type.

Value: string

ModelPermissions

Definition of permissions for an OpenDD model.

Key	Value	Required	Description
kind	ModelPermissions	true
version	v1	true
definition	ModelPermissionsV1	true	Definition of permissions for an OpenDD model.

Example:

kind: ModelPermissions
version: v1
definition:
  modelName: Articles
  permissions:
    - role: admin
      select:
        filter: null
    - role: user
      select:
        filter:
          fieldComparison:
            field: author_id
            operator: _eq
            value:
              sessionVariable: x-hasura-user-id

ModelPermissionsV1

Definition of permissions for an OpenDD model.

Key	Value	Required	Description
modelName	ModelName	true	The name of the model for which permissions are being defined.
permissions	[ModelPermission]	true	A list of model permissions, one for each role.

ModelPermission

Defines the permissions for an OpenDD model.

Key	Value	Required	Description
role	Role	true	The role for which permissions are being defined.
select	SelectPermission / null	false	The permissions for selecting from this model for this role. If this is null, the role is not allowed to query the model.

Example:

role: user
select:
  filter:
    fieldComparison:
      field: author_id
      operator: _eq
      value:
        sessionVariable: x-hasura-user-id
  argument_presets:
    - field: likes_dogs
      value:
        literal: true

SelectPermission

Defines the permissions for selecting a model for a role.

Key	Value	Required	Description
filter	null / ModelPredicate	true	Filter expression when selecting rows for this model. Null filter implies all rows are selectable.
argumentPresets	[ArgumentPreset]	false	Preset values for arguments for this role

ArgumentPreset

An argument preset that can be applied to all functions/procedures of a connector

Key	Value	Required	Description
argument	ArgumentName	true
value	ArgumentPresetValue	true

ArgumentPresetValue

Key	Value	Required	Description
httpHeaders	HttpHeadersPreset	true	HTTP headers that can be preset from request

HttpHeadersPreset

Configuration of what HTTP request headers should be forwarded to a data connector.

Key	Value	Required	Description
forward	[string]	true	List of HTTP headers that should be forwarded from HTTP requests
additional	AdditionalHttpHeaders	true	Additional headers that should be forwarded, from other contexts

AdditionalHttpHeaders

Additional headers that should be forwarded, from other contexts

Key	Value	Required	Description
<customKey>	ValueExpression	false

ArgumentName

Value: string

ModelPredicate

A predicate that can be used to restrict the objects returned when querying a model.

Must have exactly one of the following fields:

Key	Value	Required	Description
fieldComparison	FieldComparisonPredicate	false	Field comparison predicate filters objects based on a field value.
fieldIsNull	FieldIsNullPredicate	false	Predicate to check if the given field is null.
relationship	RelationshipPredicate	false	Relationship predicate filters objects of a source model based on a predicate on the related model.
and	[ModelPredicate]	false
or	[ModelPredicate]	false
not	ModelPredicate	false

Example:

fieldComparison:
  field: author_id
  operator: _eq
  value:
    sessionVariable: x-hasura-user-id

RelationshipPredicate

Relationship predicate filters objects of a source model based on a predicate on the related model.

Key	Value	Required	Description
name	RelationshipName	true	The name of the relationship of the object type of the model to follow.
predicate	ModelPredicate / null	false	The predicate to apply on the related objects. If this is null, then the predicate evaluates to true as long as there is at least one related object present.

RelationshipName

The name of the GraphQL relationship field.

Value: string

FieldIsNullPredicate

Predicate to check if the given field is null.

Key	Value	Required	Description
field	FieldName	true	The name of the field that should be checked for a null value.

FieldComparisonPredicate

Field comparison predicate filters objects based on a field value.

Key	Value	Required	Description
field	FieldName	true	The field name of the object type of the model to compare.
operator	string	true	The name of the operator to use for comparison.
value	ValueExpression	true	The value expression to compare against.

ValueExpression

An expression which evaluates to a value that can be used in permissions and various presets.

Must have exactly one of the following fields:

Key	Value	Required	Description
literal		false
sessionVariable	string	false	Used to represent the name of a session variable, like "x-hasura-role".
booleanExpression	ModelPredicate	false

FieldName

The name of a field in a user-defined object type.

Value: string

Role

The role for which permissions are being defined.

Value: string

ModelName

The name of data model.

Value: string

CommandPermissions

Definition of permissions for an OpenDD command.

Key	Value	Required	Description
kind	CommandPermissions	true
version	v1	true
definition	CommandPermissionsV1	true	Definition of permissions for an OpenDD command.

Example:

kind: CommandPermissions
version: v1
definition:
  commandName: get_article_by_id
  permissions:
    - role: admin
      allowExecution: true
    - role: user
      allowExecution: true

CommandPermissionsV1

Definition of permissions for an OpenDD command.

Key	Value	Required	Description
commandName	CommandName	true	The name of the command for which permissions are being defined.
permissions	[CommandPermission]	true	A list of command permissions, one for each role.

CommandPermission

Defines the permissions for a role for a command.

Key	Value	Required	Description
role	Role	true	The role for which permissions are being defined.
allowExecution	boolean	true	Whether the command is executable by the role.
argumentPresets	[ArgumentPreset]	false	Preset values for arguments for this role

Example:

role: user
allowExecution: true
argumentPresets:
  - argument: user_id
    value:
      session_variable: x-hasura-user_id

ArgumentPreset

An argument preset that can be applied to all functions/procedures of a connector

Key	Value	Required	Description
argument	ArgumentName	true
value	ArgumentPresetValue	true

ArgumentPresetValue

Key	Value	Required	Description
httpHeaders	HttpHeadersPreset	true	HTTP headers that can be preset from request

HttpHeadersPreset

Configuration of what HTTP request headers should be forwarded to a data connector.

Key	Value	Required	Description
forward	[string]	true	List of HTTP headers that should be forwarded from HTTP requests
additional	AdditionalHttpHeaders	true	Additional headers that should be forwarded, from other contexts

AdditionalHttpHeaders

Additional headers that should be forwarded, from other contexts

Key	Value	Required	Description
<customKey>	ValueExpression	false

ValueExpression

An expression which evaluates to a value that can be used in permissions and various presets.

Must have exactly one of the following fields:

Key	Value	Required	Description
literal		false
sessionVariable	string	false	Used to represent the name of a session variable, like "x-hasura-role".
booleanExpression	ModelPredicate	false

ModelPredicate

A predicate that can be used to restrict the objects returned when querying a model.

Must have exactly one of the following fields:

Key	Value	Required	Description
fieldComparison	FieldComparisonPredicate	false	Field comparison predicate filters objects based on a field value.
fieldIsNull	FieldIsNullPredicate	false	Predicate to check if the given field is null.
relationship	RelationshipPredicate	false	Relationship predicate filters objects of a source model based on a predicate on the related model.
and	[ModelPredicate]	false
or	[ModelPredicate]	false
not	ModelPredicate	false

Example:

fieldComparison:
  field: author_id
  operator: _eq
  value:
    sessionVariable: x-hasura-user-id

RelationshipPredicate

Relationship predicate filters objects of a source model based on a predicate on the related model.

Key	Value	Required	Description
name	RelationshipName	true	The name of the relationship of the object type of the model to follow.
predicate	ModelPredicate / null	false	The predicate to apply on the related objects. If this is null, then the predicate evaluates to true as long as there is at least one related object present.

RelationshipName

The name of the GraphQL relationship field.

Value: string

FieldIsNullPredicate

Predicate to check if the given field is null.

Key	Value	Required	Description
field	FieldName	true	The name of the field that should be checked for a null value.

FieldComparisonPredicate

Field comparison predicate filters objects based on a field value.

Key	Value	Required	Description
field	FieldName	true	The field name of the object type of the model to compare.
operator	string	true	The name of the operator to use for comparison.
value	ValueExpression	true	The value expression to compare against.

FieldName

The name of a field in a user-defined object type.

Value: string

ArgumentName

Value: string

Role

The role for which permissions are being defined.

Value: string

CommandName

The name of a command.

Value: string