Tokens

reference:

Token

Fauna tokens provide identity-based access to a database.

An identity typically represents a user but can also be used to identify any service, system, or process that needs to run queries with given privileges. Any Fauna document can be used as an identity.

Token workflow

When an identity is successfully authenticated using the login() function, a new token is created. Tokens can also be created directly when identity-based access is required, but authentication isn’t needed for handling outside of Fauna.

When a token is created, you must copy the token secret out of the query result when it is first created and store it securely. It is impossible to recover the token secret if it is discarded or lost because the token stores only the BCrypt hash of the secret, truncated to 72 bytes.

A token secret is then included as a bearer token in queries:

How Fauna performs identity-based authentication

  • The client sends a query to Fauna, and the request includes the secret for a Token as an HTTP bearer token header.

  • If the secret exists, Fauna looks up the associated Token document in the database associated with the secret. If not, the response is Unauthorized.

  • If the Token exists and hasn’t expired by ttl, Fauna looks up the associated identity document. If not, the response is Unauthorized.

  • If the identity document exists and hasn’t expired by ttl, Fauna applies ABAC roles to evaluate if the identity document is permitted to execute the query. If not, the response is Unauthorized.

  • If the identity document has permission, the query is executed, and the response is returned.

A token secret can be used in multiple queries until its token becomes invalid or is deleted. After a token is deleted, its associated secret is invalidated.

Token attributes

By itself, a token doesn’t grant any privileges to the identity. The privileges available to an identity are defined by attributed-based access control.

Multiple tokens can exist for a particular identity. This feature can be used to provide simultaneous, identity-based access to multiple devices.

Tokens are defined as documents in the Token system collection. Like databases, tokens exist in the system-global root database context. Tokens are linked to a database.

A token secret is a password equivalent. Guard secrets with the same care and attention that you use for passwords.

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!