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

Fauna accounts created after August 21, 2024 must use FQL v10. These accounts will not be able to run FQL v4 queries or access the v4 Dashboard.

For more details, see the v4 EOL announcement and migration guide. Contact support@fauna.com with any questions.

Security

This section describes Fauna authentication and access control security features.

Fauna’s security design makes it easy to query your databases from any network-connected context, including a web browser. Connections to the database are secured using HTTPS. Authentication and access control are implemented using HTTP bearer tokens in the request header for each query.

Fauna provides two security models for access:

  • An identified user identity-based access: With this model, queries have an associated identity, stored within the database or within an external identity provider, that identifies the actor executing each query. Identity-based access is typically used by applications to enforce fine-grained access control, or to modify query behavior based on the identity of the actor that queries the database.

  • An anonymous user anonymous-based access: With this model, queries do not have an associated identity. Access is role-based, where the role grants specific privileges. Anonymous-based access is typically used by application developers and background tasks that need either global access, or narrowly-focussed access, where identity is not important.

To use these security models, Fauna provides these resources:

  • Secrets: Each secret is an opaque bearer token, associated with a token document or key document within Fauna, that provides access to a specific database. A secret is displayed only once at creation time; it should be stored securely, and needs to be revoked and recreated if lost.

  • Attribute-based access control (ABAC): ABAC roles define specific privileges, for query execution, to specific member identities within the database. Such roles provide fine-grained access control, and can modify the query behavior based on document attributes or time of day.

  • Tokens: A token grants authorized access to an associated identity. The actual permissions available are controlled with attribute-based access control (ABAC). The metadata for a token, including its hashed secret, is stored as a document in the internal tokens collection. Tokens are typically created using the Login function, which involves a credential that the identity knows, but can also be created directly for password-less identity-based authentication.

  • JSON Web Tokens (JWTs): A JWT grants authorized access to an associated identity that is managed by an external identity provider. The actual permission available are controlled with attribute-based access control (ABAC). A JWT is created when a user successfully authenticates with an external identity provider. Once a Fauna database has been configured to accept JWTs for specific identity providers, a JWT can then be used to query Fauna.

  • Keys: A key grants anonymous authorized access. The actual permissions granted are controlled with roles, which can be one a four built-in roles, or a user-defined attribute-based access control (ABAC) role. The metadata for a Key, including its hashed secret, is stored as a document in the system keys collection.

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.

Anonymous-based authentication and access control with Fauna keys

How Fauna accepts the secret for a key

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

  • If the secret exists, Fauna looks up the associated Key document. If not, the response is Unauthorized.

  • If the Key exists and has not expired (due to ttl), Fauna evaluates the Key’s role field within the database associated with the Key. The active role could be a built-in role or an ABAC role, and determines whether the query should be permitted to execute. If not, the response is Unauthorized.

  • If the Key provides permission, the query is executed and the response is returned.

In this section:

Best practices

This sections describes some of the considerations and best practices for maintaining security when querying Fauna.

Secrets

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

  • Secrets for admin keys provide unrestricted access to a database or any of its child databases. Protect these secrets as you would for any computer’s root password:

    • Do not embed the admin key secrets into applications.

    • Share admin key secrets only with individuals that need unrestricted database access.

    • Consider creating an administrators role and applying membership to specific user documents instead of using admin key secrets.

  • The build-in client role for keys was intended to make it easy to embed a secret within an application to grant, essentially, unauthenticated access to select documents within a database. We no longer recommend its use, since it is part of the legacy, resource-based permission system, and because ABAC provides far greater flexibility and easier management of document access.

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!