Auth0

This tutorial describes how to configure Auth0 as an identity provider (IdP). Using this Auth0 configuration your application users can query your Fauna database. This example discusses the minimum configuration steps required to accept a JWT from Auth0 to execute a query.

Successful acceptance of a JWT for authentication requires that your Fauna database configuration and the Auth0 configuration agree on the following details:

  • The audience URL. Auth0 needs this field to create JWTs that Fauna can accept. When you create an AccessProvider document, Fauna creates a unique audience URL for your database.

  • The issuer URL. This tells Fauna which IdP is permitted to send a JWT that should authorize a query to be executed.

    Use an exact copy of your IdP issuer URL, including a trailing slash if it exists. URL differences could prevent acceptance of your IdP JWT tokens.

  • The jwks_uri URL. This is URL for the JSON Web Key Set endpoint. This endpoint serves the IdP-managed public key. Services such as Fauna can use the endpoint to verify or decrypt a JWT and confirm its validity. By convention, this URL is the issuer URL with .well-known/jwks.json appended.

Prerequisites

The following is a list of preparatory steps. Do a step only if you haven’t already done so:

  1. Sign up for a Fauna account.

  2. Create a database.

  3. Sign up for an Auth0 account.

  4. Create a Role to define the access privileges to apply to authenticated Auth0 users.

In the case of an IdP, users are stored in the IdP rather than Fauna. As a result, Fauna only applies the role privileges and ignores any membership it may also have.

Step 1 - Start Fauna configuration

This section configures an Access Provider in your Fauna database. An AccessProvider document allows you to define one or more roles to apply, to grant externally authenticated users access.

Do these steps in a new browser tab:

  1. Log in to the Fauna Preview Dashboard.

  2. Choose the database that should accept authenticated users from Auth0.

  3. Select the Access Providers tab and click Create Access Provider.

  4. In the Audience field, click the copy icon to copy the URL. Save the URL.

 

Don’t close this tab while configuring Auth0 in the next step. Fauna configuration continues in Step 3 - Complete Fauna configuration, creating the access provider.

Step 2 - Configure Auth0

This section shows how to configure an API in Auth0 using the Audience URL you saved in Step 1 - Start Fauna configuration.

Open a new browser tab for the following steps:

  1. Log in to Auth0.

  2. Choose APIs in the left navigation pane.

  3. Click + Create API.

  4. Enter a name for the API in the Name field to help you identify this API. The name should include a Fauna prefix, such as Fauna-my_app.

  5. Paste the saved Audience URL from Step 1 - Start Fauna configuration in the Identifier field.

  6. Choose the RS256 Signing Algorithm.

  7. Click Create.

  8. Click the Test tab to display the Auth0 API Test page:

  9. Find the --url value in the curl example and copy the URL, omitting the oauth/token part of the URL. Save this URL making sure to include the trailing slash (/).

    This is the API URL used to populate the issuer and jwks_uri fields in Step 3 - Complete Fauna configuration.

Step 3 - Complete Fauna configuration

This section completes Fauna access provider configuration begun in Step 1 - Start Fauna configuration. An AccessProvider document allows you to define one or more roles to apply, to grant access to externally authenticated users.

  1. Go to the Step 1 - Start Fauna configuration browser tab.

  2. Enter a name in the Name field to help you identify this access provider. The preferred name is Auth0.

  3. Enter the Auth0 API URL saved in Step 2 - Configure Auth0 in the Issuer field.

  4. Enter the same Auth0 API URL in the JWKS endpoint field and append .well-known/jwks.json to the URL. For example, the saved https://dev—​nozpv3z.us.auth0.com/ should be entered as https://dev—​nozpv3z.us.auth0.com/.well-known/jwks.json in the JWKS endpoint field.

  5. Click Create.

    The Auth0 access provider is added to the database Access Providers list.

  6. If you don’t have a role defined, use the shell to create a role to assign to the access provider similar to this create role example.

  7. Use the shell to add the role to the access provider instance. In this example, the management team role is added to the Auth0 access provider:

    AccessProvider.byName("Auth0")!.update({
  roles: "mgmtTeam"
})
    {
  name: "Auth0",
  coll: AccessProvider,
  ts: Time("2023-09-18T21:13:06.645Z"),
  audience: "https://db.fauna.com/db/ywp9xrp6gyyre",
  roles: "mgmtTeam",
  jwks_uri: "https://dev—​nozpv3z.us.auth0.com/.well-known/jwks.json ",
  issuer: "https://db.fauna.com/db/ywp9xrp6gyyre"
}

Verify the configuration

Your Fauna database and your Auth0 API are configured to exchange authentication information using a JWT. To verify that the configuration works, follow these steps:

  1. In the Auth0 Test browser tab, make sure that the cURL tab is selected.

  2. Copy the cURL code example, which begins with curl --request POST \.

  3. Open a terminal.

  4. Paste the code sample in the terminal, and enter Return.

  5. The output should be similar to:

    {"access_token":"eyJhbGcIqiJSUzI1N5IsInR5cCi6IkpXVCIsImTpZCI6ilNCZTczWmFyOWpKU3h
ueG44QlNTSqJ9eyJpc3MiOiJQdHRwczovL2R6di0tbm96cHYzei51cy5hdXRoMC5jb20vIiwic3ViIjo
ibDZ2SlM4UXZIQzJMbWlHUmFPVGlFMTZnaXZ1dWZSMjJAY2xpZW50cyIsImF1ZCI6Imh0dHBzOi8vZGI
uZmF1bmEuY29tL2RiL3l4eGY1eDl3MXlieW4iLCJpYXQiOjE2MDU1MDI2NDgsImV4cCI6MTYwNTU4OTA
0OCwiYXpwIjoibDZ2SlM4UXZIQzJMbWlHUmFPVGlFMTZnaXZ1dWZSMjIiLCJndHkiOiJjbGllbnQtY3J
lZG.udGlhbHMif6 pdnzxME8gaQkyxsWhurgVzQcakcnMRUJEGcb83f_lgd0tWaE-VcFcfb-SXLCFX3IcJkls9woQVcFM91
UCHRN_qSKjEzB1vOrFqQ73FSq33dLviGM_8E195R_zJVmCsb__ADhQCaWTYM-vO8ZSA7lC2WzVejLAg
CJhOXwP7WGeG_FDfqVDM0InaJdVOoUwXF4SzZ00DVjJxSoKnsiRgwpPyaV3rGAQGVlijyYe1mea7D3g
jHO2a-yUV-yT75xglTyjwC5WKHySXgu-iXq7x6N5JIRAcBh2-ka6sS5o61JHR35sFfXYpUiSiPj45XL
nGhB7wbVwvq4mA3ur1bePg","expires_in":86400,"token_type":"Bearer"}

The value of the access_token field can be used in place of the secret from a database token or key. This token identifies your user account in Auth0.

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!