User-defined roles

User-defined roles provide configurable, domain-specific security rules. They are the core schema for attribute-based access control. Roles are created with the CreateRole function, and have the following structure:

Field name Value type Description

name

String

The role’s name.

privileges

VarArgs

One or more privilege configuration objects.

membership

VarArgs

Optional. One or more membership configuration objects.
User-defined roles can only be managed with an admin key.

Beginning with FaunaDB 2.11.0, the FaunaDB access control logic has been changed to use attribute-based access control (ABAC) roles, or the key-based permission system, but never both.

If a resource is a member of an ABAC role, the ABAC role specifies all privileges for that resource. Otherwise, the key-based permission system determines whether read/write/execute privileges are enabled.

For example, when an ABAC role includes a user-defined function as a member, that function cannot be called unless the ABAC privileges permit the call action.

Privilege configuration object

A privilege configuration object defines, for a given resource, what actions are permitted.

Field name Value type Description

resource

Reference

A reference to a collection, index, set, or user-defined function.

actions

Object

An object containing key-value pairs, where the keys are action names, and the values are either a boolean value to indicate whether access is permitted, or a predicate function that can compute whether access is permitted.

The available actions are:

  • create: permits the create of new documents, collections, or set.

  • delete: permits the deletion of existing documents, collections, or sets.

  • read: permits the reading of documents, collections, sets, or indexes.

  • write: permits writing to existing documents within a collection.

  • history_read: permits reading historical versions of a document, collection, or set.

  • history_write: permits inserting events into the history for an existing document or set.

  • unrestricted_read: permits the reading of an index without considering any other read permissions.

  • call: permits the calling of user-defined functions.

When configuring read access to an index, both the read and unrestricted_read actions are permitted. The read action grants access to the index’s data. However, an additional read permission check is performed before allowing access to the indexed document, which filters out references that the user cannot read. The unrestricted_read action disables the additional check, returning all of the documents associated with the index.

An action’s value can be a boolean, to indicate whether the action is permitted or not, or a read-only lambda predicate function. Lambda predicate functions must be created using a query, using the same format that the CreateFunction function accepts. The predicate function takes different parameters depending on the configured action. Predicates must return a boolean value where true grants the action, and false denies it.

The parameters to a predicate function are:

Action Argument(s) Description

create

Object

An object containing the new document’s data.

delete

Reference

The reference to the document to be deleted.

read

Reference, or index terms

A reference to the document to be read, or one or more terms to be matched against the target index.

write

Object, Object, Reference

Three parameters:

  1. An object containing the original document data.

  2. An object containing the new document data (to be written).

  3. A reference to the document to be written.

history_read

Reference

The reference to the document to be read.

history_write

Reference, Timestamp, String, Object

Four parameters:

  1. The reference to the document to be written.

  2. The timestamp to write to, which may create or update an event depending on existence of a matching timestamp.

  3. The action string.

  4. An object containing the new document data.

unrestricted_read

Index terms

The terms matched against the target index.

call

Array

The parameters that are to be passed to the user-defined function.

Membership configuration object

A membership configuration object dynamically defines which authenticated resources are members of a given role. Tokens is covered in the next section.

Field name Value type Description

resource

Reference

A reference to a collection in which its documents are members of the configured role.

predicate

Query

Optional. A read-only lambda predicate function that takes the reference of the authenticated resource and returns a boolean value that indicates whether the referenced resource is a member of the configured role.

Tokens

Tokens, like keys, allow direct access to FaunaDB. Their use is optional. Each token is created by calling the Login function with a reference to a document that has credentials defined, and a password.

Once a token has been created, it can be used to connect to FaunaDB and execute queries in the same database as the credentialed document. Queries executed with a token have Attributed-based access control (ABAC) permissions applied. When a document is a member of a user-defined role, that role is used to evaluate that the query privileges available to that document.

Next steps

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve! documentation@fauna.com

Thank you for your feedback!