Check out v4 of the Fauna CLI

v4 of the Fauna CLI is now in beta.

The new version introduces enhancements to the developer experience, including an improved authentication workflow. To get started, check out the CLI v4 quick start.

Access providers

An access provider registers an external identity provider (IdP), such as Auth0, in your Fauna database.

Once set up, the IdP can issue JSON Web Token (JWTs) that act as Fauna authentication secrets. This lets your application’s end users use the IdP for authentication.

Supported identity providers

You can use any application that issues JWTs and meets the requirements as an access provider. Fauna has documented setup steps for the following IdPs:

Auth0

Clerk

Other supported integrations

Although they don’t meet the requirements to act as an access provider, you can use the following IdPs to issue authentication tokens for end users:

Amazon Cognito

Microsoft Entra

Requirements

To act as an access provider, an IdP must:

Issue JWTs with an aud (audience) and iss (issuer) claim. The aud claim must be configurable. Fauna uses the aud and iss claims to verify the source and intended audience of JWTs.
Sign its JWTs using the RS256, RS384, or RS512 algorithms. The JWT header must specify the algorithm in the alg claim.
Provide a URI that points to public JSON web key sets (JWKS) that Fauna can use to verify the signature of the IdP’s JWTs.

Create and manage access providers

You create and manage access providers as FSL access provider schema:

access provider someIssuer {
  // `issuer` string for the IdP.
  // Must match the `iss` claim in JWTs produced by the IdP.
  issuer "https://example.com/"
  jwks_uri "https://example.com/.well-known/jwks.json"

  role customer
}

You can create and manage schema using any of the following:

The Fauna CLI
The Fauna Dashboard
The Fauna Core HTTP API’s Schema endpoints
FQL schema methods

Reference: FSL access provider schema

Access provider roles

When you define an access provider schema, you can specify one or more role properties with user-defined roles. Fauna assigns these roles to the provider’s JWTs. You can’t assign a built-in role to an access provider’s JWTs.

Each role property can include a predicate to conditionally assign roles to JWTs.

access provider someIssuer {
  ...
  // Assign the `customer` role to the provider's JWTs.
  role customer

  // If the predicate is `true`,
  // assign the `manager` role to the provider's JWTs.
  role manager {
    // Check that the JWT payload's `scope` includes `manager`.
    predicate (jwt => jwt!.scope.includes("manager"))
  }
}

See Dynamically assign roles to JWTs

Set up an access provider

Setting up an access provider requires configuration in Fauna and the external IdP.

To set up the access provider in Fauna, you must include the following information from the IdP in the access provider schema:

An issuer string that matches the iss claim in JWTs issued by the IdP.
A jwks_uri that points to a set of JWKS for the IdP’s JWTs. Fauna uses the keys to verify the signature of the JWTs.

To issue valid Fauna JWTs, you must provide the IdP with an audience URL from Fauna. The audience URL is globally unique and scoped to a Fauna database. All access providers in a database use the same audience URL.

The following procedure outlines the broad steps for setting up an access provider. The exact steps will vary based on the IdP:

Retrieve the issuer string and jwks_uri from the IdP.
Create an FSL access provider schema that includes the:
- name for the access provider.
- IdP’s issuer. Must be unique to the access provider.
- IdP’s jwks_uri. Must be unique to the access provider.
- Roles for the provider’s JWTs in one or more role properties.
```
access provider someIssuer {
  issuer "https://example.com/"
  jwks_uri "https://example.com/.well-known/jwks.json"

  role customer
}
```
Submit the schema to Fauna using any of the following:
- The Fauna CLI
- The Fauna Dashboard
- The Fauna Core HTTP API’s Schema endpoints

Get the database’s audience URL from the Dashboard or using an FQL query. The audience URL consists of https://db.fauna.com/db/ followed by the database’s global id.

To get the audience URL using FQL:

AccessProvider.byName("someIssuer")

{
  name: "someIssuer",
  coll: AccessProvider,
  ts: Time("2099-07-08T17:41:55.280Z"),
  jwks_uri: "https://example.com/.well-known/jwks.json",
  roles: [
    "customer",
    {
      role: "manager",
      predicate: "(jwt) => jwt!.scope.includes(\"manager\")"
    }
  ],
  // The database's `audience` URL for access providers
  audience: "https://db.fauna.com/db/abc123",
  issuer: "https://example.com/"
}

Configure the IdP to include the audience URL in the aud claim of JWTs produced by the IdP.
Complete any other required configuration in the IdP.

How authentication works with an access provider.

Once set up, the IdP issues a JWT when a user logs in to the IdP (or at another trigger). Your application can use the JWT as an authentication secret.

The following outlines how this authentication flow typically works:

An overview of the sequence of events required to use external authentication

An unauthenticated user visits your application and clicks "Log in".
Your application redirects to or otherwise opens a login form for the IdP.
The IdP presents the login form.
The user enters their credentials and submits them to the IdP.
If authentication is successful, the IdP makes a request to an endpoint for your application and provides a new JWT.
Your application indicates to the user that their login is successful. Your web application holds onto the JWT to use for subsequent queries to Fauna.
The user performs an action that requires fetching data from Fauna.
Your web application runs a query and uses the held JWT to authenticate the request.
Fauna validates the JWT.

If needed, Fauna fetches the given public key from the jwks_uri to validate the JWT’s signature.

Fauna only performs the validation step one time during the JWT validation interval, if provided, or one time per hour.

If successful, Fauna returns the query’s results.
Your web application updates its UI for the user based on the response that it receives.

Delete an access provider

You can delete an access provider using any of the following:

The Fauna CLI
The Fauna Dashboard
The Fauna Core HTTP API’s Schema endpoints
The FQL accessProvider.delete() method.

Deleting an access provider immediately invalidates any Fauna JWTs issued by the related IdP.

`AccessProvider` collection

Fauna stores access providers as documents in the AccessProvider system collection. You can use AccessProvider methods to access AccessProvider collection documents in FQL.

See AccessProvider FQL docs

JSON Web Tokens (JWTs)

Once set up, you can use JWTs issued by an IdP as an authentication secret in Fauna.

JWTs are commonly used by web applications for authorization and to transmit information. For more information about JWTs and their structure, see https://jwt.io/introduction.

JWT payload

A JWT’s payload contains claims. A claim is a key and value in a JSON structure. For example:

{
  "iss": "https://fauna-auth0.auth0.com/",
  "sub": "google-oauth2|997696438605329289272",
  "aud": [
    "https://fauna-auth0.auth0.com/userinfo",
    "https://db.fauna.com/db/abc123",
  ],
  "iat": 1602681059,
  "nbf": 1602681059,
  "exp": 1602767459,
  "azp": "12345abcdef",
  "scope": "openid profile email",
}

The following table describes covers JWT claims and claims required by Fauna.

Claim Required by Fauna Description

Claim	Required by Fauna	Description
`iss`	Yes	Issuer of the JWT. Must match the `issuer` string in the access provider schema.
`sub`	Yes	Subscriber or authenticated user identity. In the example, the `sub` claim is for an authenticated Google user whose identity is confirmed by the IdP, Auth0.
`aud`	Yes	Audiences expected to validate and use the JWT In the example, the `aud` claim includes two URLs: An IdP URL. The URL permits the JWT holder to request user information that isn’t included in the JWT. An `audience` URL for a Fauna database.
`iat`		The "issued at" timestamp for the JWT. Represented as seconds since the Unix epoch.
`nbf`		The "not before" timestamp for the JWT. Represented as seconds since the Unix epoch. You can’t use a JWT to authenticate Fauna requests before the `nbf` timestamp.
`exp`		Expiration timestamp for the JWT. Represented as seconds since the Unix epoch. You can’t use a JWT to authenticate Fauna requests after the `exp` timestamp.
`azp`		The "authorized party" party to which the JWT is issued. This is typically an ID for the user in the IdP.
`scope`		Space-delimited list of scopes. Fauna doesn’t use or process JWT scopes. You can include arbitrary scopes for use in attribute-based access control (ABAC). For an example, see Dynamically assign roles to JWTs.

iss

Yes

Issuer of the JWT. Must match the issuer string in the access provider schema.

sub

Yes

Subscriber or authenticated user identity.

In the example, the sub claim is for an authenticated Google user whose identity is confirmed by the IdP, Auth0.

aud

Yes

Audiences expected to validate and use the JWT

In the example, the aud claim includes two URLs:

An IdP URL. The URL permits the JWT holder to request user information that isn’t included in the JWT.
An audience URL for a Fauna database.

iat

The "issued at" timestamp for the JWT. Represented as seconds since the Unix epoch.

nbf

The "not before" timestamp for the JWT. Represented as seconds since the Unix epoch.

You can’t use a JWT to authenticate Fauna requests before the nbf timestamp.

exp

Expiration timestamp for the JWT. Represented as seconds since the Unix epoch.

You can’t use a JWT to authenticate Fauna requests after the exp timestamp.

azp

The "authorized party" party to which the JWT is issued. This is typically an ID for the user in the IdP.

scope

Space-delimited list of scopes. Fauna doesn’t use or process JWT scopes.

You can include arbitrary scopes for use in attribute-based access control (ABAC). For an example, see Dynamically assign roles to JWTs.

Access a JWT’s payload in a query

If you use a JWT to authenticate an FQL query, you can access the JWT’s payload using Query.token():

Query.token()

{
  iss: "https://faunadb-auth0.us.auth0.com/",
  sub: "6dSyciWo7pKrarUCgFxzxi545oWfgyEk@clients",
  aud: "https://db.fauna.com/db/abc123",
  iat: 1720536267,
  exp: 1720622667,
  scope: "manager",
  azp: "12345abcdef"
}

Reference: Query.token()

Update a JWT’s roles

Fauna assigns roles to a JWT based on the role properties in the related access provider’s schema. Fauna checks a JWT’s roles and related privileges at query time for every query.

To update a token’s roles, edit the role properties in the schema. Changes to roles and privileges take effect immediately and affect pre-existing JWTs.

Check a JWT’s roles

You can use user-defined functions (UDFs) to check a JWT’s roles. See Check a secret’s user-defined roles.

JWT expiration

JWTs with an exp (expiration) claim can’t be used after the exp timestamp. JWTs with an nbf (not before) claim can’t be used before the nbf timestamp.

Fauna doesn’t require the exp or nbf claims. If desired, you must configure your IdP to include the claims in its JWTs.

JWT scope

JWTs are scoped to a specific Fauna database based on the Fauna audience URL in the aud claim. You can’t use a JWT to access parents or peers of this database.

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!