Role-based access control with JWT

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

A JWT is a compact, signed token that carries user data as claims: key-value pairs embedded in the token’s payload. When a user logs in, the authentication provider issues a JWT containing claims about that user, such as their email, roles, and when the token expires. Netlify reads these claims to make access control decisions.

Create users and set roles

When you use an authentication provider that supports JWT, your project visitors log in using the provider service, and the service returns a signed 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 provides JWT-based user authentication for your Netlify projects with minimal setup. When you set up Identity and use @netlify/identity, the Identity service generates a JWT and stores it in a cookie named nf_jwt. This cookie is sent automatically with requests to your project. Visit the Identity docs for next steps to:

• Register and authenticate Identity users
• Set Identity user roles
• Set roles programmatically

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 your project.

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 Project 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 project.

Team-wide default secret

You can set a default JWT secret for all projects belonging to your team under Team settings > Access & security > Visitor access > JWT secret. JWT settings at the project level will override team-level defaults.

Once you’ve configured your project, 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.

A JWT’s payload contains claims with information about the user. Among these claims, Netlify looks for the app_metadata object to read the user’s roles. The same user can have one or more roles to access different pages in your project. Make sure that the header and payload 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 direct them to different areas of your project 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.

_redirects

/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

netlify.toml

[[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.

Always include a fallback rule

Without a fallback rule, unauthorized users see a raw 404 page with no way to log in. Always pair a role-gated rule with a fallback that redirects unauthorized visitors to a login page or a helpful error page. For example:

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

The first rule grants access to users with the admin role. The second rule catches everyone else and redirects them to /login.

Role paths

Netlify looks for roles at different paths in the JWT depending on your authentication provider:

Provider	Default role path	Example
Netlify Identity	app_metadata.roles	{"app_metadata": {"roles": ["admin"]}}
External JWT provider	app_metadata.authorization.roles	{"app_metadata": {"authorization": {"roles": ["admin"]}}}

If your external provider stores roles at a different path, contact support to configure a custom role path for your project.

Role changes and JWT expiration

Changing a user’s roles does not invalidate their current JWT. The new roles take effect when the user’s token is next refreshed, typically on their next login or when their client calls refreshSession(). Keep this in mind when testing role changes.

Check roles server-side with Netlify Identity

In addition to CDN-edge redirect rules, with Netlify Identity you can check user roles in Netlify Functions and Edge Functions using getUser() from @netlify/identity. Use redirect rules for simple path-based access control, and function-based checks when you need custom authorization logic.