A credential document is part of the Fauna identity-based access control and is used to store a cryptographic hash of a password that can be used to authenticate a stored identity.

Credentials are defined as documents in the system Credential collection. Like databases, credentials exist in the system-global root database context.

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 document can be used as an identity.

Credentials are linked to a database.

Credential workflow

A credential document can be created directly like any other document or indirectly using a document credentials field. When a document is created or updated with a credentials field, the field value isn’t stored with the document. Instead, it is used to create a credentials document. The password in the credentials field value is never stored.

After a credential document is created, the reference to the stored identity can be passed to the login() function with the matching password to create a token. The token secret can then be used to execute queries on behalf of the identity, with the privileges defined by Attribute-based access control (ABAC) roles.

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.

Is this article helpful? 

Tell Fauna how the article can be improved:
Visit Fauna's forums or email

Thank you for your feedback!