Authentication Setup

Authentication Setup

Use this skill when the real job is choosing and structuring product authentication for a real app, not dumping JWT snippets or pretending authentication, authorization, security hardening, and docs are all the same task.

authentication-setup owns the setup layer for:

• choosing hosted vs framework-native vs platform-native vs enterprise add-on vs self-hosted auth
• deciding session/cookie vs token boundaries
• selecting login methods: email/password, magic links, social OAuth, passkeys
• defining what user/profile/org/membership data stays app-owned
• planning SSO/SCIM, domain mapping, and migration/cutover boundaries
• recording callback URLs, cookie domains, preview/staging drift, and rollout notes

Read these support docs before choosing the lane or handoff:

• references/auth-decision-matrix.md
• references/boundary-checklist.md
• references/session-and-deployment-notes.md
• references/enterprise-and-migration-notes.md

When to use this skill

• Set up auth for a new web app, SaaS product, admin app, or API-backed product
• Decide between Clerk, Auth.js, Better Auth, Supabase Auth, Firebase Auth, Cognito, Keycloak, or similar paths
• Add or refactor sessions, cookies, refresh-token strategy, OAuth providers, or passkeys
• Define app-owned users, profiles, orgs, memberships, and role boundaries around an auth provider
• Add organizations, invites, enterprise SSO, SCIM, or domain verification as the next milestone
• Untangle auth boundaries across frontend routes, middleware, backend APIs, and database policy layers
• Review whether the current auth stack is too vendor-coupled, too DIY, or too vague to scale safely

When not to use this skill

• The main job is authorization policy, permission inheritance, or ABAC/ReBAC modeling → treat it as a dedicated authorization design problem and route contract semantics to api-design
• The main job is cookie flags, CSRF, rate limiting, secret handling, abuse prevention, or general vulnerability hardening → use security-best-practices
• The main job is API contract/interface design before auth is slotted into the API honestly → use api-design
• The main job is developer-facing reference docs, quickstarts, or API auth docs for consumers → use api-documentation
• The main job is backend regression coverage, login/callback testing, or role-matrix test planning → use backend-testing
• The main job is deeper schema normalization/indexing rather than auth-owned tables and identity boundaries → use database-schema-design

Instructions

Step 1: Classify the auth job before naming vendors

Normalize the request first.

auth_setup_profile:
  app_type: saas | internal-tool | marketplace | consumer-app | api-only | mixed | unknown
  auth_lane: hosted | framework-native | platform-native | enterprise-add-on | self-hosted | unknown
  runtimes: browser | server | edge | mobile | api | mixed
  login_methods: password | magic-link | social-oauth | passkeys | sso | mixed | unknown
  identity_scope: single-user | teams-orgs | b2b-enterprise | mixed | unknown
  session_model: server-session | stateless-jwt | hybrid | unknown
  data_ownership: vendor-owned | app-owned | hybrid | unknown
  rollout_stage: greenfield | mvp | scale-up | migration | enterprise-expansion

Ask or infer: 1. What frameworks, runtimes, and deployment surfaces already exist? 2. Is the team optimizing for fastest safe launch, deeper control, enterprise support, or self-hosting? 3. Does the app only need sign-in, or also orgs, invites, roles, admin access, and customer SSO? 4. Which auth/data pieces are already fixed by the current stack?

Step 2: Choose the smallest credible auth lane

Use auth-decision-matrix.md instead of rebuilding the landscape from memory.

Default lane chooser:

• Hosted auth when speed, prebuilt UX, providers, MFA/passkeys, and polished onboarding matter most
• Framework-native auth when the team wants auth close to app code and app-owned data
• Platform-native auth when Supabase/Firebase/Appwrite-style platform choices are already fixed
• Enterprise add-on when the request includes SAML/OIDC SSO, SCIM, directory sync, or domain verification
• Self-hosted when sovereignty, air-gapped, OSS-only, or on-prem requirements dominate

Rules: 1. Recommend one primary lane and at most one fallback. 2. If the backend platform is already fixed, evaluate platform-native first. 3. If enterprise identity is mentioned, branch there explicitly instead of flattening it into consumer login. 4. If migration or cutover risk matters, pull in enterprise-and-migration-notes.md.

Step 3: Draw the provider/app ownership boundary

Before implementation, state who owns what.

Minimum boundary packet:

• Provider usually owns: sign-in methods, password reset/email verification, MFA/passkey ceremony, token/session issuance, enterprise federation entry points
• Application usually owns: local user/profile records, org/workspace membership, roles/entitlements, billing-linked access, admin/support exceptions, domain-specific authorization
• Shared edge: claims copied into tokens or sessions, webhook/user sync, callback URLs, middleware, cookie config, audit/event visibility

Use boundary-checklist.md to keep the skill from drifting into neighboring lanes.

Step 4: Choose the session and login model deliberately

Use session-and-deployment-notes.md for the detailed heuristics.

Quick defaults:

• Server sessions / signed cookies for browser-heavy apps, SSR, and middleware-friendly auth state
• Stateless JWTs for API-heavy and multi-service traffic where token verification is a first-class requirement
• Hybrid when browser sessions and API/machine tokens both matter

Always record:

• chosen login methods and why they are needed now
• token/session lifetime and refresh strategy
• logout/revocation expectations
• callback URL and cookie/domain behavior across local, preview, staging, and production
• edge/runtime constraints that may change helper availability

Step 5: Model app-owned auth data

Even hosted auth rarely removes the need for local tables.

Usually define at least:

• users or profiles
• organizations / workspaces if multi-tenant
• memberships / roles
• invitation, provisioning, or seat state if teams are invited/admin-managed

Record:

• the stable user identifier across provider and app DB
• which fields stay vendor-owned vs mirrored locally
• whether permissions live in claims, local tables, or both
• how webhook or sync failures are detected and repaired

If the request slides into broader schema design, route deeper modeling to database-schema-design.

Step 6: Branch enterprise or migration work explicitly

If the request includes SSO, SCIM, domain verification, existing-user linking, provider migration, or self-hosted cutover risk, use enterprise-and-migration-notes.md.

Name these items directly:

• whether this is an add-on vs replacement
• account-linking and org/domain mapping rules
• provisioning / deprovisioning behavior
• customer onboarding/support expectations
• rollback boundary if the rollout or migration goes wrong

Step 7: Produce an auth setup packet

The output should help the next implementation step succeed.

Preferred packet: 1. chosen auth lane and why 2. primary stack recommendation plus fallback 3. provider/app ownership boundary 4. session + login model 5. app-owned data model outline 6. environment checklist 7. adjacent route-outs 8. open risks or migration notes

Output format

Use this structure unless the user asks for another format:

# Authentication Setup Plan

## Auth lane
- chosen lane
- why it fits

## Recommended stack
- primary option
- fallback option
- tradeoffs

## Ownership boundary
- provider owns
- app owns
- shared edge / sync points

## Session + login model
- sessions vs JWT vs hybrid
- chosen login methods
- callback/cookie/runtime notes

## App-owned data model
- users/profiles
- orgs/memberships/roles
- sync strategy

## Environment + rollout checklist
- local
- preview/staging
- production
- migration notes

## Route-outs
- adjacent skills and why

Examples

Example 1: Next.js SaaS with product auth

Input:

Set up auth for a Next.js SaaS app with email login, Google OAuth, org roles, and an admin panel.

Expected handling:

• classify as browser/server mixed SaaS with teams/orgs
• compare hosted vs framework-native paths instead of jumping straight into JWT snippets
• define app-owned org/membership tables
• note SSR/middleware/cookie boundaries
• route security hardening and auth-flow testing to neighboring skills

Example 2: Supabase-first app

Input:

We already use Supabase. Decide what auth should live in Supabase vs our app DB, and how roles should work.

Expected handling:

• choose platform-native lane first
• keep provider identity separate from app-owned entitlements
• call out RLS/authz follow-through as an adjacent design/testing concern

Example 3: Enterprise expansion or migration

Input:

We already have login. Now add enterprise SSO and SCIM for B2B customers without rewriting our whole auth stack.

Expected handling:

• classify as enterprise add-on or migration-sensitive work, not basic consumer-login setup
• cover account linking, org/domain mapping, and provisioning boundaries
• avoid pretending SSO/SCIM is the same job as social login or password auth

Best practices

1. Start with the auth lane and ownership boundary, not code snippets. 2. Keep authentication setup separate from deeper authorization policy and general security hardening. 3. Assume most products still need app-owned user/org/membership tables even with hosted auth. 4. Treat enterprise SSO/SCIM and migrations as a distinct branch once B2B or cutover pressure appears. 5. Record environment-specific callback, cookie, and preview-deployment behavior early. 6. Prefer one clear primary recommendation with a fallback, not a giant vendor list. 7. Route adjacent work explicitly so authentication-setup stays reusable instead of becoming another backend catch-all.

References

• Next.js Authentication
• Auth.js
• Clerk Docs
• Supabase Auth Docs
• Keycloak Docs
• WorkOS Docs

Authentication Decision Matrix

Use this reference when the request says "set up auth" but the real decision is which auth lane fits the product.

Fast lane chooser

Common lane-to-tool map

Hosted auth

• Clerk
• Auth0
• Firebase Authentication
• Amazon Cognito

Best when:

• time to first working login matters most
• polished built-in UX is valuable
• you expect social login, MFA, or passkeys quickly

Tradeoffs:

• vendor coupling
• pricing cliffs
• app-specific authz still stays local

Framework-native auth

• Auth.js
• Better Auth
• Lucia
• Passport.js only for legacy compatibility

Best when:

• framework/runtime fit matters
• you want app-owned data and control
• you can tolerate more setup work

Tradeoffs:

• more assembly around email, adapters, sessions, and account linking
• more responsibility for production hardening and edge cases

Platform-native auth

• Supabase Auth
• Firebase Auth
• Appwrite Auth

Best when:

• backend platform is already fixed
• auth should stay near the same DB/platform primitives

Tradeoffs:

• architecture becomes more platform-shaped
• provider identity still does not eliminate app-owned authorization

Enterprise add-on

• WorkOS
• Auth0 enterprise features
• Okta / Entra integrations depending on customer environment

Best when:

• customers need SAML/OIDC SSO, SCIM, domain verification, or directory sync

Tradeoffs:

• support + rollout work per customer
• account mapping and provisioning logic increase quickly

Self-hosted

• Keycloak
• Authentik
• Zitadel / Ory-class options

Best when:

• sovereignty, on-prem, or OSS-only constraints dominate

Tradeoffs:

• operational load
• admin complexity
• backups/upgrades become part of the auth story

Selection rules

1. Start from the team's constraints, not your favorite vendor. 2. If the backend platform is already fixed, evaluate the platform-native path first. 3. If the product needs enterprise SSO/SCIM, branch there explicitly instead of stuffing it into the consumer-login path. 4. Prefer one primary recommendation and one fallback, not a giant list. 5. If the team is already deep in a hosted auth product, optimize the app-owned boundary instead of assuming a full migration is free.

Authentication Boundary Checklist

Use this checklist to keep authentication-setup from collapsing into neighboring skills.

Provider vs app ownership

Provider usually owns

• sign-in methods and credential ceremony
• password reset / email verification flows
• MFA / passkey registration UX
• token or session issuance
• enterprise federation endpoints when applicable

App usually owns

• profile and business-domain fields
• organizations / workspaces / memberships
• roles, entitlements, and support/admin exceptions
• billing-linked access
• product-specific authorization decisions

Shared edge

• webhook / user-sync pipelines
• claims copied into tokens or sessions
• callback URLs and redirect handling
• middleware / guards / server helpers
• audit/event visibility across systems

Route-outs

Smells that mean the skill is too broad

• The answer is mostly JWT code and no product decision framework.
• The answer treats authorization as identical to authentication.
• The answer recommends an auth vendor but never states what data stays app-owned.
• The answer mixes SSO/SCIM into the same checklist as social login with no separate branch.
• The answer drifts into OWASP/security checklist territory without routing to security-best-practices.
• The answer designs a full policy engine instead of a setup boundary.

Minimal boundary packet

A strong output should include all of these: 1. chosen auth lane 2. ownership boundary 3. session/token model 4. user/org/membership data outline 5. environment checklist 6. adjacent handoffs

Enterprise and Migration Notes

Use this reference when the request is no longer just "add login" and has become an enterprise identity rollout or an auth-stack migration.

Treat enterprise add-ons as a distinct branch

Enterprise auth work is usually about federation, provisioning, and customer-specific rollout coordination, not just enabling another provider button.

Common signals:

• SAML, OIDC enterprise SSO, Entra ID / Azure AD, Okta, Google Workspace, Ping, or customer-managed IdPs
• SCIM or directory sync
• domain verification, discovery, or enforced SSO
• admin onboarding and customer IT handoff
• customer-specific support or staged rollout requirements

Questions to answer before recommending the lane

1. Is this a new auth stack or an add-on to an existing login flow? 2. Which customer identity providers must be supported first? 3. Is provisioning manual, JIT, SCIM-driven, or mixed? 4. How do domains, organizations, and users map into the app? 5. What happens when a user already exists through email/password or social login? 6. What support path exists for failed SSO setup, bad mappings, or provisioning drift?

Common enterprise boundary packet

• Identity provider / enterprise layer owns: federation handshake, customer IdP metadata, directory sync protocol, admin onboarding flow
• Application owns: organization/workspace records, role/entitlement mapping, support overrides, billing-linked access, customer-visible fallback UX
• Shared edge: account linking, domain verification, SCIM ↔ local membership sync, auditability, offboarding/deprovisioning behavior

Migration patterns

A. Hosted/framework-native auth adding enterprise later

Usually keep the existing auth stack, then add:

• organization/domain mapping rules
• account-linking rules for existing users
• enterprise-only admin/onboarding path
• sync/reconciliation plan for provisioning events

B. Provider migration

Treat as an identity-data migration project, not a library swap. Record:

• canonical user identifier and how it survives the cutover
• session invalidation / re-auth expectations
• password/import constraints if moving credential systems
• callback/domain changes per environment
• rollback boundary if the cutover misbehaves

C. Self-hosted / sovereignty move

Expect more operational work:

• backup and upgrade policy
• realm/tenant configuration ownership
• secret rotation and signing-key handling
• admin/operator responsibility boundaries

Failure modes worth naming

• Existing accounts do not link cleanly to enterprise identities.
• SCIM creates users before the app has a matching org or seat model.
• Domain verification or redirect URLs drift between preview and production.
• Enterprise onboarding requires per-customer manual support that was never scoped.
• Migrations ignore session invalidation and create surprise lockouts.

Output reminder

If the request includes enterprise identity or migration pressure, the final plan should name: 1. whether this is an add-on vs replacement 2. account-linking strategy 3. org/domain mapping rules 4. provisioning / deprovisioning behavior 5. rollout and rollback notes

Session and Deployment Notes

This reference exists because auth bugs often come from environment drift, not from the login form itself.

What to record early

• local app URL(s)
• preview/staging URL(s)
• production URL(s)
• OAuth callback URLs per environment
• cookie domain / subdomain rules
• secure / sameSite / httpOnly expectations
• token/session lifetime and refresh rules
• logout / revocation behavior

Session-model heuristics

Browser-heavy product UI

Usually prefer:

• server sessions or signed cookies
• middleware/server-side access to auth state
• explicit note about subdomain and preview behavior

API-heavy or multi-service traffic

Usually prefer:

• short-lived access tokens
• refresh/session rotation story
• service-to-service and machine-token distinction

Hybrid products

Often need both:

• browser sessions for the product UI
• API or machine tokens for integrations, webhooks, or automation

Common deployment pitfalls

1. Callback URLs differ across local, preview, staging, and production. 2. Secure cookies break silently in misconfigured local proxies or preview domains. 3. Social-login provider dashboards lag behind domain changes. 4. Edge/runtime differences change what auth helpers can access. 5. Session refresh logic behaves differently in middleware, server rendering, and client navigation. 6. Logout/revocation is often under-specified until support incidents happen.

Output reminder

Every auth setup plan should include an environment section with:

• callback URL checklist
• cookie/domain checklist
• secret/config ownership
• rollout / migration / rollback notes