JSON Web Tokens (JWTs)

Beginning with API version 4.0, Fauna can accept valid JWTs from a configured identity provider (IdP) — such as Auth0 — that provide self-contained JWTs.

A JSON Web Token (JWT) is a compact representation of various claims, which can include identity, authentication status, permissions, and more.

Within a JWT, a claim is, essentially, a specific key and value within a JSON structure. For example:

{
  "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",
}

Within that JWT, there are seven claims:

  • iss: The issuer of the JWT, specifying the identity provider.

  • sub: The "subscriber" or authenticated user identity. The example sub claim is for an authenticated Google user whose identity was confirmed by the identity provider, Auth0.

  • aud: The audience(s) (URLs) that expect to validate and use the JWT’s claims. The example aud claim includes two URLs that are permitted/expected to process the JWT:

    1. The first URL is an identity provider-specific URL that permits the JWT holder to ask for additional user information that is not automatically included in the JWT.

    2. The second URL is an example of a Fauna database identifier URL. The latter string of characters is a globally-unique identifier for the specific database that should accept the JWT.

  • iat: The "Issued-at" timestamp, which is a Unix timestamp identifying when the JWT token was created.

  • exp: The expiry timestamp. The audience URLs should accept the JWT’s claims starting with the iat, and ending with the exp. Once the JWT has expired, its claims should be ignored/rejected.

  • azp: The "authorized party", party to which the JWT was issued. Usually, this is used to contain the userid within the identity provider.

  • scope: The scope is a space-delimited list of scope names. Each scope should be considered to be permitted use of the JWT.

There are a wide variety of claims that can be included in a JWT, but the claims identified above tend to be the most commonly used claims. To work with Fauna, a JWT must, at minimum, include the iss, sub, and aud claims.

Trust in a JWT comes from the cryptographic signing of the JWT by the identity provider, or encryption of the JWT when disclosure of the claims is undesirable. Typically, the identity provider makes a public key available so that the receiver of a JWT can validate/decrypt the JWT for use. The standard location URL template is https://<identity provider>/.well-known/jwks.json.

Fauna only supports the RS256, RS384, and RS512 encryption algorithms. Fauna does not accept JWTs encrypted with any other algorithm. When in doubt, ask your IdP for assistance.

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!