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:
-
An unauthenticated user visits your web application and logs in.
-
The application redirects to or opens a frame for the IdP login form.
-
The IdP presents the login form.
-
The user enters their credentials and submits them to the IdP.
-
On successfully authenticating, the IdP requests from your application
login successful
endpoint and returns a freshly generated JWT. -
The web application notifies the user that login is successful. The application stores the JWT to use for subsequent queries to Fauna.
-
The user performs some action that requires fetching data from Fauna.
-
Your web application composes an FQL query and uses the user JWT, in place of a Fauna token/key, as the
HTTP Bearer
token. -
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
, andRS512
encryption algorithms and doesn’t accept JWTs encrypted with another algorithm. If you have questions, ask your IdP for help. -
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 |
---|---|---|
|
Unique name for the external identity provider (IdP). rhyme Can’t be |
|
|
Unique HTTPS URL for the IdP that is used to grant access to
Fauna. The |
|
|
Valid HTTPS URI. This should be the JSON Web Key (JWK) that signs the JSON Web Token (JWT) from the IdP. |
|
|
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 |
|
User-defined metadata for the provider. Use it to store provider-relevant information. |
|
|
(read-only) Unique URL for your database that should be used in the
|
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 |
|
yes |
Audience or URLs that expect to validate and use the
JWT claims. For Fauna, this represents the scope/database and has
the pattern |
|
The authorized party, the party that issued the JWT. Typically, this is used to include the userid in the identity provider. |
|
|
no |
JWT token expiry timestamp. The audience URLs should accept the JWT
claims starting with the |
|
no |
The Issued-at timestamp is a Unix timestamp that identifies the JWT token creation time. |
|
yes |
Issuer of the JWT, such as |
|
no |
Timestamp that indicates when the token becomes valid, and not before this time. |
|
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, |
|
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!