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.

How TypePermissions work

Lifecycle

By default, whenever a new type is created in your supergraph, each field is only accessible to the admin role. You can think of these as permissions on columns in a database table.

You can quickly generate new roles by adding a new item to the permissions array in the TypePermissions object. Each item in the array should have a role field and an output field. The output field should contain an allowedFields array, which lists the fields that are accessible to the role when the type is used in an output context.

To make a new TypePermission or role available in your supergraph, you'll need to create a new build using the CLI.

Examples

---
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

Field	Description	Reference
kind	Indicates that this object is defining permissions for a specific type.	TypePermissions
version	Specifies the version of the type permissions structure.	TypePermissionsV1
definition.typeName	The name of the type for which permissions are being defined.	CustomTypeName
definition.permissions	A list of permissions specifying which fields are accessible for different roles.	TypePermission
definition.permissions[].role	The role for which permissions are being defined.	Role
definition.permissions[].output.allowedFields	The fields of the type that are accessible for a role when the type is used in an output context.	TypeOutputPermission

How ModelPermissions work

Lifecycle

By default, whenever a new model is created in your supergraph, all records are only accessible to the admin role. You can think of these as permissions on rows in a database table.

You can restrict access to certain rows by adding a new item to the permissions array in the ModelPermissions object. Each item in the array should have a role field and a select field. The select field should contain a filter expression that determines which rows are accessible to the role when selecting from the model.

Most commonly, you'll use session variables — provided via your configured authentication mechanism — to restrict access to rows based on the user's identity or other criteria. You can also use argument presets to enforce row-level security. You can see an example of this below.

To make a new ModelPermission or role available in your supergraph, after updating your metadata, you'll need to create a new build using the CLI.

Examples

---
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

Field	Description	Reference
kind	Indicates that this object is defining permissions for a specific model.	ModelPermissions
version	Specifies the version of the model permissions structure.	ModelPermissionsV1
definition.modelName	The name of the model for which permissions are being defined.	ModelName
definition.permissions	A list of permissions specifying which rows or objects are accessible for different roles.	ModelPermission
definition.permissions[].role	The role for which permissions are being defined.	Role
definition.permissions[].select.filter	A filter expression that determines which rows are accessible for this role when selecting from the model.	ModelPredicate

How CommandPermissions work

Lifecycle

By default, whenever a new command is created in your supergraph, it is only executable by the admin role.

You can enable or restrict access to commands by adding a new item to the permissions array in the CommandPermissions object. Each item in the array should have a role field and an allowExecution field. The allowExecution field should be set to true if the command is executable by the role.

Further, you can use argument presets to pass actual logical expressions to your 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.

To make a execution of a command available to a role in your supergraph, after updating your metadata, you'll need to create a new build using the CLI.

Examples

---
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

Field	Description	Reference
kind	Indicates that this object is defining permissions for a specific command.	CommandPermissions
version	Specifies the version of the command permissions structure.	CommandPermissionsV1
definition.commandName	The name of the command for which permissions are being defined.	CommandName
definition.permissions	A list of permissions specifying whether the command is executable by different roles.	CommandPermission
definition.permissions[].role	The role for which permissions are being defined.	Role
definition.permissions[].allowExecution	Indicates whether the command is executable by the role.	CommandPermission
definition.permissions[].argumentPresets	Preset values for arguments that are enforced when the command is executed by the role.	ArgumentPreset

---

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

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.

Examples:

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

kind: ModelPermissions
version: v1
definition:
  modelName: Articles
  permissions:
    - role: admin
      select:
        filter: null
    - role: user
      select:
        filter:
          relationship:
            name: author
            predicate:
              fieldComparison:
                field: 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
allowSubscriptions	boolean	false	Whether the role is allowed to subscribe to the root fields of this model.

ArgumentPreset

Preset value for an argument

Key	Value	Required	Description
argument	ArgumentName	true	Argument name for preset
value	ValueExpressionOrPredicate	true	Value for preset

ValueExpressionOrPredicate

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

ArgumentName

The name of an argument.

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

Examples:

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

relationship:
  name: author
  predicate:
    fieldComparison:
      field: id
      operator: _eq
      value:
        sessionVariable: x-hasura-user-id

and:
  - fieldComparison:
      field: author_id
      operator: _eq
      value:
        sessionVariable: x-hasura-user-id
  - fieldComparison:
      field: title
      operator: _eq
      value:
        literal: Hello World

not:
  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	OperatorName	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

OperatorName

The name of an operator

Value: string

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

Preset value for an argument

Key	Value	Required	Description
argument	ArgumentName	true	Argument name for preset
value	ValueExpressionOrPredicate	true	Value for preset

ValueExpressionOrPredicate

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

Examples:

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

relationship:
  name: author
  predicate:
    fieldComparison:
      field: id
      operator: _eq
      value:
        sessionVariable: x-hasura-user-id

and:
  - fieldComparison:
      field: author_id
      operator: _eq
      value:
        sessionVariable: x-hasura-user-id
  - fieldComparison:
      field: title
      operator: _eq
      value:
        literal: Hello World

not:
  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	OperatorName	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

OperatorName

The name of an operator

Value: string

FieldName

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

Value: string

ArgumentName

The name of an argument.

Value: string

Role

The role for which permissions are being defined.

Value: string

CommandName

The name of a command.

Value: string