Netlify Role Management
Use Auth0 with your Jamstack websites on Netlify
Grow your users and drive traffic to a high-performing website with Auth0 and Netlify. Use the Auth0 integration to manage users and roles on your Jamstack sites hosted on Netlify. Once the integration is in place, you set roles for users in Auth0 and use Netlify Role-Based Redirects to direct users to different areas of your site. This access control is implemented at Netlify's CDN edge, removing the need for a round trip to an origin server.
Used by more than 1,000,000 web developers and businesses, Netlify is the fastest way to build and host the fastest sites. The Netlify platform provides modern developer workflows, serverless functions and a global High Performance Edge to deliver the most performant, secure and scalable websites backed by a 99.99% SLA. Netlify pioneered the Jamstack category, a modern web architecture that marries the best practices of static sites with the API economy and serverless functions, to deliver faster load times and dynamic content, without worrying about managing web servers. Founded in 2014, Netlify is a venture-backed software company headquartered in San Francisco with a global team.
Fast, global edge performance
Sites load in a fraction of the time because they’re pre-rendered and served directly from Netlify’s high performance Edge network. Netlify is built on the backbone of the world’s most trusted cloud providers like AWS, Azure and GCP.
Best for Web Developers
Get set up faster and ship more often with Netlify’s modern developer workflows. Build compelling experiences in any templating engine or frontend framework.
Way lower cost and complexity
Absorb huge traffic bursts without burdening your teams. Never count servers or wrestle with infrastructure again; Netlify manages and serves all your environments and auto-scales across our global network.
This integration walks you through how to use Auth0 to add authentication to your frontend web properties that are built and hosted on Netlify. You can use this functionality to gate content on your site, secure access to your web properties, or lock your site pre-release.
Netlify & Auth0 Working Together
Auth0 provides an easy-to-use and robust authentication service so that your developers can focus on building applications. Auth0 also allows you to set up multiple types of login options, multi-factor authentication, and roles and permissions.
Netlify provides modern build workflows, serverless functions and a global multi-cloud Edge network to deliver the most performant, secure and scalable Jamstack websites, all without having to manage web servers. Netlify makes it easy for developers to marry the best practices of pre-built sites with Auth0’s API for authenticating users.
- User visits the SPA and clicks to login
- This loads a Netlify Function that redirects to Auth0 to handle authentication
- After the user authenticates successfully, their current roles are checked and if they have don't have one, they will be given a default role using Auth0 Rules
- Auth0 sends the user back to a Netlify Function with their identity and roles in a JWT ID token
- The Netlify Function validates the token and sets a specific Netlify cookie
- Netlify RBAC (Role-based Access Control) verifies the JWT and grants access to the visitor based on their role.
- An Auth0 account
- A Netlify account - this guide uses features from the Enterprise or Business Tiers of Netlify
Deploy Web App to Netlify
Deploy to Netlify button in this Github repository to deploy the demo application to Netlify. This will create a new GitHub repository on your account and deploy it as a new web app to Netlify.
Netlify will generate a unique URL for your new web app. Take note of that URL as we will use it in a second.
Note: If you want to add this integration to an existing application hosted on Netlify, follow these steps.
- copy/paste the functions directory from the source code into your application
- copy/paste the
netlify.tomlfile from the source code into the root of your repository
- copy/paste the
_redirectsfile from the source code into your apps public directory
- add links on your site or application to
For reference, this starter code includes the following files.
We will be using serverless functions deployed and managed by Netlify to handle authentication and communication with Auth0. These functions are stored inside of a
functions directory in the Git repo. The
netlify.toml file includes the configuration to tell Netlify that our Serverless Functions exist inside of a directory called
functions and to deploy them.
[build] functions = "functions" publish = "public/" command = "npm run start"
publish directory is the directory (relative to the root of your repo) that contains the deploy-ready HTML files and assets generated by the Netlify build.
command refers to the build command used by Netlify to build the site into static assets.
Inside of that functions directory, there are four files.
AuthUtils.js → This file will contain the bulk of the Auth0 authentication logic. It will expose callback handlers that our three endpoints (login, logout, and callback) will use.
Login.js → This function will redirect the user to Auth0 to handle authentication.
Logout.js → This function will log the user out of Auth0 and also remove the cookie that Netlify uses to track the user.
Callback.js → This function will handle the redirect from Auth0 after login has been completed. It will validate the ID Token from Auth0 and use the data within to build a new JSON Web Token that Netlify will use for authorization purposes. This token will be stored as a cookie named
This file is used to define the redirect rules that Netlify will use to implement Role-Based Authentication Control (RBAC) and protect certain endpoints based on a user’s role(s). It includes the following two rules.
/admin/* 200! Role=admin /guest/* 200! Role=guest
The rule above tells Netlify's CDN to grant access to the
/admin path, and everything under it, only to visitors whose JWT tokens include the admin role in their
app_metadata. The same for the
/guest path and the
If a user tries to access one of those routes without the appropriate role, they will be redirected to a 404 page. This project includes a basic 404 page, but you can customize it in any way that you want.
If you wanted to redirect a user to a login page after being denied access, you could add the following rule to the
/admin/* /.netlify/functions/login 401! /guest/* /.netlify/functions/login 401!
Note: You can also add these redirect rules in the
netlify.toml file that contains the build command. If you specify your redirect rules in your Netlify configuration file, you can use a more structured configuration format.
This directory includes the frontend code for our site. It has the HTML files for protected pages nested under the admin and guest routes. The index page also includes the login and logout buttons that trigger the Netlify Functions to handle authentication.
Create New Application in Auth0
Start by creating an application in Auth0 by clicking Create Application on the Applications screen in the dashboard. Give your Application a new, choose "Regular Web Application" as the type, and click Create.
Then, click on the
Settings tab and take note of the Domain and Client ID fields at the top.
If you scroll down a bit, you’ll see settings for Allowed Callback URLs and Allowed Logout URLs. Update these accordingly.
- Allowed Callback URLs -
- Allowed Logout URLs -
For the Netlify Functions to trigger authentication and validate the user identity returned from Auth0, we will need to add the following details as environment variables in Netlify.
AUTH0_DOMAIN- The Domain from the Auth0 Application created above.
AUTH0_CLIENT_ID- The Client ID from the Auth0 Application created above.
AUTH0_TOKEN_NAMESPACE- The namespace used for custom claims in the ID Token. The default is "https://netlify-integration.com" and will be explained in the Auth0 Rule portion of this guide below.
TOKEN_SECRET- The secret used to sign a JSON Web Token. This should be at least 16 characters long and sufficiently random. You can use
openssl rand -base64 18or
pwgen 16 1on the command line to generate one.
For Netlify to verify the JWT and determine who is authorized for a route, it needs the
TOKEN_SECRET value above to be added in another part of the dashboard.
In Netlify Dashboard under Site settings > Access Control, update Password/JWT Secret with the value from the
TOKEN_SECRET environment variable above.
Create Roles in Auth0
You will need two roles,
guest role will be applied automatically on login and the
admin one can be given manually in the Auth0 dashboard.
guest role by clicking Users and Roles > Roles in the Auth0 dashboard and click Create Role. Give the first role a name of
guest, a description of your choosing, and then click Create.
After you create the role, take note of its ID in the URL so we can use it later in this guide.
Now, create the
admin role with the same steps. You won’t need to remember the id for this one.
Add the Auth0 Rule
Please note: Clicking any of the 3 buttons on the Edit Rule screen will save and activate the Rule. When initially installed, the Rule will be skipped until the required configuration (explained below) is added.
- Click Add Integration at the top of this page
- Click Save Changes to activate this integration
For information on testing and debugging Rules, please see our documentation.
Add the Auth0 Rule Configuration
The default role configuration is only necessary if you have routes that can be accessed simply by being logged in (like in our deployable sample at the top of this guide). If you are using default roles, make sure to add them to users that have elevated privileges, like the
Please note: Once marked the required configuration below is added, all logins for your tenant will be processed by this Rule. Please make sure all components have been configured correctly and verified on a test tenant before activating the integration in production.
- Click Back to Rules to get to the main Rules screen.
- Scroll down to the Settings section.
- Add the following keys (more about Rules configuration here):
DEFAULT_ROLE_NAME- The name of the default role to be given to a user; this is the name that Netlify will use to authorize the routes
DEFAULT_ROLE_ID- The ID of this role to be given to users if they do not already have a role; this is obtained from the URL above
CUSTOM_CLAIMS_NAMESPACE- The namespace for adding custom claims to the ID token (see formatting guidelines here). This will default to
https://netlify-integration.comand must match the
AUTH0_TOKEN_NAMESPACEvalue saved in Netlify above.
Test It Out
Trigger a new deploy of your Netlify site by clicking on the Trigger Deploy button in the Deploys tab of your site. Once deployed, click on the URL to the site and you should now be able to signup/login via Auth0 and view the guest page at
/guest/secret (since that is the role you will be assigned by default).
If you additionally give yourself the “admin” role in the Auth0 dashboard, after logging out and logging back in, you should be able to view the admin page (
/admin/secret) as well.
If you log out, and try to navigate directly to one of the protected pages (
/guest/secret), you should see the unauthorized page.