ABAC privileges and membership
Attribute-based access control (ABAC) is a flexible, fine-grained strategy for managing identity-based operations in Fauna. ABAC extends the default authentication and authorization mechanisms.
ABAC is an extension of traditional role-based access control (RBAC), where roles can define privileges that can be dynamically evaluated based on any attribute of the actor trying to access or change data, any attribute of the data to be accessed or modified. For example, the document state or contextual information available during a transaction.
A role defines a set of privileges, which are actions that can be executed on given resources, and membership, which define the identities that should have the privileges.
Identities or resources are changes are evaluated on every query. For example, if manager membership is removed for Carol, she can no longer access manager-level resources.
The identity of an actor is defined by the Token included in the query sent to Fauna. When the token is valid, and the token-associated identity is listed in a role membership, the query operations are evaluated against the privileges defined by the role. If the required privileges are granted, the query is permitted to execute.
ABAC roles configure membership and privileges for the current database. It isn’t possible to define roles that affect child databases.
If you have defined ABAC roles that should also apply to child databases, you must establish those roles in each child database that requires them.
The Fauna access control logic uses attribute-based access control (ABAC) roles or the key-based permission system.
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 evaluates if read, write, or execute privileges are enabled.
For example, when an ABAC role includes a user-defined function as a
member, that function can’t be called unless the ABAC privileges permit
the call action.
Privileges
A privilege specifies a resource in Fauna, where the resource can be a database, collection, document, key, index, function, or other entities, and a set of predefined actions to permit.
Privileges associated with containers, such as databases and collections, also apply to the resources in the container.
The available actions are:
| Action | Permission | Applicable resource |
|---|---|---|
|
Permit calling a UDF. |
UDFs |
|
Permit resource creation. |
Documents and core schemas, including databases, collections, indexes, functions, and keys |
|
Permit resource deletion. |
Documents and core schemas, including databases, collections, indexes, functions, and keys |
|
(not currently implemented) Permit reads on historical versions of a resource. |
Documents |
|
(not currently implemented) Permit writes to historical versions of a resource. |
Documents |
|
Permit reads on a resource. |
Documents |
|
Permit reading an index without considering |
Indexes |
|
Permit writes to a resource. |
Documents |
Action permissions are a whitelist. They define permitted actions. The default is that no actions are permitted.
Action permissions can use a predicate to evaluate permissions dynamically. For example, an action might be permissible only during a period of the day.
Action permissions apply only to the given resource and its
contents, and not to nested resource contents. For example,
specifying Collections() as a resource can be used to grant or deny
privileges on all of the collection documents that exist but not to the
documents in those collections. To grant permissions to documents in
a collection, you have to specify a particular collection as a resource.
There is no wildcard collection expression available.
For a given resource, there may be multiple privileges defined in separate roles. When a resource is queried, permission is granted to process the action if any privilege grants the action.
user-defined
functions (UDFs) can be created to
have a role, such as role: "admin". This allows UDFs to execute with
given privileges, which might be higher than those of the caller.
This is useful in many scenarios. For example, a "complete_order" function that completes a financial transaction might access collections and documents that the user calling the function doesn’t otherwise have access to.
You should be careful when granting create and call privileges
for UDFs because an otherwise unprivileged user might create a function with
role: "admin" and then call it to create a new key with the admin
role. This situation exists for the server role, too, because it has
implicit access to the create and call privileges.
Membership
Membership describes the set of documents that should have the role privileges.
Membership is managed with a collection. Documents in the collection are members of the role. Typically, a document refers to a user, but a document can be any record in Fauna. For example, Fauna access keys can be assigned a role, which is useful for background processes.
Membership can also be controlled with a predicate function for dynamic membership evaluation. For example, membership for some users might be available only during a interval of the day.
Multiple roles can be associated with a Fauna resource, and users can be associated with multiple roles. Attribute-based access is computed for every Fauna transaction, including index filtering. Action permissions can be computed dynamically using anonymous functions.
Predicates
A predicate is a read-only anonymous function that accepts arguments
and returns true or false to indicate if the action is permitted or
prohibited.
Predicates run with server-level permissions, regardless of the access level of the identity calling the function. This is because the function needs to be able to evaluate access to all calling identity declared resources to make privilege determinations.
The actions and their associated arguments are:
-
create: the new data that is about to be created. -
read,history_read,delete: the ref to the underlying document. -
readfor indexes: the terms being used to match against the index. -
write,history_write: the old data, the new data, and a reference to the document to be written. -
call: the parameters to be passed to the user-defined function.
Considerations
The following considerations are offered as guidelines for using the ABAC feature:
-
It is possible to lock yourself out using your current secret/token. You can recover access using the Fauna Dashboard.
-
Define only as many roles as you need.
-
Use predicates only when needed.
-
Provide role membership only to those users that must be members.
-
Limit the scope of operations used in ABAC role predicates wherever possible. ABAC roles are evaluated for every query, which can impact overall performance.
-
While ABAC roles can be used to filter out documents that should not be readable by the current client, such filtering can involve evaluating every document in a collection. Instead, use indexes for filtering.
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!