Authentication is where trust begins. This guide covers sign-in options, roles and permissions, sessions, and account recovery for customer and staff experiences on Build Me Web applications.
Sign-in options
Email/password, magic links, and SSO (Enterprise) are supported. Choose the simplest option your audience will complete — friction kills activation. Consumer apps often win with magic links or social sign-in; B2B often needs SSO and SCIM-style provisioning.
Password policies should resist common breaches without sadistic complexity rules that drive reuse. Offer passkeys where platform support exists and your threat model benefits.
- Pick a primary method aligned to audience.
- Enable MFA for staff and high-value customer actions.
- Separate customer and staff identity planes — never share cookie jars casually.
- Localize sign-in error copy without revealing whether an email is registered on public forms.
Instrument sign-in funnel events (started, succeeded, failed reason buckets) so you can see whether MFA or form UX is the drop-off.
Roles & permissions
Map roles to capabilities, not pages. “Can refund orders” is a permission; “Billing page” is just where that capability appears. Staff roles should never reuse customer tokens.
Start with a small role set (Admin, Operator, Read-only) and expand when real job functions demand it. Audit role changes on Managed and Enterprise plans.
role: support_agent
permissions:
- orders.read
- orders.refund
- customers.read
deny:
- billing.settings.writeAuthorize on the server for every mutating request. Hide UI affordances for UX, but never as the only control.
Sessions
Use short-lived access tokens with rotating refresh tokens for SPAs. Harden cookies with Secure, HttpOnly, and SameSite where applicable. Absolute session lifetimes and idle timeouts should match risk: banking-like apps tighter than content personalization.
Revoke sessions on password change, role demotion, and suspected compromise. Provide a “sign out everywhere” control for users.
- Bind sessions to device fingerprints carefully — false positives lock out travelers.
- Prefer rotating refresh tokens with reuse detection.
- Store server-side session state when you need instant revocation.
Account recovery
Password reset and magic-link flows must rate-limit and expire quickly. Never reveal whether an email exists in error messages on public forms. Send the same generic response either way.
Support-assisted recovery should verify identity out of band for high-risk accounts. Log recovery events for audit.
- MFA enabled for privileged roles
- Session revocation tested
- Recovery emails authenticated (SPF/DKIM)
- Rate limits verified against abuse scripts
Troubleshooting
Users stuck in redirect loops: check cookie domain/path and HTTPS mismatches between app and auth host.
SSO users missing roles: verify group claim mapping and default role fallbacks.
Magic links failing: link TTL too short, email security scanners prefetching once-use links — use token exchange patterns that tolerate prefetch.
Prerequisites & preparation
Before changing production settings for authentication and accounts, align the people who own content, DNS, analytics, and approvals. A fifteen-minute kickoff that names owners prevents multi-day Slack archaeology later. Capture decisions in the workspace notes so the next teammate inherits context instead of guesswork.
Gather credentials and access: workspace admin or editor role, DNS control when hostnames are involved, payment or API sandbox accounts when money paths are involved, and a shared checklist link. Confirm which environment you will rehearse in — preview first, production only after a green run.
Choose primary sign-in methods per audience, define staff vs customer planes, and draft MFA policy for privileged roles.
Detailed walkthrough
Work the happy path slowly the first time. Narrate what you expect to see after each click: a status badge, a DNS record, a webhook delivery, a Lighthouse metric. When reality diverges, stop and resolve the mismatch instead of clicking ahead — most outages begin as ignored yellow states.
- Implement the primary sign-in method with clear, non-enumerating errors.
- Map a minimal role set to capabilities; enforce checks server-side.
- Configure session lifetimes, cookie flags, and sign-out-everywhere.
- Harden recovery flows with rate limits and short-lived tokens.
- Instrument sign-in funnel events for activation debugging.
Edge cases & failure modes
Plan for partial failure. Networks drop, registrars delay, providers rate-limit, and humans approve the wrong revision. Your runbook should say what “abort” looks like: leave preview up, roll back the release, or freeze campaigns until metrics recover.
- SSO group claims not mapped — users land with empty roles.
- Magic link prefetch by email scanners consuming one-time tokens.
- Cookie domain mismatches causing redirect loops.
QA checklist before you announce
- Happy path verified on mobile and desktop
- Failure path messaging reviewed
- Owners named for the first hour after launch
- Rollback or freeze path documented
Operating the change
After launch, watch the metrics that prove the change worked — not vanity charts. Pair quantitative signals with one qualitative check (support ticket themes, sales feedback). Schedule a follow-up within a week to remove temporary flags, raise DNS TTLs, or archive the experiment.
Audit privileged role changes and review break-glass access monthly.
Treat authentication and accounts as a repeatable playbook. The second time your team runs it should be faster because the checklist and owners already exist.
Friction kills activation — pick the simplest auth your audience will complete, then harden privileged actions with MFA.
Customer and staff identity planes should not share cookies or tokens casually.
Recovery messaging must be generic on public forms to avoid account enumeration.
Rotating refresh tokens with reuse detection help catch stolen session chains.
Passkeys where supported reduce password reuse risk for consumer audiences.
Log auth failures with enough detail for security review without storing secrets or raw passwords.
Implementation checklist
Confirm audience-appropriate primary sign-in methods on preview before you promote. Name who approves the change, which environment is authoritative, and what “done” looks like in measurable terms.
Document capability-based roles instead of page maps where the team already looks — workspace notes or the engineering handbook — not only in a meeting memory.
Rehearse MFA for privileged staff actions against written acceptance checks. If you cannot name the verification event (order, DNS lookup, deploy health, or signed API call), you are not ready to announce.
Operating it with your team
Measure session revocation on credential changes with anonymized but realistic data, and keep logs, headers, or screenshots for at least one release cycle so regressions have a baseline.
Automate non-enumerating recovery responses so the next teammate can repeat the path without tribal knowledge. Prefer vaulted secrets over chat paste, and archive temporary exceptions with an end date.
When you finish this guide, you should be able to explain the happy path, the abort path, and the metrics that prove success. If any of those are fuzzy, revisit the walkthrough with your teammates before you scale traffic, spend, or automation.