FQL v4 will be decommissioned on June 30, 2025. Ensure that you complete your migration from FQL v4 to FQL v10 by that date.

For more details, review the migration guide. Contact support@fauna.com with any questions.

Credentials

A credential document is used to store a cryptographic hash of a password that can be subsequently used to authenticate an identity stored in Fauna — part of Fauna’s identity-based access control.

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

A credential document can be created directly, like any other document in Fauna, or indirectly via a document’s credentials field. When a document is created or updated with a credentials field, the field value is not stored with the document — instead, it is used to create a credentials document. The password within the credentials field value is never stored.

Once a credential document has been created, the reference to the identity stored in Fauna can be passed to the Login function, along with the matching password, to create a token. The token’s secret can then be used to execute queries on behalf of the identity, with the privileges defined by Attribute-based access control (ABAC) roles.

Identity-based authentication and access control with Fauna tokens

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 within the database associated with the secret. If not, the response is Unauthorized.

  • If the Token exists and has not expired (due to ttl), Fauna looks up the associated identity document. If not, the response is Unauthorized.

  • If the identity document exists and has not expired (due to ttl), Fauna applies ABAC roles to determine whether 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.

Similarly, once a credential document has been created, the Identify function can be used to verify the hashed password in the credential document. However, calling Identify does not create a token; it is used simply to verify that the stored and provided credentials match.

Credentials are defined as documents within the system credentials collection. Like databases, credentials exist within the system-global root database context. Credentials are tied to a specific database.

Definition

{
  ref: Ref(Credentials(), "266165112685986314"),
  ts: 1590093681910000,
  instance: Ref(Collection("users"), "123456"),
  hashed_password: '$2a$05$pSOerPcfQdpeO0fPqtXXYeqRc0KSY/0QvaAoNjf5PN69zOdrzKx76'
}
Field name Value type Description

ref

Reference

The reference for this credential.

ts

Long

The timestamp, with microsecond resolution, associated with the creation of the credential.

instance

Reference

The reference to the identity that provided this credential.

hashed_password

String

The credential’s hashed password.

data

Object

Optional - User-defined metadata for the credential.

Operations on credentials

  • Create a credential document by adding the credentials field to a document, when it is created or updated:

    Create(
  Collection("users"),
  {
    data: { <document data goes here> },
    credentials: {
      password: "abc123"
    }
  }
)

  • You can also create a credential document directly:

    Create(
  Credentials(),
  {
    instance: Ref(Collection("users"), "123456"),
    password: "abc123"
  }
)

  • Update the password for a document with the following query:

    Update(
  Ref(Collection("users"), "2"),
  { credentials: { password: "myNewPassword" } }
)

    Note that this query results in the creation or update of the associated credentials document without the current password.

    Revising a password does not immediately invalidate any tokens in use. You would need to call the Logout function to invalidate tokens, and force users to login again with the new password.

  • Update the password in a credential document with the following query:

    Update(Ref(Credentials(), "123456"), {
  current_password: "abc123",
  password: "correct horse battery staple"
})

    Note that in this query, the current password is required in order to update the password.

    Revising a password does not immediately invalidate any tokens in use. You would need to call the Logout function to invalidate tokens, and force users to login again with the new password.

  • Credentials can be deleted by using the Delete function. Deleting a credential does not affect any tokens currently in use.

  • Modify a credential’s optional user-defined metadata (the data field) by using the Update function.

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!