Keys

reference:

Key

Fauna keys provide anonymous-based access to a database.

Keys are typically used by database owners or administrators to manage database structure and contents with few restrictions and by background tasks that automate various database procedures at regular intervals. The secret for a Fauna key allows you to access the database associated with the key and invoke those operations permitted by the key role.

Keys are defined as documents in the system keys collection. Like databases, keys exist in the system-global root database context. Keys are linked to a database and allow access to its contents. If no database is given, the key grants access to the database from which the key originates. The level of access that a key provides depends on its role.

Key secret

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

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

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

How Fauna accepts the secret for a key

  • The client sends 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 hasn’t expired by ttl, Fauna evaluates the key role field in the database associated with the Key. The active role can be a built-in role or an ABAC role and determines if 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.

A key secret can be used in multiple queries until its key becomes invalid or is deleted.

Scoped keys

Here are some cases where you might want to impersonate access to a database:

  • You have a reporting tool that needs to gather information from all of your child databases. To access a child database, you typically must use a secret associated with each child database. With hundreds or thousands of child databases, managing those secrets is challenging.

  • Your application makes queries on behalf of users, and you want to test that functions and access controls are working correctly, but you don’t have access to any user password to call login().

  • Similarly, your application provides different capabilities for users with differing roles, and you wand to test the capabilities and access controls.

To facilitate these use cases, Fauna accepts a scoped key. A scoped key allows you to use a secret that you already possess to impersonate access to Fauna in several ways, but it isn’t possible to use a scoped key to gain more privileges.

A scoped key is formed from the secret of a key that you already possess, plus more information that provides three impersonation alternatives described in the following subsections. In each case, [:child_database] refers to an optional child database name. The name can use slashes to refer to grandchild and great-grandchild databases with unlimited nesting. For example:

  • secret:test:admin is a scoped key with the admin role for the current database child database called test.

  • secret:test/performance:server is a scoped key with the server role for a database called performance in the current database child database called test.

secret[:child_database]:role

Where:

  • secret is the key secret. An administrator key is required to access a child database.

  • child_database is the name of a child database (optional). When given, the secret for an administrator key must be used. When not given, the secret from an administrator or server key can be used.

  • role is the name of a system role to use, one of:

    • admin

    • server

    • server-readonly

This kind of scoped key is typically used to impersonate access to a child database.

For example: fnACysRJGIACAHiL_5f0UxHlPFIZgq876ptMNJ72:posts:admin

Provided that the secret belongs to an admin key, this scoped key provides full access to the child database called posts.

secret[:child_database]:@doc/collection/id

Where:

  • secret is the key secret. An administrator key is required to access a child database.

  • child_database is the name of a child database (optional). When given, the secret for an administrator key must be used. When not given, the secret from an administrator or server key can be used.

  • collection is the name of a collection in the current database or, if child_database is provided, in the child database.

  • id is the document ID for the document to authorize as. Document IDs are string-encoded 64-bit integers.

This kind of scoped key is used to impersonate a user.

For example: fnACysRJGIACAHiL_5f0UxHlPFIZgq876ptMNJ72:@doc/users/1234

This scoped key has the same privileges as the authenticated Ref(Collection("users"), 1234) document.

secret[:child_database]:@role/name

Where:

  • secret is the key secret. An administrator key is required to access a child database.

  • child_database is the name of a child database (optional). When given, the secret for an administrator key must be used. When not given, the secret from an administrator or server key can be used.

  • name is the name of an ABAC role to authorize as.

This kind of scoped key is used to impersonate any user with the privileges of the given role.

For example: fnACysRJGIACAHiL_5f0UxHlPFIZgq876ptMNJ72:@role/developers

This scoped key has the same privileges as any member document with the developer role.

Run-as

The Dashboard Shell Run As feature uses scoped keys.

Run As allows you to run a query using different roles, which simplifies evaluating your user-defined roles:

  • Specify a document: allows you to specify an identity document.

  • Specify a secret: allows you to specify a secret.

  • Admin: equivalent to using a key with the admin-role.

  • Server: equivalent to using a key with the server-role.

  • A user-defined role when at least one is defined. Roles can be selected based on their name.

Queries that you execute in the Dashboard Shell run using the selected role or identity document.

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!