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.

How Fauna accepts the secret for a key

  1. Fauna receives a key secret with a query.

  2. If the secret exists, Fauna looks up the associated Key document.

  3. If the Key exists and has not expired because of ttl, Fauna evaluates the role field associated with the Key.

    The role privileges permit or deny the query execution. Fauna does not evaluate the role membership when a <key_secret> is the bearer.

  4. If the privileges permit it, Fauna executes the query and returns a response. Otherwise, the query is Unauthorized.

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.

Identity-based authentication

  1. A client sends a Fauna query and includes the Authorization: Bearer <token_secret> in the HTTP header.

  2. 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 is Unauthorized.

  3. If the Token exists and has not expired because of ttl, Fauna looks up the associated identity document. If the identity document does not exist, the response is Unauthorized.

  4. If the identity document exists and has not expired because of ttl, Fauna evaluates user-defined roles whose membership correspond to the document.coll. If none are found, the response is Unauthorized.

  5. If membership is validated, Fauna evaluates the privileges defined on the role on the resource being queried. If the privileges do not allow the query, the response is Unauthorized.

  6. If the document belongs to the membership and has privileges on the resource 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!