role

Learn: Roles

Defines a user-defined role. A role determines an authentication secret’s privileges, which control data access.

Fauna stores user-defined roles as documents in the Role system collection. See Role.

role manager {
  membership Manager

  membership User {
    predicate (user => user.accessLevel == 'manager')
  }

  privileges Product {
    create
    read
    write
    delete
  }

  privileges User {
    read {
      predicate (doc => Query.identity() == doc)
    }
  }

  privileges inventory {
    call
  }

  privileges submitOrder {
    call {
      predicate (args => Query.identity() == arg[0])
    }
  }
}

Syntax

role <role> {
  [membership <collection> [{
    predicate <predicate>
  }] . . .]

  [privileges <resource> {
    <action> [{
      predicate <predicate>
    }] . . .
  } . . .]
}

Name

role Required

Unique name for the role in the database.

Must begin with a letter. Can only include letters, numbers, and underscores. admin and server are reserved and can’t be used.

Properties

Property Required Description

membership

Assigns the role to tokens based on the token’s identity document. See Membership definition.

privileges

Allows one or more actions on a resource. See Privileges definition.

Membership definition

role manager {
  membership Manager

  membership User {
    predicate (user => user.accessLevel == 'manager')
  }
  ...
}
Property Required Description

collection

Yes

Name of a user-defined collection.

Fauna assigns the role to tokens with an identity document in the collection.

predicate

Predicate used to conditionally assign the role. If the predicate is not true, the role is not assigned.

The predicate is passed one argument: an object containing the token’s identity document.

The predicate runs with the built-in server role’s privileges. Supports shorthand syntax.

Privileges definition

role manager {
  ...
  privileges Product {
    create
    read
    write
    delete
  }

  privileges User {
    read {
      predicate (doc => Query.identity() == doc)
    }
  }
  ...
}
Property Required Description

resource

Yes

Name of a collection or user-defined function (UDF). Supports user-defined collections and the following system collections:

  • AccessProvider

  • Collection

  • Credential

  • Database

  • Function

  • Key

  • Role

  • Token

action

Yes

Type of operation allowed on the resource. Privileges support different actions based on the resource type. See Privilege actions.

predicate

Predicate used to conditionally grant the privilege. If the predicate is not true, the privilege is not granted.

Privilege predicates are passed different arguments based on their action. See Privilege predicate arguments.

The predicate runs with the built-in server role’s privileges. Supports shorthand syntax.

Privilege actions

Privileges support different actions based on their resource type.

Resource type Action Allows you to …​

User-defined function (UDF)

call

Call the function.

Collection

create

Create documents in the collection.

Collection

delete

Delete documents in the collection.

Collection

read

Read documents in the collection.

Collection

write

Update or replace documents in the collection.

Collection

history_read

Reserved. Do not use.

Collection

history_write

Reserved. Do not use.

Collection

unrestricted_read

Reserved. Do not use.

Privilege predicate arguments

Privilege predicates are passed different arguments based on their action.

Action Predicate function signature Parameter description

create

(doc: Object) => Boolean | Null

doc: Object containing the document to create. Includes document metadata.

delete

(doc: Object) => Boolean | Null

doc: Object containing the document to delete. Includes document metadata.

read

(doc: Object) => Boolean | Null

doc: Object containing the document to read. Includes document metadata.

write

(oldDoc: Object, newDoc: Object) ⇒ Boolean | Null

oldDoc: Object containing the original document. Includes document metadata.

newDoc: Object containing the document to write. Includes document metadata.

call

(args: Array) => Boolean | Null

Array containing the function call’s arguments.

Examples

role manager {

  // Assign the `manager` role to tokens with
  // an identity document in the `Manager` collection.
  membership Manager

  // If the predicate is `true`,
  // assign the `manager` role to tokens with
  // an identity document in the `User` collection.
  membership User {
    // Check that the identity document's
    // `accessLevel` field value is `manager`
    predicate (user => user.accessLevel == 'manager')
  }

  // Grant full access to `Store` collection documents.
  privileges Store {
    create
    read
    write
    delete
  }

  // Grant `read` access to `Customer` collection documents.
  privileges Customer {
    read
  }

  // If the predicate is `true`,
  // grant `read` access to `Manager` collection documents.
  privileges Manager {
    read {
      predicate (doc =>
        // Check that the `ManagerProfile` document
        // is the token's identity document.
        // `Query.identity()` is `null` (falsy) for JWTs or keys.
        Query.identity() == doc &&
        // Check that it's a weekday.
        Date.today().dayOfWeek < 6)
      )
    }
  }

  // Grant the ability to call the user-defined
  // `inventory()` function.
  privileges inventory {
    call
  }

  // If the predicate is `true`,
  // grant the ability to call the user-defined
  // `submitOrder()` function.
  privileges submitOrder {
    call {
      // Check that the function's
      // `customer` argument (`arg[0]`) is
      // the token's identity document.
      predicate (args => Query.identity() == arg[0])
    }
  }
}

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!