Access control cookbook
Access control requires the ability to authenticate a caller to connect to a Fauna database and then authorize actions by the caller on database resources. Successful use of these features enables you to secure access to your business-critical data in Fauna.
Commonly, authentication and authorization are implemented in the application layer. Fauna centralizes these in the database. As a result, applications can become database clients without needing to implement authentication or authorization.
The Fauna access control makes it easy to query databases from any network-connected context, including a web browser. Connections to the database are secured using HTTPS. After a caller authenticates to a database, Fauna uses attribute-based access control (ABAC) features to authorize the actions a caller can take.
You can use database keys to secure access to your databases. Keys are an internal Fauna access feature that does not use identity. Instead, to access data with a key the caller must have the key secret. Access is anonymous because any caller with the secret can use the key.
A key also has a corresponding
Role which can be a built-in Fauna role or
a custom role. While roles can have
privileges, in the context
of a key, Fauna only evaluates the role
Keys do not expire. A key secret can be used in many queries until the key
becomes invalid or is deleted. You can create a key using the
Manage Keys icon on the database or using the
Users can supply a key secret in the Dashboard Shell by choosing the
Secret option in the run menu. External clients must send a query and
include a key secret as an
Authorization:Bearer <key_secret> in the HTTP
The following diagram shows how Fauna evaluates a query made with a key.
Fauna receives a key
secretwith a query.
secretexists, Fauna looks up the associated
Keyexists and has not expired because of
ttl, Fauna evaluates the
rolefield associated with the
privilegespermit or deny the query execution. Fauna does not evaluate the role
<key_secret>is the bearer.
privilegespermit it, Fauna executes the query and returns a response. Otherwise, the query is
An application can be a client of a Fauna database without needing to
recreate authentication or authorization logic. In this section of the
Access control cookbook cookbook, you learn how to use the
Token identity-based access together with user-defined
roles to authorize queries.
Token collection supports identity access. There are two ways to create a
token. When a person, system, or process is successfully authenticated by
Credential.login() or by using the
Token.create() method directly. These
methods return a token
secret which can be stored and used for subsequent
Regardless of how it is created, a token has a required
identity document. The
object has an
id and a
coll value. Multiple tokens can exist for an
identity, so callers can use tokens to provide identity-based access to a
single database from multiple devices simultaneously.
This diagram shows Fauna authorizes queries from client applications.
A client sends a Fauna query and includes the
Authorization: Bearer <token_secret>in the HTTP header.
If the secret exists on the database, Fauna looks up the associated
Token.documentobject in the database associated with the secret. If no association exists, the response is
Tokenexists and has not expired because of
ttl, Fauna looks up the associated identity
document. If the identity
documentdoes not exist, the response is
If the identity document exists and has not expired because of
ttl, Fauna evaluates user-defined roles whose
membershipcorrespond to the
document.coll. If none are found, the response is
membershipis validated, Fauna evaluates the
privilegesdefined on the role on the resource being queried. If the privileges do not allow the query, the response is
documentbelongs to the
resourcethe query is for, Fauna executes the query and returns a response.
Is this article helpful?
Tell Fauna how the article can be improved:
Thank you for your feedback!