User-defined roles

User-defined roles provide configurable, domain-specific security rules. They are the core schema for role-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.

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

Two objects, one containing the original document data, and the second containing the new document data to be written.

history_read

Reference

The reference to the document to be read.

history_write

Reference, Timestamp, String, Object

The reference to the document to be written, the timestamp to write to (which may create or update an event depending on existence of a matching timestamp), the action string, and an object containing the new document data.

unrestricted_read

Index terms

The terms matched against the target index.

call

Parameters

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 by application users. Their use is optional. Where keys provide database-level access, each token has an associated document. Requests made with a token apply resource-level permission checks based on its document. When a document is a member of a user-defined role, that role is used to evaluate the user’s permissions.

Both server and client keys can generate tokens. Token generation with a client key requires a password. The password is optional when using a server key, but is verified if provided.

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!