External identity providers

This section describes the elements, functions, and operations required to use an identity provider (IdP) to authenticate users who can then query Fauna.

External authentication is any authentication that takes place outside of your Fauna database, allowing queries to be run.

Typically, external authentication is handled by an Identity Provider (IdP). An IdP provides the following services and capabilities:

  • creates, maintains, and manages identity information

  • creates, maintains, and manages permissions for each identity

  • provides authentication services where its own identities or those from other identity providers can authenticate.

When you use external authentication with Fauna, you have two options for identity information storage:

  • Identities are stored in your Fauna database. You provide 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.

  • Identities are stored in the IdP or in an IdP that you don’t use directly. For example, if you use Auth0 as your IdP, you might manage your users and their credentials in Auth0. Similarly, you might accept social logins from users who exist in other identity providers, such as FaceBook and GitHub.

    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), which is signed and possibly encrypted so that the claim of authentication can be known to be made by a trusted source. The JWT is then used as a password-equivalent and, after the appropriate configuration in your Fauna database is created, can be used in place of a Fauna token or key to authorize the execution of queries.

How external authentication works

After configuration, the process of using an IdP to authenticate to query a database looks like this:

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

  1. An unauthenticated user visits your web application and clicks "Log in".

  2. Your web application redirects to or opens a sub-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. If authentication is successful, the IdP makes a request to your application endpoint and provides a new JWT.

  6. Your web application indicates to the user that their login is successful. Your web application holds onto the JWT to use for subsequent queries to Fauna.

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

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

  9. Fauna validates the JWT. If needed, Fauna fetches the given public key from the jwks_uri to validate/decrypt the JWT. Fauna only performs the validation/decryption step one time during the JWT validation interval, if provided, or one time per hour. The result of the query execution is returned to your web application.

  10. Your web application updates its UI for the user based on the response that it receives.

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

External authentication is configured in two places:

  1. In the Fauna database that should permit users authenticated using an IdP to execute queries.

  2. With the IdP, to specify which web-accessible services should accept the JWTs that they create after successful authentication.

It is important that these two configurations are correct so that authenticated users can access documents in Fauna and to prevent non-authenticated users from gaining access.

Configuration involves creating an AccessProvider document that specifies the issuer, the jwks_uri, and the audience.

For more information, see AccessProvider.

IdP configuration varies by provider, but there are many similarities between the services. Typically, you configure an API with the details of connecting to Fauna, create roles or scopes that define the types of access that each user should have, and create user records that include their credentials and roles.

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

JSON Web Tokens (JWTs)

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

in a JWT, a claim is a key and value in 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",
}

in 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 is confirmed by the identity provider, Auth0.

  • aud: The audiences, URLs, that expect to validate and use the JWT claims. The example aud claim includes two URLs that are permitted/expected to process the JWT:

    1. The first URL is an identity provider URL that permits the JWT holder to ask for more user information that isn’t 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 database that should accept the JWT.

  • iat: The Issued-at timestamp, which is a Unix timestamp identifying JWT token creation time.

  • exp: The expiry timestamp. The audience URLs should accept the JWT claims starting with the iat, and ending with the exp. When the JWT expires, its claims should be ignored/rejected.

  • azp: The "authorized party", party to which the JWT is issued. Usually, this is used for the userid in 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 numerous claims that can be included in a JWT, but the listed claims 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 supports only the RS256, RS384, and RS512 encryption algorithms. Fauna doesn’t accept JWTs encrypted with any other algorithm.

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!