Netlify auth: site protection, app login, or team SSO?
Three unrelated things get called auth on Netlify. Which one you need, how to tell them apart, and why their sessions can't be bridged.
Key takeaways
Three unrelated layers on Netlify all get called “auth,” and picking the wrong one costs real time. Project visibility / Password Protection decides whether a request can load the site at all. Netlify Identity decides who a user is inside your app. Team and Org SAML SSO decides who can log into the Netlify dashboard. Their sessions are entirely separate, with no bridge between them.
- “Lock this site to my company” is project visibility or Password Protection, not Identity.
- “Let my users sign up and log in” is Netlify Identity.
- “My team should sign into Netlify with Okta” is Team or Org SAML SSO, and it has nothing to do with your visitors.
- The same provider can appear twice. Google can be an Identity OAuth provider for your app users and a SAML IdP for your team. Unrelated wiring.
- Stacking a perimeter on Identity means two logins. There’s no shared cookie, forwarded header, or JWT exchange.
- If you want one sign-in company-wide, use invite-only Identity or the Auth0 extension.
The question underneath the question
“How do I add auth to my Netlify site?” has three correct answers, and they don’t overlap. Someone asking it usually wants one of these:
- Keep the public out while we’re still building.
- Let our customers create accounts and see their own data.
- Make our team sign into Netlify itself with the company IdP.
Those need three different features, configured in three different places, and the sessions they create don’t talk to each other. Getting this wrong is one of the most common sources of wasted iterations on the platform, usually in the form of someone trying to make a password gate log a user into their app.
So: work out which layer you’re in before you configure anything.
The three layers
Layer 1: can this request load the site?
Project visibility (credit-based plans) or Password Protection (Enterprise, Open Source, legacy). This is the platform perimeter, enforced before your site is served at all.
Use it when you want to keep the public out entirely: a site still in development, an internal tool, a client preview, or deploy previews that shouldn’t be indexed or shared. It has no concept of individual app users. It’s a door, not an account system.
Options are Public, Password (one shared secret, Pro only among credit-based plans), or Private (team and invitees, enforced with Netlify login). Full setup in How to password-protect a Netlify site or deploy previews.
Layer 2: who is this user inside my app?
Netlify Identity. This is app-level authentication: signup, login, OAuth social login, roles, and per-user data. It issues an nf_jwt cookie and your visitors don’t need Netlify accounts.
Use it when your product has users. Anything involving “log in,” “sign up,” “my account,” or “only show this user their own records” is this layer. Full setup in How to add user login to a Netlify site with Identity.
Worth stating plainly since the opposite is widely believed: Identity was announced as discontinued and that decision was reversed after community pushback. It’s supported and included on all credit-based plans at no extra cost.
Layer 3: who can log into the Netlify dashboard?
Team and Organization SAML SSO. This governs your team members’ access to Netlify itself: the dashboard, the deploys, the settings.
Use it when you want employees to reach Netlify through Okta, Entra, or Google Workspace. It has nothing to do with your site’s visitors, and configuring it will not affect who can load your site.
The one place layers 1 and 3 touch: Password Protection’s team login protection option authenticates against Netlify team login, which is SSO-capable. So you can require company SSO to view a site by combining them. That’s still layer 1 doing the gating.
Pick the layer
| What you want | Layer | Feature |
|---|---|---|
| Restrict the site to your team, invite by email | 1 | Private project, or team login protection |
| A shared password anyone on the team can use | 1 | Basic password protection, or Password visibility (Pro) |
| Protect only previews, keep production open | 1 | ”Previews only” / “Non-production deploys only” |
| Require company SSO to view the site | 1 + 3 | Org/Team SSO with Only SSO allowed (strict) plus team login protection |
| Let users sign up and log in to your app | 2 | Netlify Identity |
| Gate part of your app by user role | 2 | Identity roles plus role-based redirects |
| Employees sign into the Netlify dashboard via Okta | 3 | Team or Org SAML SSO |
| One company-wide app sign-in, no double login | 2 | The Auth0 extension, federating to your IdP |
Why the sessions can’t be bridged
This is the part worth understanding, because it saves you from a project that can’t work.
If you enable a perimeter gate and Netlify Identity, users log in twice. The perimeter (Password Protection or SAML SSO) authenticates a Netlify team member and issues its own session, with SSO tokens on that path expiring after about an hour. Identity authenticates an app end user and issues the nf_jwt cookie.
There is no documented passthrough between them: no shared cookie, no forwarded header, no JWT exchange that turns “passed the perimeter” into “logged in to the app.” And even a hypothetical bridge wouldn’t be clean, because a perimeter session represents team-member identity, not an app end-user record with app_metadata.roles.
An unofficial netlify/netlify-plugin-identity-sso repo once attempted this. It’s unofficial, dormant since 2021, and hardcoded for @netlify.com emails. Don’t build on it.
Practical takeaway: if a single sign-in matters, choose invite-only Identity or the Auth0 extension. Don’t try to fuse the two layers.
The four ways to get “company-only plus per-user identity”
A common enterprise ask conflates two real concerns: the deployed app should be reachable only by employees (perimeter), and the app should tell users apart (in-app identity). Four ways to satisfy both, least to most friction.
Option A: invite-only Netlify Identity. The best default for “just my team.” Enable Identity in invite-only mode and invite only company addresses. Identity becomes both the perimeter and the in-app identity: no uninvited user can sign in, and everyone signed in is a real Identity user with roles. One login, available on all plans, free. The tradeoffs are manual invite management, no automatic provisioning from a corporate directory, and reliance on invite links not being shared. Great for internal tools and small teams; doesn’t scale cleanly to thousands of employees.
Option B: the Auth0 extension. The best fit for a real organization with an existing IdP. Configure Auth0 to federate with Okta, Entra, Google Workspace, or similar. Auth0 enforces company-only access through its connection and organization settings and supplies per-user identity, in a single sign-in with support for auto-provisioning. More moving parts than Identity, and it needs Auth0 configuration. This is the path when invite-only Identity won’t scale.
Option C: Basic Password Protection plus Identity. A shared-password gate in front (Pro and above) with Identity inside for per-user accounts. Two logins, but the first is a single shared secret rather than a per-user login, so it’s lighter than Option D. Good for “keep the public out while we build” plus real user accounts without an Enterprise plan. The shared password is easily forwarded, so treat it as a soft gate rather than real access control.
Option D: Enterprise team-login perimeter plus Identity. The genuine two-layer setup: Team or Org SAML SSO with Password Protection set to team login, optionally strict, and Identity running separately for app sessions. Two logins, Enterprise only. There’s also a hidden cost: team login admits only Netlify team members, so every employee who passes the perimeter needs a paid Netlify seat. Choose this only when a true CDN-edge perimeter is a hard requirement and the double login is acceptable.
Common failure modes
You configured Identity to keep the public out and it didn’t. Identity in open-registration mode lets anyone sign up. Either switch to invite-only (Option A) or add a perimeter (layer 1).
You set up team SSO and your site visitors still aren’t gated. Team SSO is layer 3, dashboard access. To gate the site itself you also need Password Protection with team login protection.
You’re trying to make the password gate log users into your app. It can’t. See the section above.
You went looking for an API to set project visibility. There isn’t one. Layer-1 settings have no public API, no CLI command, and no MCP tool. The dashboard is the only surface.
Your team members get prompted for the site password. Basic password protection prompts everyone, managing team members included. Use Private or team login instead.
Git Contributors can’t reach a protected deploy. Team login excludes them by design.
Your webhooks stopped arriving after you made the project private. Private projects can’t receive third-party webhooks. That needs a public project.
A visitor got an error page rather than a login prompt. Advanced Web Security (firewall rules, WAF, rate limiting) runs before any password or login prompt, so a blocked IP never sees one.
Your SSO-protected site returns 401 after an hour. SSO tokens expire after 1 hour. Read the Netlify-Site-Protection-Expires-In response header and re-authenticate before it hits zero.
You enabled Identity and an external JWT provider together. You can use one or the other, not both. External JWT providers are Enterprise-only, and you can’t authenticate third-party JWT tokens while Identity is enabled.
Reference
The three layers at a glance
| Layer 1 | Layer 2 | Layer 3 | |
|---|---|---|---|
| Question | Can this request load the site? | Who is this user in my app? | Who can log into Netlify? |
| Feature | Project visibility / Password Protection | Netlify Identity | Team / Org SAML SSO |
| Applies to | Site visitors | App end users | Netlify team members |
| Session | Perimeter session (SSO path ~1 hour) | nf_jwt cookie | Netlify dashboard session |
| Configured in | Dashboard only, no API | Dashboard plus @netlify/identity code | Dashboard, org or team settings |
| Plans | Project visibility: credit-based Free/Personal/Pro. Password Protection: Enterprise/OSS/legacy. Shared password: Pro+. | All credit-based plans, no extra cost | Enterprise-oriented |
What the old names mapped to
| Old name | Now |
|---|---|
| Site-wide password protection | Part of Password Protection |
| Selective password protection | Basic authentication with custom HTTP headers (code you author) |
| Basic protection | Password (project visibility) |
| Team protection | Private (project visibility) |
| All deploys | Production and previews |
| Non-production deploys only | Previews only |
Sessions, spelled out
Layer 1 and layer 2 sessions are independent. There is no shared cookie, no forwarded header, and no JWT exchange. A layer-1 session identifies a Netlify team member; a layer-2 session identifies an app end user with app_metadata.roles. Neither can substitute for the other.
FAQs
What’s the difference between Netlify Identity and password protection?
Identity is app-level authentication: your users sign up, log in, and get roles, and it issues an nf_jwt cookie. Password protection is a platform perimeter deciding whether a request can load the site at all, with no concept of individual app users.
How do I lock a Netlify site to my company? For a small team, invite-only Netlify Identity is the simplest single-login option. For an organization with an existing IdP, use the Auth0 extension. For a true CDN-edge perimeter, use Private project visibility or team login protection, accepting that pairing it with Identity means two logins.
Does Netlify SSO protect my site or just the dashboard? By itself, just the Netlify dashboard for your team members. To require SSO to view a site, combine it with Password Protection set to team login protection.
Why do my users have to log in twice? You have both a perimeter gate and Netlify Identity active, and their sessions are independent by design. Use invite-only Identity or the Auth0 extension if you need one sign-in.
Can I bridge the password-protection session into my app’s Identity session? No. There’s no shared cookie, forwarded header, or JWT exchange, and a perimeter session represents team-member identity rather than an app user record.
Is Netlify Identity deprecated? No. It was announced as discontinued and then reinstated after community pushback. It’s supported on all credit-based plans at no extra cost.
Can I set project visibility from the CLI or API? No. Layer-1 settings have no public API, CLI command, or MCP tool. Use the dashboard.
Which layer do I need to gate one page by user role? Layer 2. Assign Identity roles and use role-based redirect rules, remembering to include a fallback rule so users without the role get a login page rather than a raw 404.
Can the same Google account be used for both my app users and my team? Yes, but they’re unrelated configurations: Google as an Identity OAuth provider for app users, and Google Workspace as a SAML IdP for team members. Setting up one does nothing for the other.
Related
- Configure Team SAML SSO
- Configure Organization SAML SSO
- Basic authentication with custom HTTP headers
This article is generated from Netlify’s open-source agent guidance at netlify/context-and-tools, the same reference our AI coding agents use.
Ready to build? Start at netlify.new.