/netlify-access-control

name: netlify-access-control
description: 'Picks the right Netlify site-protection layer and disambiguates the three unrelated "auth" concepts users conflate — app-user login (Netlify Identity), site-load gating (Password Protection / project visibility), and dashboard SAML SSO. Use it when asked to password-protect a site or Deploy Preview, make a project private/public, restrict a site to your team, require SSO to view a site, set up company-wide or internal-app SSO, invite users to a private project, or know which team member made a request to a private site. Also use it for SSO-session symptoms on protected sites: "logged out mid-session", 401s after about an hour, or token expiry/refresh questions. Not for wiring auth code — route app-login setup to netlify-identity.'

Netlify access control — pick the protection layer

This skill routes you to the correct protection layer. It does not teach each one. **These settings have no public API, CLI command, or MCP tool.** Never curl `api.netlify.com` or read local auth tokens to inspect or change them — give the user the dashboard path and checklist. On failure, report what you tried and stop.

First: disambiguate "auth" — three unrelated layers

Users constantly conflate these. Identify which one is meant before recommending anything.

1. **Netlify Identity** — "who is this user *inside my app*." Issues `nf_jwt`. → route to the **netlify-identity** skill; not covered here. 2. **Password Protection / project visibility** — "can this request load the site at all." Covered here. 3. **Team/Org SAML SSO** — "can you log in to the Netlify *dashboard*." Gates dashboard access; also underlies team-login site protection.

Sessions are separate. The same provider (e.g. Google) can appear twice unrelated — Identity OAuth for app users vs. SAML IdP for team members.

**Double-login footgun:** a Password-Protection/team-login perimeter session and an Identity app session have **no bridge** — no shared cookie, no header forwarding, no JWT exchange. Don't try to wire them together. For the combined layered pattern and its tradeoffs, see `references/two-layer-pattern.md`. The Netlify login itself *does* reach app code: on a private project or with team login protection, functions and edge functions receive the signed-in Netlify user as **`context.user`** — if every app user can pass that login, it is the app's identity and no second login is needed.

**Want an internal app with a single sign-in (no double login)?** First ask who uses it:

• **They can pass the project's Netlify login** → **Private project** (Credit-based plans; Pro for anyone beyond the Team Owner) or **team login protection** (Enterprise), and use `context.user` in functions for per-person behavior.
• **They can't** (e.g. employees without Netlify seats) → **Auth0 extension** federating to the corporate IdP, *before* the two-layer stack.

Decision guide (this skill's job)

• Restrict entire site to your team, invite by email → **Private project** (Credit-based) or **Team login protection** (Password Protection).
• Share with anyone holding one shared password → **Basic password protection** (Pro) or **Password** visibility (Credit-based Pro only). **Not available on Credit-based Free/Personal** — make the project **Private** instead.
• Keep production public, protect previews only → scope **Previews only** / **Non-production deploys only**.
• Require SSO to *view a site* → Organization/Team SSO with **Only SSO allowed (strict)**, then Password Protection with **Team login protection**.
• Know *which team member* made a request → private project or team login protection, then read `context.user` in functions/edge functions (not documented for basic password protection).
• Protect specific pages/sections with multiple passwords → **Basic authentication with custom HTTP headers** (formerly Selective password protection): https://docs.netlify.com/manage/security/secure-access-to-sites/basic-authentication-with-custom-http-headers/
• Authenticate your own end users → **Netlify Identity** / **OAuth provider tokens** / **Role-based access control with JWT** → route to netlify-identity.
• Block malicious/automated traffic or AI crawlers → **Advanced Web Security** (WAF / Firewall Traffic Rules / rate limiting) or **User Agent Blocker** extension: https://docs.netlify.com/build/build-with-ai/block-ai-crawlers/

Key distinction: Private vs Password

• **Private** already requires Netlify credentials — no shared password. Invite by email; recommended for team-only access.
• **Password** = one universal shared password anyone can use (including managing team members, who must also enter it). No SSO. Doesn't identify individual visitors.
• **Team login protection** = same mechanism as Private: a visitor must log in as a member of your Netlify team, and **Reviewers** you invite can get in too (unlimited and not counted toward the member count on legacy plans; Pro or higher on Credit-based plans). **Git Contributors cannot log in** — invite them as Reviewers rather than upgrading them to Developer.

Identify the visitor: `context.user`

With **team login protection** or on a **private project**, functions and edge functions get the signed-in Netlify user as `context.user`. Don't guess its fields — see https://docs.netlify.com/build/functions/api/#user and https://docs.netlify.com/build/edge-functions/api/#user.

SSO-session symptom: 401s after ~1 hour

If a user reports being "logged out mid-session" or 401s on an SSO-protected site: **SSO auth tokens expire after 1 hour**, after which requests return `401`. Sites with SSO protection return the header **`Netlify-Site-Protection-Expires-In`** — seconds until the request's token expires. Refresh proactively:

// Client-side. Checks the Netlify SSO protection header and reloads before expiry.
const res = await fetch(window.location.href, { method: "HEAD" });
const secondsLeft = Number(res.headers.get("Netlify-Site-Protection