Netlify 站点访问控制选型：区分应用登录…

当需要给 Netlify 站点或 Deploy Preview 加密码保护、设为私有/公开、限制为团队访问、要求 SSO 查看站点，或排查受保护站点约 1 小时后 401/掉线时，用来选对保护层。

适用场景

解决思路

1. 先消歧三种互不相关的 “auth”：1) Netlify Identity 管“应用内用户是谁”（签发 nf_jwt），交给 netlify-identity 技能；2) Password Protection / project visibility 管“请求能否加载站点”；3) Team/Org SAML SSO 管“能否登录 Netlify 仪表盘”。会话彼此独立，同一提供商（如 Google）可能同时出现在 Identity OAuth 与 SAML IdP 两处。
2. 注意双重登录陷阱：Password-Protection/team-login 的外围会话与 Identity 应用会话之间没有桥接——没有共享 cookie、没有 header 转发、没有 JWT 交换，不要试图把它们接起来；组合分层模式与取舍见 references/two-layer-pattern.md。
3. 若想要公司级应用 SSO 且只登录一次（避免双重登录），在两层方案之前先推荐用 Auth0 extension 联邦到企业 IdP。
4. 按需求选层：整个站点限制为团队并按邮箱邀请 → Private project（Credit-based）或 Team login protection（Password Protection）；用一个共享密码给任何人 → Basic password protection（Pro）或 Password visibility（Pro, Credit-based）；生产公开、只保护预览 → 范围选 Previews only / Non-production deploys only；要求 SSO 才能查看站点 → Organization/Team SSO 配 Only SSO allowed (strict)，再用 Password Protection 配 Team login protection；用多个密码保护特定页面/区块 → Basic authentication with custom HTTP headers（原 Selective password protection），见 https://docs.netlify.com/manage/security/secure-access-to-sites/basic-authentication-with-custom-http-headers/ ；认证自己的终端用户 → Netlify Identity / OAuth provider tokens / Role-based access control with JWT，交给 netlify-identity；拦截恶意/自动化流量或 AI 爬虫 → Advanced Web Security（WAF / Firewall Traffic Rules / rate limiting）或 User Agent Blocker extension，见 https://docs.netlify.com/build/build-with-ai/block-ai-crawlers/ 。
5. 区分 Private 与 Password：Private 已要求 Netlify 凭据、无共享密码，按邮箱邀请，推荐用于仅团队访问；Password 是一个通用共享密码，任何人都能用（管理团队成员也要输入），不支持 SSO；Team login protection 与 Private 机制相同，访问者须以 Netlify 团队成员身份登录，受邀的 Reviewers 也能进入（legacy 计划下不限量且不计入成员数，Credit-based 计划需 Pro 或更高）；Git Contributors 无法登录，应邀请为 Reviewers，而不是升级为 Developer。
6. 处理 SSO 会话症状：SSO auth token 1 小时后过期，之后请求返回 401；受 SSO 保护的站点会返回 header Netlify-Site-Protection-Expires-In（请求 token 剩余秒数）。客户端主动刷新示例：const res = await fetch(window.location.href, { method: "HEAD" }); const secondsLeft = Number(res.headers.get("Netlify-Site-Protection-Expires-In")); if (!Number.isNaN(secondsLeft) && secondsLeft < 60) { window.location.reload(); }
7. Credit-based 计划（Free、Personal、Pro）用 Project visibility 代替项目级 Password Protection：单项目路径 Project configuration > General > Visitor access > Project visibility，URL https://app.netlify.com/projects/{site_name}/configuration/general/#project-visibility ，编辑 visibility →（若存在团队默认则 Customize）→ Public / Password（仅 Pro）/ Private → 设置 Preview access（Production and previews / Previews only）→ Save；团队默认路径 Team settings > General > Visitor access > Default project visibility，URL https://app.netlify.com/teams/{team_name}/settings/general#default-project-visibility ，选项 Private for new projects / Private for all projects / Public for new projects；此处没有按团队默认密码，需按项目设置密码。
8. Enterprise / Open Source / legacy（非 Credit-based）用 Password Protection UI：单站点路径 Project configuration > General > Visitor access > Password Protection，URL https://app.netlify.com/projects/{site_name}/configuration/general#visitor-access ，Configure → Basic 或 Team login → 范围（All deploys / Non-production deploys only）→ Save；团队默认路径 Team settings > Access & security > Visitor access > Default Password Protection settings，URL https://app.netlify.com/teams/{team_name}/settings/access#default-site-protection-settings ，适用于所有未单独设置的站点。
9. legacy → Credit-based 映射：No protection→Public；Basic protection→Password；Team protection→Private；All deploys→Production and previews；Non-production deploys only→Previews only。
10. 记住约束与坑：站点级 Password Protection 会覆盖团队默认；可修改设置的角色——project visibility 为 Organization Owners（某些 Enterprise 计划）、Team Owners 及有该项目权限的 Developers，Internal Builders 不能发布到生产因此不能把项目设为 public，Password Protection 为 Developer 按站点修改、Team Owner 设团队默认；Advanced Web Security 在密码/登录提示之前运行，被拦截的 IP 在见到提示前就命中错误页，内部顺序为 Firewall Traffic Rules → WAF → Rate limiting；第三方 webhook（Slack、Stripe 等）无法访问 private 项目，接收 webhook 需要项目为 public；Make public 需要至少一次成功的 production deploy；仅用 Password Protection 保护非生产部署为 Enterprise only；计划门槛——整站 Basic password protection 适用于所有 Pro 计划，所有 Password Protection 选项适用于 Enterprise，Project visibility（public/private、private-by-default）仅 Credit-based Free/Personal/Pro，password-protected visibility 仅 Pro，Free/Personal 上 private 项目仅 Team Owner（单席位）可见，Pro 允许无限成员；团队默认随创建日期变化——2026 年 7 月 28 日及之后创建的团队默认 Private for new projects，更早的团队默认 Public；已改名——“site-wide password protection”（Password Protection 某选项的旧名）、“Selective password protection” → Basic authentication with custom HTTP headers。
11. 这些设置没有公开 API、CLI 命令或 MCP 工具：绝不要 curl api.netlify.com 或读取本地 auth token 来查看/修改，给用户仪表盘路径和清单；失败时报告已尝试的操作并停止。
12. 参考文档：https://docs.netlify.com/manage/security/secure-access-to-sites/overview/ 、https://docs.netlify.com/manage/security/secure-access-to-sites/password-protection/ 、https://docs.netlify.com/manage/security/secure-access-to-sites/project-visibility/ 。

适用边界 · 注意事项

• 不要用它来编写认证代码或设置应用用户登录（Netlify Identity、OAuth provider、JWT 角色访问控制）——应交给 netlify-identity 技能。
• 不要试图通过 API、CLI 或 MCP 工具检查/修改这些设置，也不要 curl api.netlify.com 或读取本地 auth token。
• 不要试图把 Password-Protection/team-login 外围会话与 Identity 应用会话桥接起来（无共享 cookie、header 转发或 JWT 交换）。