Role

Description

Roles are the core of an attribute-based access control (ABAC) schema. Role is a native collection of user-defined roles. These roles extend the built-in access roles, admin, server, client, or server-readonly.

Only resources with an admin key can create or manage user-defined roles. Roles are created in the current database. To establish the same roles throughout a database hierarchy, you must separately create identical roles in each child database that requires them.

Avoid using the deprecated, built-in client role.

Unlike user-defined collections, the Role collection has a predefined document structure. The structure is system defined and immutable. Role documents are accessed by their name parameter, which makes the collection a part of the subset of native collections known as named collections.

A role document structure has privileges and membership arrays. privileges associate a Fauna resource with predefined, permitted actions. A resource can be a Collection, or user-defined function (UDF).

A membership array authorizes users or processes to use the privileges. Membership specifies a Collection of members and an optional predicate function that validates members. Without this function, all collection members have the role and its privileges.

Roles work together with one of the Token, Key, or AccessProvider native collections. The following table explains how Fauna evaluates role privileges and membership depending on whether the caller is attempting to access resources by using a Token, Key, or AccessProvider.

Present Role participation

Present	Role participation
`Token`	Internal authentication by Fauna. Fauna evaluates stored `Credential` to authenticate a caller. Role `membership` and `privileges` are evaluated to grant authorization.
`Key`	Internal authorization without the use of identity authentication. Presentation of a Fauna key secret enables the caller. Only the role `privileges` are evaluated to grant authorization.
`AccessProvider`	External authentication by an identity provider (IdP). A third-party caller supplies the JWT secret from the provider. The JWT is matched to an `AccessProvider` document to authenticate the caller. The predicates on the provider document and the role `privileges` together are evaluated to grant authorization.

Token

Internal authentication by Fauna. Fauna evaluates stored Credential to authenticate a caller. Role membership and privileges are evaluated to grant authorization.

Key

Internal authorization without the use of identity authentication. Presentation of a Fauna key secret enables the caller. Only the role privileges are evaluated to grant authorization.

AccessProvider

External authentication by an identity provider (IdP). A third-party caller supplies the JWT secret from the provider. The JWT is matched to an AccessProvider document to authenticate the caller. The predicates on the provider document and the role privileges together are evaluated to grant authorization.

See the Role document definition

Static methods

Method Description

Method	Description
`Role.all()`	Get the set of all roles.
`Role.byName()`	Get a role by its name.
`Role.create()`	Create a role.
`Role.firstWhere()`	Get the first role matching a predicate function.
`Role.where()`	Get roles matching a predicate function.

Role.all()

Get the set of all roles.

Role.byName()

Get a role by its name.

Role.create()

Create a role.

Role.firstWhere()

Get the first role matching a predicate function.

Role.where()

Get roles matching a predicate function.