Integrate & extend /Integrations /

Auth0 Integration

Auth0 is an identity platform that adds authentication and authorization to your applications with features to manage users and customize access control. The Auth0 extension provides a streamlined and secure solution so you can connect your Netlify team to Auth0 from the Netlify UI. With the Auth0 extension, you can add authorization to your functions to manage access across multiple services.

# Before you begin

To get started with Auth0 on Netlify, ensure that you have the following:

  • An Auth0 account and an Auth0 tenant. If you don’t have an account already, you can sign up for free. After you create your account, Auth0 will prompt you to create a tenant.
  • A deployed site on Netlify.

# Get started with Auth0

To use Auth0 with your site, you need to complete the following:

  1. Install the Auth0 extension for your team in the Netlify UI and connect to Auth0.
  2. Configure the extension for your site.

# Install the extension and connect to Auth0

Once you have your Netlify site, Auth0 account, and Auth0 tenant ready, you can install the extension in the Netlify UI:

  1. As a Team Owner, navigate to the

    page for your team in the Netlify UI.

  2. Search for Auth0 and select it in the search results.

  3. On the details page, select Install.

Auth0 extension install page

  1. From your team’s Sites list, select the site you plan to use with this extension, navigate to the

    and scroll to find the Auth0 extension settings.

  2. Next, start the process to link your Auth0 tenant to your Netlify account. Select Link an Auth0 tenant and follow the prompts to authorize Netlify to access your tenant. If you do not have an Auth0 account, select Sign up with Auth0 and follow the prompts to create an Auth0 account.

After connecting your tenant, your next step is to configure the extension for your site.

# User-level authentication

The Auth0 extension authenticates at the user-level in the Netlify UI. When you collaborate on a team, each user can only connect to the tenants that their Auth0 user has access to. However, if someone else has configured the extension on a site, team members can review the list of tenants configured for each deploy context in the extension’s site settings, and can review the related environment variables under

.

# Configure the extension for your site

Now that you have installed the Auth0 extension on your team and added a tenant, you can configure the Auth0 extension settings for the site:

  1. Under Site tenants, select Add a tenant and select a tenant to use for your site's deploy contexts.

  2. Next, select the Auth0 application and, optionally, an API. If you don’t already have Auth0 applications and APIs, we recommend that you create them from the Netlify UI. Creating Auth0 applications and APIs from the Netlify UI optimizes their settings for use with Netlify.

If you already have Auth0 applications and APIs, you can select and assign them to each tenant.

  1. Select one or more deploy contexts for your site tenant.

Assigning tenants to individual branch deploys is not yet supported

This extension does not support assigning a tenant to individual branch deploys. The tenant selected for the Branch Deploys context applies to all branch deploys.

  1. This extension automatically creates a set of environment variables based on your configuration. If your framework or build system requires the use of a specific prefix in environment variable names, input your desired prefix or select one from the Preset dropdown. If your framework or build system doesn’t require a prefix, leave this blank.

    For example: When configuring an API, selecting the Vite preset will generate the following variables:

    Auth0 example environment variables

    You can review these variables at any time by navigating to

    .

To configure multiple tenants, repeat these steps for each tenant.

# Default settings

When you create Auth0 applications and APIs through the Netlify UI, the extension sets a number of default settings and optimizes them for use with Netlify.

When you create a new Auth0 application using the Create new application button, the extension will create a Single-Page Application (SPA) in Auth0. SPAs are ideal for frontend applications that use an API. To locate your application, navigate to your Auth0 dashboard, select Applications > Applications, and find the application. The application name corresponds to your Netlify site name and the type is Single Page Application.

Auth0 UI Applications list

When you create a new Auth0 API using the Create new API button, the extension will create a Custom API in Auth0. To verify that your API was created successfully, navigate to your Auth0 dashboard, select Applications > APIs, and find the API. The name of the API corresponds to your Netlify site name.

Auth0 UI APIs list

A few of the Auth0 settings the extension sets by default include:

  • Application Properties. The Token Endpoint Authentication Method is set to None so that you can exchange tokens on the frontend. This is the only option for public applications.
  • Application URIs. We pre-configure the Allowed Callback URLs, Allowed Web Origins, and Allowed Logout URLs to support local development.
  • Advanced Settings. In the OAuth settings, the JSON Web Token (JWT) Signature Algorithm is set to RS256. Auth0 recommends this value and it allows you to sign the token with your tenant’s private key. Refer to the Auth0 documentation to learn more about JWT Signing Algorithms.

You can manage settings for the applications and APIs created through the Netlify UI in the Auth0 dashboard.

# Use Auth0 in your frontend application

Here is an example of how you can set up a frontend application to use the Auth0 extension.

This example uses the Auth0 SDK for React Single Page Applications, which provides the Auth0Provider function to wrap the App component. The App component can contain the logic for your specific use case, such as a login screen or a screen that grants access to an account.

To use the Auth0Provider function, provide the AUTH0_CLIENT_ID and AUTH0_DOMAIN environment variables that the extension created during configuration. In this example, the environment variables do not have a prefix, as one has not been set for the site.

import { Auth0Provider } from "@auth0/auth0-react";
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App.js";

const root = document.getElementById("root") as HTMLElement;

ReactDOM.createRoot(root).render(
  <React.StrictMode>
    <Auth0Provider
      clientId={import.meta.env.AUTH0_CLIENT_ID}
      domain={import.meta.env.AUTH0_DOMAIN}
      authorizationParams={{
        redirect_uri: window.location.origin
      }}
    >
      <App />
    </Auth0Provider>
  </React.StrictMode>
);

You can learn more about using Auth0 with Single-Page Applications in the Auth0 documentation.

# Create a function to use Auth0 on the backend

You can use the Auth0 extension to add authentication and authorization to a serverless function in your project. Below is an example of how to set up access control checks in functions in a project.

├─ netlify/
│  ├─lib/
│  │ └─ auth.ts
│  └─functions/
│    └─ get-users.ts

In this example, we'll protect the get-users function against access by an unauthenticated user.

To get started, install the dependencies used in this example:

npm install jose
npm install -D @netlify/functions

First, define a reusable helper that checks a request's authorization header for a valid Access Token signed by your Auth0 tenant. This helper function throws an error if the token is missing or invalid.

// netlify/lib/auth.ts
import { type JWTVerifyResult, createRemoteJWKSet, jwtVerify } from "jose";

export type VerifyAuth0TokenResult<
  CustomClaims extends Record<string, unknown> = Record<string, unknown>,
> = {
  token: string;
  result: JWTVerifyResult<CustomClaims>;
};

export const verifyAuth0Token = async <
  CustomClaims extends Record<string, unknown>,
>(
  request: Request,
): Promise<VerifyAuth0TokenResult<CustomClaims>> => {
  const authorization = request.headers.get("Authorization") ?? "";
  const [type, token, ...parts] = authorization
    .replace(/\s+/g, " ")
    .trim()
    .split(" ");

  if (type !== "Bearer" || parts.length !== 0) {
    throw new Error("Missing or invalid Authorization header");
  }

  const JWKS = createRemoteJWKSet(
    new URL(".well-known/jwks.json", process.env.AUTH0_ISSUER),
  );
  const result = await jwtVerify<CustomClaims>(token, JWKS, {
    issuer: process.env.AUTH0_ISSUER,
    audience: process.env.AUTH0_AUDIENCE,
  });
  return { token, result };
};

Next, create a function get-users that will reject access by unauthenticated requests:

// netlify/functions/get-users.ts
import type { Context } from "@netlify/functions";
import { type VerifyAuth0TokenResult, verifyAuth0Token } from "./auth.js";

export default async (request: Request, context: Context) => {
  let authResult: VerifyAuth0TokenResult;
  try {
    authResult = await verifyAuth0Token(request);
  } catch {
    return new Response("Authorization required", { status: 401 });
  }

  return Response.json({
    users: [
      { id: "1", email: "example-user-1@example.com" },
      { id: "2", email: "example-user-2@example.com" },
    ],
  });
};

In the example above, if a user isn’t authenticated they aren’t authorized to access the list of users.

You can use Auth0’s RBAC functionality or scopes and claims on the decoded token to add more complex authorization to the function. RBAC is enabled by default for Auth0 APIs created in the Netlify UI but you do need to configure permissions for roles on the API in your Auth0 dashboard.

When calling this example API, it’s important to make sure you send an authentication token. To generate a token, you can use a library such as @auth0/auth0-react. Read more on how to get an Access Token in Auth0’s documentation.

You can test your function locally when you launch Netlify Dev to start a development environment. When you run the command, Netlify Dev automatically injects all of your environment variables for use.

netlify dev

Visit localhost:8888 to launch your site locally. From here, you can test the action that triggers your function.

# Modify your configuration

If you need to modify the configuration values for a specific site, you can either update the configuration through the extension’s settings or update the environment variables directly.

To add additional tenants:

  1. In the Netlify UI, navigate to your site and then select under Extensions in the navigation.
  2. In the Auth0: Tenant settings section, add a tenant through Auth0. Once added, it will be saved to your list of tenants.

To update the extension’s site configuration settings:

  1. In the Netlify UI, navigate to the site you'd like to edit, then navigate to the and scroll to find the Auth0 extension settings.
  2. Select Manage site config.
  3. Edit the values as needed. The environment variables will update automatically.

Alternatively, you can update the environment variables directly.

# Uninstall the extension

As a Team Owner, to uninstall the Auth0 extension:

  1. In the Netlify UI, navigate to the site you'd like to edit, then navigate to the and scroll to find the Auth0 extension settings.
  2. Search for Auth0 and select it in the search results.
  3. On the details page, navigate to the Danger zone section, and then select Uninstall this extension.

Uninstalling the extension in Netlify doesn’t automatically delete Auth0 applications or APIs, nor does it unset any environment variables set on sites. To remove the applications, log into your Auth0 dashboard and follow the steps to delete tenants and remove applications.

# More resources