Use an external identity provider (IdP)

External authentication is authentication that takes place outside of your Fauna database. After authentication is made, Fauna queries can be made. This section describes the elements, functions, and operations required to use an identity provider (IdP) to authenticate users so they can query Fauna.

Typically, external authentication is handled by an IdP. An IdP offers the following services and capabilities:

  • creates, maintains, and manages identity information

  • creates, maintains, and manages permissions for each identity

  • offers authentication services where its identities, or those from other identity providers, can be authenticated

An identity provider can be enterprise-based for example, Okta or social-based, such as FaceBook. There are many providers and each one has differences to consider.

About IdP selection

When you use external authentication with Fauna, you have two identity information storage options. Store identities in your Fauna database or store identities in the IdP. This makes a difference when selecting a provider.

If you store identities in Fauna you must deliver code to the IdP that allows the IdP to authenticate users in your database. In this scenario, there is no significant benefit to using an IdP with Fauna

Instead, you should select a provider that stores and identities for you such as Auth0 or Facebook. In this scenario, each of the identities is already confirmed, usually by email verification but occasionally by other mechanisms such as the exchange of public keys.

On successful authentication, the IdP generates a JSON Web Token (JWT). It is this JWT that is provided to Fauna. The JWT is signed and possibly encrypted so that the claim of authentication is known to be made by a trusted source. Your application uses the JWT as a password-equivalent in Fauna.

Using an IdP to authenticate requires you to understand your use case, the IdP, and the configuration of your Fauna database.

Configuration process

External authentication is configured in the Fauna and the IdP. On Fauna, you configure the database that your users query. On the IdP you configure which web-accessible services should accept the JWTs created after successful authentication.

After Fauna and IdP configuration is complete, you can configure your application to integrate the IdP login workflow and then query Fauna with the JWTs that your application receives from the IdP.

A correct configuration ensures that authenticated users can access documents in Fauna and prevents unauthenticated users from gaining access.

External authentication flow

After configuring an IdP and Fauna, the process of using an IdP to authenticate a user through a web application looks like this:

The external authentication sequence

  1. An unauthenticated user visits your web application and logs in.

  2. The application redirects to or opens a frame for the IdP login form.

  3. The IdP presents the login form.

  4. The user enters their credentials and submits them to the IdP.

  5. On successfully authenticating, the IdP requests from your application login successful endpoint and returns a freshly generated JWT.

  6. The web application notifies the user that login is successful. The application stores the JWT to use for subsequent queries to Fauna.

  7. The user performs some action that requires fetching data from Fauna.

  8. Your web application composes an FQL query and uses the user JWT, in place of a Fauna token/key, as the HTTP Bearer token.

  9. Fauna validates the JWT.

    If needed, Fauna fetches the public key from the jwks_uri to validate/decrypt the JWT. Fauna only performs this step one time during the JWT optional validity period or hourly. The result of the query execution is returned to your web application.

    Fauna supports only the RS256, RS384, and RS512 encryption algorithms and doesn’t accept JWTs encrypted with another algorithm. If you have questions, ask your IdP for help.

  10. The web application receives the response and updates its UI for the user.

This flow is typical. While there are variations of this flow depending on where the identities are stored and where permissions are configured, the variations aren’t described here.

Configuration Elements

The Fauna configuration for external authentication involves creating an AccessProvider document. This document specifies the IdP issuer, the URL where the IdP jwks_uri public key can be found, and the audience, which identifies the database that should accept the JWT.

IdP configuration varies by provider, but there are many similarities between the services. In general:

  • Configure an API with the Fauna connection details.

  • Create roles or scopes that define user access types.

  • Create user records that include user credentials and roles.

After the Fauna and IdP configuration is complete, you can configure your application to integrate the IdP login workflow, and query Fauna using the JSON Web Tokens (JWTs) that your application receives from the IdP.

This page provides an overview of the configuration elements.

Valid JWT configuration

Fauna accepts valid JSON Web Tokens (JWTs) from an identity provider (IdP) that has self-contained JWTs, such as Auth0. An AccessProvider document has relevant information needed to validate token authenticity and it must be configured to use JWT with Fauna:

Field Name Field Type Definition and Requirements

name

String

Unique name for the external identity provider (IdP). rhyme

Can’t be events, sets, self, documents, or underscore (_) character and can’t include the percent (%) character.

issuer

String

Unique HTTPS URL for the IdP that is used to grant access to Fauna. The issuer is typically an account or application URL provided by the IdP.

jwks_uri

String

Valid HTTPS URI. This should be the JSON Web Key (JWK) that signs the JSON Web Token (JWT) from the IdP.

roles

Array of role names or role-predicate objects.

Defines the roles to evaluate for access by a provided JWT token.

A role that grants access means that the query involving a JWT token is processed, even if another role might deny access. If roles is not configured, no privileges are defined, and queries with JWT tokens from the configured issuer can’t processed.

data

Object

User-defined metadata for the provider. Use it to store provider-relevant information.

audience

String

(read-only) Unique URL for your database that should be used in the audience configuration for an identity provider. Fauna creates this field when you create a database.

The following example is a valid AccessProvider document:

{
  name: "anAccessProvider",
  coll: AccessProvider,
  ts: Time("2023-08-14T14:42:23.070Z"),
  data: {
    custom: "some data"
  },
  audience: "https://db.fauna.com/db/ywo7ha5rhyynn",
  roles: [
    "humanResources",
    {
      role: "humanResources",
      predicate: "_ => true"
    }
  ],
  jwks_uri: "https://fauna.auth0.com/.well-known/jwks.json",
  issuer: "https://fauna.auth0.com"
}

If all the validation properties and required claims are present and valid, the AccessProvider gets the jwks_uri for the public keys to validate the token signature. If the token signature is valid, the AccessProvider checks if the lists of valid roles and valid collections include the scope claim in the token. If so, the JWT is considered valid, and the user is allowed to execute the query.

To enable JWT in your application, set the "Authorization" header to "Bearer" type: "Authorization: Bearer xxx.yyy.zzz".

JWT claims

A JWT is a compact representation of various claims, which can include identity, authentication status, permissions, and more. A JWT claim is a JSON key:value pair provided by the IdP.

Claim

Required

Description

aud

yes

Audience or URLs that expect to validate and use the JWT claims. For Fauna, this represents the scope/database and has the pattern https://db.fauna.com/db/<global_id>. The global_id is a unique string that represents a database globally.

azp

The authorized party, the party that issued the JWT. Typically, this is used to include the userid in the identity provider.

exp

no

JWT token expiry timestamp. The audience URLs should accept the JWT claims starting with the iat claim and ending with the exp claim. After the JWT expires, its claims should be ignored or rejected.

iat

no

The Issued-at timestamp is a Unix timestamp that identifies the JWT token creation time.

iss

yes

Issuer of the JWT, such as https://dev-xpto.auth0.com.

nbf

no

Timestamp that indicates when the token becomes valid, and not before this time.

scope

no

A space-delimited list of scope names but only one document or role can exist at the same time for the token to be considered valid. Each scope should be considered as permitted to use the JWT. For Fauna, scope represents a document or role to evaluate JWT permissions for documents. It should have the pattern @doc/<collectionName>/<id>. For roles, it should have the pattern @role/<roleName>.

sub

yes

The subscriber or authenticated user identity whose identity is confirmed by the identity provider, such as Auth0.

Various claims can be included in a JWT, but the preceding claims tend to be the most commonly used. For Fauna, a JWT must minimally include the iss, sub, and aud claims.

The following example is a valid JWT token:

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

In the aud claim example, the first URL is an identity provider URL that permits the JWT holder to ask for more user information not included in the JWT. The second URL is an example of a Fauna database identifier URL. The latter string of characters is a globally unique identifier for the database that should accept the JWT.

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!