Netlify Docs
Ask Netlify

Contact

Site & team management /Security /Secure access to sites /

Role-based access control with JWT

Role-based access control allows you to set granular access to your site, or to specific pages. We use JSON Web Tokens (JWT), roles, and redirect rules to grant access to those sections.

# Create users and set roles

When you use an authentication provider that supports JWT, your site visitors log in to your site using the provider service, and the service returns an encrypted JWT with user data.

One JWT provider at a time

You may use Netlify Identity or an external provider for JWT-based authentication, but you cannot use both at the same time.

# Netlify Identity

Netlify Identity is built to provide JWT-based user authentication for your Netlify sites with minimal required setup. When you set up Identity for your site and use the Netlify Identity widget, the Identity service generates and saves a JWT in a cookie named nf_jwt. This cookie gets sent with requests to your site. Visit the Identity docs for next steps to:

When you’ve completed the setup above, come back to this page to learn how to configure role-based redirects below.

# External providers

This feature is available on Enterprise plans.

As an alternative to Netlify Identity, you can manage your users with any third party authentication provider that supports JWT tokens with roles metadata, such as Auth0 or Okta. Please note that you cannot authenticate third party JWT tokens if you have Netlify Identity enabled on a site.

To configure an external JWT secret:

  1. Generate a JWT application in your authentication provider of choice, and copy the application’s client secret.
  2. In the Netlify UI, go to
    Site configuration Access & security Visitor access JWT secret
    .
  3. Select Set JWT secret, and enter the secret from your authentication provider. We use this secret to verify the access tokens for your site.

Team-wide default secret

You can set a default JWT secret for all sites belonging to your team under

Team settings Access & security Visitor access JWT secret
. JWT settings at the site level will override team-level defaults.

Once you’ve configured your site, go back to your authentication provider and set roles for the users you want to grant access to. For example, you can set specific roles for people in a specific GitHub organization, or with a specific company email.

Netlify uses the app_metadata object in the token to read the user roles. The same user can have one or more roles to access different pages in your site. Make sure that the header and token have the following format.

The header has two required fields with set values. Netlify requires JWT tokens to be signed with the HS256 algorithm.

{
  "alg": "HS256",
  "typ": "JWT"
}

The token payload has a required exp (expiration) field, while other fields are optional. The value of exp should be a time/date in the future using the Unix Epoch time format.

{
  "id": "some id",
  "exp": 1602522810,
  "app_metadata": {
    "authorization": {
      "roles": ["admin","editor"]
    }
  }
  "iat": 1607022935
}

Although the example above reflects the standard path Netlify expects for app_metadata.authorization.roles, you can contact support to change this path if your external authentication provider requires it.

# Redirect visitors based on roles

Once you have a method for authenticating users with roles assigned in app_metadata, you can start directing them to different areas of your site with role-based redirects. This access control is implemented at our CDN edge, removing the need for a round trip to our origin servers.

Role-based redirect rules work like other redirect rules on Netlify, except that they include a Role parameter which determines which users are redirected according to the rule. If a visitor with a different role tries to access the specified path, they will get a 404 page unless you specify a fallback.

You can set redirect rules in a _redirects file or in a Netlify configuration file.

/admin/*  /admin/:splat  200!  Role=admin

# 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`.
# Any other visitor that tries to access those URLs will be
# presented with a 404 page.

# If you don’t want to present a 404 page, you can set a fallback rule
# to redirect unauthorized users to a specific page, like a login page.
# The next example adds a new rule to accomplish that:

/admin/*  /admin/:splat  200!  Role=admin
/admin/*  /login  401!

# The second rule in the example is what we call a fallback rule.
# It tells Netlify’s CDN that it must redirect every visitor that’s
# not in the `admin` role to the `/login` page.

# You can also grant several roles access to the same path
# by chaining them with commas:

/private/* /private/:splat  200!  Role=editor,admin

[[redirects]]
  from = "/admin/*"
  to = "/admin/:splat"
  force = true
  status = 200
  conditions = {Role = ["editor", "admin"]}

# In this example, visitors whose JWT tokens include the `admin` or
# `editor` role can access the `/admin` path.

You can read more about these and other redirect rules in our redirects documentation.

Check out our blog for more information about role-based access control.