Access control cookbook
This cookbook guides you through tutorials for the Fauna access control features. Each of these sections rely on the Shell and a simple Javascript application to teach you about access control in Fauna. See Get started for information on setting up the example code in your environment.
Overview
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.
Secure database access
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 members
and privileges
, in the context
of a key, Fauna only evaluates the role privileges
.
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 Key.create()
query.
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
header.
The following diagram shows how Fauna evaluates a query made with a key.
-
Fauna receives a key
secret
with a query. -
If the
secret
exists, Fauna looks up the associatedKey
document. -
If the
Key
exists and has not expired because ofttl
, Fauna evaluates therole
field associated with theKey
.The role
privileges
permit or deny the query execution. Fauna does not evaluate the rolemembership
when a<key_secret>
is the bearer. -
If the
privileges
permit it, Fauna executes the query and returns a response. Otherwise, the query isUnauthorized
.
Attribute-based access control (ABAC)
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
Fauna internal Token
identity-based access together with user-defined
roles to authorize queries.
The 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
queries.
Regardless of how it is created, a token has a required
identity document. The document
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.document
object in the database associated with the secret. If no association exists, the response isUnauthorized
. -
If the
Token
exists and has not expired because ofttl
, Fauna looks up the associated identitydocument
. If the identitydocument
does not exist, the response isUnauthorized
. -
If the identity document exists and has not expired because of
ttl
, Fauna evaluates user-defined roles whosemembership
correspond to thedocument.coll
. If none are found, the response isUnauthorized
. -
If
membership
is validated, Fauna evaluates theprivileges
defined on the role on the resource being queried. If the privileges do not allow the query, the response isUnauthorized
. -
If the
document
belongs to themembership
and hasprivileges
on theresource
the query is for, Fauna executes the query and returns a response.
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!