Back to Details

netlify-access-control

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Netlify Access Control

Netlify访问控制

"Auth" on Netlify means three different things that are easy to conflate. Picking the wrong one — or stacking two when one would do — is the main source of friction. This skill disambiguates the layers and routes you to the right one. For actually building app-level user auth, see the netlify-identity skill.
Netlify中的“身份验证”指三种容易混淆的不同功能。选错功能——或在只需一种时叠加两种——是主要的困扰来源。本技能将明确区分这些层级，并引导你选择正确的方案。若要实际构建应用级用户身份验证，请查看netlify-identity技能。

The three layers

三个层级

LayerAnswersWho it's forPlanHow it's configured
Netlify Identity"Who is this user inside my app?" (signups, logins, roles; issues 
nf_jwt
)		Your app's end usersAll plans, freeDashboard + 
@netlify/identity
code
Password Protection (Secure access to sites)"Can this request even load the site?"Basic: anyone with a shared password · Team login: Netlify team membersBasic: Pro+ · Team login: EnterpriseDashboard-only
Team / Org SAML SSO (Secure access to Netlify)"Can you log in to the Netlify dashboard?" (and, with strict mode, pass the site gate)Netlify team members, via a corporate SAML IdPEnterpriseDashboard-only
These are independent. The 
nf_jwt
cookie is issued by app-level JWT auth: Netlify Identity, or a configured external JWT provider such as Auth0/Okta (the two are mutually exclusive); Password Protection and SAML SSO sessions are separate, with their own lifecycles, and do not populate 
nf_jwt
.
Note on terminology: Netlify's docs file Identity, Password Protection, role-based access, and more under an umbrella called "Secure access to your sites," while SAML SSO lives under "Secure access to Netlify." So "Secure Access" is not one feature — when a user says it, find out whether they mean gating site visitors (Password Protection) or gating dashboard login (SAML SSO).
层级解决的问题适用人群套餐配置方式
Netlify Identity“我的应用内的这个用户是谁？”（注册、登录、角色；颁发
nf_jwt
）		你的应用终端用户所有套餐，免费版可用控制台 + 
@netlify/identity
代码
密码保护（站点安全访问）“该请求是否能加载站点？”基础版：拥有共享密码的任何人 · 团队登录：Netlify团队成员基础版：Pro及以上 · 团队登录：Enterprise套餐仅通过控制台
团队/组织SAML SSO（Netlify安全访问）“你能否登录Netlify控制台？”（在严格模式下，可通过站点访问验证）Netlify团队成员，通过企业SAML身份提供商Enterprise套餐仅通过控制台
这些功能相互独立。
nf_jwt
cookie由应用级JWT身份验证颁发：Netlify Identity，或已配置的外部JWT提供商（如Auth0/Okta，二者互斥）；密码保护和SAML SSO会话是独立的，有各自的生命周期，且不会填充
nf_jwt
。
术语说明：Netlify文档将Identity、密码保护、基于角色的访问等归类在“站点安全访问” umbrella下，而SAML SSO则归类在“Netlify安全访问”下。因此“Secure Access”并非单一功能——当用户提及它时，需确认他们指的是限制站点访问者（密码保护）还是限制控制台登录（SAML SSO）。

Why Google causes confusion

为何Google会引发混淆

The same provider can show up in two unrelated places:
  • Google as a Netlify Identity OAuth provider — your app's end users click "Log in with Google." Any Google account works, it creates an Identity user, and it issues an 
    nf_jwt
    . This is app-level auth.
  • Google Workspace as a SAML IdP for Team/Org SSO — your Netlify team members log in to the dashboard (and, with strict mode + team-login, pass the site gate) using their corporate Google account. It does not create an Identity user and does not issue an 
    nf_jwt
    .
Both are "sign in with Google," but they target different populations and produce different sessions. Don't assume one implies the other.
同一提供商可能出现在两个不相关的场景中：
  • 作为Netlify Identity OAuth提供商的Google —— 你的应用终端用户点击“使用Google登录”。任何Google账号均可使用，它会创建一个Identity用户，并颁发
    nf_jwt
    。这属于应用级身份验证。
  • 作为团队/组织SSO的SAML身份提供商的Google Workspace —— 你的Netlify团队成员使用企业Google账号登录控制台（在严格模式+团队登录下，可通过站点访问验证）。它不会创建Identity用户，也不会颁发
    nf_jwt
    。
两者都是“使用Google登录”，但针对不同人群，生成的会话也不同。不要假设二者存在关联。

Pick the layer

选择合适的层级

Start from what the user actually needs and walk down:
  1. Does anyone need to be blocked from loading the site at all?
    • No — the site is public, but I need user accounts/roles inside the app → Netlify Identity (open or invite-only registration). Use the netlify-identity skill. Done.
    • Yes — restrict who can reach it → keep going.
  2. What kind of restriction?
    • Just keep the public out — a shared secret is fine, no per-user identity needed (staging, a soft pre-launch gate) → Basic Password Protection (Pro+, one shared password). Dashboard-only.
    • Only my employees, it's an internal tool / smaller team, and I also want to tell users apart inside the app → invite-only Netlify Identity (all plans, free). Invite only company addresses; Identity itself becomes the gate because no uninvited user can sign in. One login, full per-user identity, every plan. This is the best default for "employees-only internal tool." Tradeoff: you manage invites manually and rely on invite links not being shared — it doesn't auto-provision from a corporate directory.
    • Big company, app-level company SSO with a single sign-in (no double login), where company-only is enforced inside the IdP → the Auth0 extension. The extension links an Auth0 tenant to your site and exposes 
      AUTH0_*
      env vars so your app authenticates end users through Auth0; Auth0 federates to your corporate IdP (Okta, Entra, Google Workspace) and enforces who counts as company, so users sign in once. This is app-level, not a CDN-edge perimeter: the site still loads and your app redirects unauthenticated visitors. Use it when invite-only Identity won't scale to a real org but you don't need a true edge perimeter; that's Option D below. Configured via the Netlify Auth0 extension (dashboard); see the Netlify docs setup guide.
    • I genuinely need a CDN-edge perimeter (Enterprise team login / SSO-gated site access) AND a separate app-level Identity → the two-layer pattern. This works, but users sign in twice (once at the perimeter, once in the app) — there is no passthrough today. Read references/two-layer-pattern.md before recommending it.
If the user isn't sure, the most common real answer is invite-only Netlify Identity for "just my team" and the Auth0 extension for "my whole company with our existing IdP." Lead with those before reaching for the double-login stack.
从用户的实际需求出发，逐步筛选：
  1. 是否需要阻止任何人加载站点？
    • 不需要——站点是公开的，但我需要应用内的用户账号/角色 → Netlify Identity（开放或仅邀请注册）。使用netlify-identity技能。操作完成。
    • 需要——限制访问人群 → 继续筛选。
  2. 需要哪种限制方式？
    • 只需阻止公众访问——共享密钥即可，无需每个用户的独立身份（预发布环境、软发布验证） → 基础密码保护（Pro及以上套餐，单个共享密码）。仅通过控制台配置。
    • 仅允许员工访问，用于内部工具/小型团队，同时需要在应用内区分用户 → 仅邀请模式的Netlify Identity（所有套餐，免费版可用）。仅邀请公司邮箱用户；Identity本身即可作为访问入口，因为未被邀请的用户无法注册。一次登录，完整的用户身份，适用于所有套餐。 这是“仅员工可用的内部工具”的最佳默认方案。权衡点：你需要手动管理邀请，且依赖邀请链接不被泄露——它无法从企业目录自动配置用户。
    • 大型企业，需要应用级企业SSO实现单点登录（无需双重登录），且通过身份提供商强制仅允许公司用户访问 → Auth0扩展。该扩展将Auth0租户与你的站点关联，并暴露
      AUTH0_*
      环境变量，以便你的应用通过Auth0对终端用户进行身份验证；Auth0与企业身份提供商（Okta、Entra、Google Workspace）联合，强制验证用户是否属于公司，因此用户只需登录一次。这属于应用级，而非CDN边缘边界防护：站点仍会加载，你的应用会将未验证的访问者重定向。当仅邀请模式的Identity无法适配大型组织，但你不需要真正的边缘边界防护时使用此方案；下方的选项D是另一种情况。通过Netlify Auth0扩展（控制台）配置；查看Netlify文档中的设置指南。
    • 确实需要CDN边缘边界防护（Enterprise团队登录/SSO验证的站点访问）AND独立的应用级Identity → 两层模式。此方案可行，但用户需要登录两次（一次在边界防护层，一次在应用内）——目前没有打通两者的机制。在推荐此方案前，请阅读references/two-layer-pattern.md。
如果用户不确定，最常见的实际方案是：针对“仅我的团队”使用仅邀请模式的Netlify Identity，针对“整个公司且使用现有身份提供商”使用Auth0扩展。在推荐双重登录方案前，优先考虑这两种。

The double login is real — name it early

双重登录是真实存在的——提前说明

When Password Protection (team login) and Netlify Identity are both on, users authenticate twice and there is no documented bridge between them — no shared cookie, no header forwarding, no JWT exchange. Don't burn iterations trying to wire the perimeter session into the app session; it isn't supported. If single sign-on matters, that's a reason to choose the Auth0 extension (or invite-only Identity) instead of the two-layer stack. Full detail and the per-option tradeoffs are in references/two-layer-pattern.md.
Also flag the hidden cost of team-login: it admits only Netlify team members, so every employee who passes that gate needs a paid Netlify seat. That alone usually rules it out for company-wide apps.
当同时启用密码保护（团队登录）和Netlify Identity时，用户需要验证两次，且两者之间没有文档化的打通机制——没有共享cookie、没有头部转发、没有JWT交换。不要浪费时间尝试将边界会话接入应用会话；这不受支持。如果单点登录很重要，那这就是选择Auth0扩展（或仅邀请模式的Identity）而非两层方案的原因。详细信息及各选项的权衡点请见references/two-layer-pattern.md。
同时要注意团队登录的隐性成本：它仅允许Netlify团队成员访问，因此所有通过该验证的员工都需要付费的Netlify席位。这一点通常会排除其在全公司应用中的使用。

Configuration is dashboard-only — hand it off, don't probe

配置仅通过控制台完成——引导用户操作，不要自行探测

Password Protection, Team/Org SAML SSO, and the Auth0 extension are all configured in the Netlify dashboard or the extensions UI — there is no public API, CLI command, or MCP tool to set or read them, and there is no way for an agent to see this state while writing code. So:
  • Give the user the dashboard location and an exact checklist; let them flip the setting and confirm.
  • Do not 
    curl https://api.netlify.com/...
    , read tokens off disk, or probe for an undocumented endpoint to inspect or change access settings.
  • If a documented path fails, report it to the user with context (what you tried, the URL, the error) and stop — don't work around it.
For the one piece an agent can read at runtime (which Identity providers are live), call 
getSettings()
from 
@netlify/identity
rather than hard-coding assumptions. It hits 
/.netlify/identity/settings
and works against any origin serving the page, including localhost under 
netlify dev
(which proxies to the live service). See the netlify-identity skill.
密码保护、团队/组织SAML SSO和Auth0扩展均通过Netlify控制台或扩展UI配置——没有公开API、CLI命令或MCP工具可设置或读取这些配置，且代理在编写代码时无法查看这些状态。因此：
  • 告知用户控制台中的位置和明确的操作清单；让他们自行切换设置并确认。
  • 不要执行
    curl https://api.netlify.com/...
    、从磁盘读取令牌或探测未公开的端点来检查或修改访问设置。
  • 如果文档化的路径失败，请向用户报告上下文信息（你尝试的操作、URL、错误信息）并停止——不要尝试绕过限制。
对于代理在运行时可以读取的内容（当前启用的Identity提供商），请调用
@netlify/identity
中的
getSettings()
，而非硬编码假设。它会请求
/.netlify/identity/settings
，适用于任何提供页面的源，包括
netlify dev
下的本地环境（它会代理到实时服务）。请查看netlify-identity技能。

References

参考资料

  • Two-layer pattern (perimeter + in-app identity) — the four architecture options for "company-only access + per-user identity," the double-login reality, plan/seat costs, and the visibility gap.
  • 两层模式（边界防护+应用内身份验证） —— “仅公司用户访问+用户独立身份”的四种架构选项、双重登录的实际情况、套餐/席位成本以及可见性差距。