How to add authentication to your Netlify site with Netlify Identity

Netlify Identity makes it possible to add authentication to a static site without running your own backend. It handles user management, login flows, and secure token handling, while staying tightly integrated with the rest of the Netlify platform.

This guide walks through setting up Netlify Identity from scratch and wiring it into a typical static site.

What is Netlify Identity

Netlify Identity is a managed authentication service built on top of GoTrue. It provides:

Email and password authentication
OAuth providers like GitHub and Google
User roles and metadata
JWT-based authentication tokens
Built-in UI widgets or custom implementations

Because Identity is deeply integrated with Netlify, it works especially well with Netlify Functions for gated content, admin areas, and APIs.

Requirements

Before getting started, make sure you have:

A Netlify account
A site deployed on Netlify
Basic familiarity with HTML and JavaScript
Netlify CLI installed (recommended for local testing)

Enabling Netlify Identity

Start by enabling Identity for your site.

Open your site in the Netlify dashboard
Go to Site configuration
Select Identity from the sidebar
Click Enable Identity

Once enabled, Netlify automatically provisions the Identity service for your site.

Enabling Git Gateway (optional but common)

If you plan to use Identity with a CMS like Netlify CMS or Decap CMS, you should also enable Git Gateway.

In the Identity settings, find Services
Enable Git Gateway
Choose a provider (GitHub is the most common)

This allows authenticated users to push content changes back to your repository.

Adding the Netlify Identity widget

The fastest way to get authentication working is by using the official Identity widget.

Add the script to your site, typically in the <head>:

<script src="https://identity.netlify.com/v1/netlify-identity-widget.js"></script>

Then initialize it in your JavaScript:

if (window.netlifyIdentity) {
  window.netlifyIdentity.on("init", user => {
    if (!user) {
      window.netlifyIdentity.on("login", () => {
        document.location.href = "/dashboard";
      });
    }
  });
}

This gives you a fully functional login and signup modal with no custom UI work required.

Opening the login modal

To let users sign in, add a button anywhere on your site:

<button onclick="netlifyIdentity.open()">Log in</button>

You can also open specific views:

netlifyIdentity.open("signup")
netlifyIdentity.open("login")

Accessing the current user

Once logged in, you can access the current user object:

const user = netlifyIdentity.currentUser()

if (user) {
  console.log(user.email)
}

The user object includes metadata, roles, and JWT tokens.

Protecting pages with redirects

A common pattern is protecting pages using Netlify redirects.

Create a _redirects file or add this to netlify.toml:

[[redirects]]
from = "/dashboard"
to = "/login"
status = 302
conditions = { Role = ["authenticated"] }

This ensures only authenticated users can access the dashboard.

Using Identity with Netlify Functions

Netlify Functions can validate Identity tokens automatically.

Example function:

import type { Handler } from "@netlify/functions"

export const handler: Handler = async (event) => {
  const user = event.context.clientContext?.user

  if (!user) {
    return {
      statusCode: 401,
      body: "Unauthorized"
    }
  }

  return {
    statusCode: 200,
    body: JSON.stringify({
      message: "Hello authenticated user",
      email: user.email
    })
  }
}

This makes it easy to build authenticated APIs without managing sessions yourself.

Managing users and roles

In the Netlify dashboard, you can:

View all users
Assign roles
Disable or delete accounts
Invite users manually

Roles are especially useful for admin-only areas and CMS access.

Custom authentication UIs

If you don’t want to use the widget, you can build a fully custom UI using the GoTrue API directly. This gives you complete control over the UX while still using Netlify Identity under the hood.

This approach is more advanced but works well for production apps with custom design requirements.

When Netlify Identity is a good fit

Netlify Identity works best when:

You are building a static or JAMstack site
You want authentication without maintaining a backend
You need simple role-based access control
You are already using Netlify Functions

For very complex auth requirements or enterprise SSO, a dedicated auth provider may still be a better choice.

Final thoughts

Netlify Identity is one of the easiest ways to add authentication to a static site. It removes a huge amount of backend complexity while still giving you secure, flexible user management.

If you are already deploying on Netlify, it is often the fastest path from “public site” to “authenticated app.”