/setup-auth

name: setup-auth
description: >
  Use when the user asks to "set up authentication", "add login",
  "add logout", "add sign in", "enable auth", "add role-based access",
  "add authorization", "protect routes", "configure identity provider",
  "configure Entra ID", "configure Entra External ID",
  "configure OpenID Connect", "add OIDC", "set up SAML",
  "set up WS-Federation", "set up local login",
  "add Facebook login", "add Google sign in", "add Microsoft Account",
  or otherwise wants to set up
  authentication (login/logout) and role-based authorization for their
  Power Pages SPA site using any supported identity provider.
  Also sets up the IdP app registration for OIDC providers (Okta, Auth0,
  Entra External ID, and other OIDC) -- reads the provider's docs first, then
  either guides the user through the provider's console or, when the provider
  supports it, configures it for the user -- and wires
  the client ID, authority, and claims mapping into Power Pages.
user-invocable: true
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion, Task, TaskCreate, TaskUpdate, TaskList, Skill, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_search, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch
model: opus

> **Plugin check**: Run `node "${PLUGIN_ROOT}/scripts/check-version.js"` — if it outputs a message, show it to the user before proceeding.

Set Up Authentication & Authorization

Configure authentication (login/logout) and role-based authorization for a Power Pages SPA site. This skill supports multiple identity providers -- Microsoft Entra ID, Entra External ID (for customer-facing apps with self-service sign-up), OpenID Connect (Okta, Auth0, etc.), SAML2, WS-Federation, local authentication (username/password), Microsoft Account, Facebook, and Google. It also supports optional features including invitation-based registration and Terms & Conditions acceptance. Power Pages built-in 2FA is intentionally not scaffolded because the SendCode/VerifyCode pages are server-rendered and cannot be integrated into a SPA experience — use IdP-level MFA instead. It creates an auth service, type declarations, authorization utilities, auth UI components, and role-based access control patterns appropriate to the site's framework and chosen identity provider(s).

Core Principles

• **Client-side auth is UX only** — Power Pages authentication is server-side (session cookies). Client-side role checks control what users see, not what they can access. Server-side table permissions enforce actual security.
• **Framework-appropriate patterns** — Every auth artifact (hooks, composables, services, directives, guards) must match the detected framework's idioms and conventions.
• **Development parity** — Include mock data for local development so developers can test auth flows and role-based UI without deploying to Power Pages.
• **Preserve site integrity** — Before changing navigation, auth pages, dialogs, or role-based UI, read `${PLUGIN_ROOT}/references/site-modification-integrity.md`. Synchronize all visible auth states across configured locale resources and keep them bidirectional and expansion-safe.

**Initial request:** $ARGUMENTS

> **Prerequisites:** > > - An existing Power Pages SPA site created via `/create-site` > - The site must be deployed at least once (`.powerpages-site` folder must exist) > - Web roles must be created via `/create-webroles`

Workflow

1. **Phase 1: Check Prerequisites** — Verify site exists, detect framework, check web roles 2. **Phase 2: Plan** — Gather auth requirements (optionally set up the IDP app registration knowledge-first — Guided by default, or configure-for-you via the provider's own CLI where supported: Okta / Auth0 / Entra External ID) and present plan for approval 3. **Phase 3: Create Auth Service** — Auth service with login/logout and type declarations 4. **Phase 4: Create Authorization Utils** — Role-checking functions and wrapper components 5. **Phase 5: Create Auth UI** — Login/logout button integrated into navigation 6. **Phase 6: Implement Role-Based UI** — Apply role-based patterns to site components 7. **Phase 7: Verify Auth Setup** — Validate all auth files exist, build succeeds, auth UI renders 8. **Phase 8: Review & Deploy** — Summary and deployment prompt

---

Phase 1: Check Prerequisites

**Goal:** Confirm the project exists, identify the framework, verify deployment status and web roles, and check for existing auth code.

Actions

1.1 Locate Project

Look for `powerpages.config.json` in the current directory or immediate subdirectories:

**/powerpages.config.json

**If not found**: Tell the user to create a site first with `/create-site`.

1.2 Detect Framework

Read `package.json` to determine the framework (React, Vue, Angular, or Astro). See `${PLUGIN_ROOT}/references/framework-conventions.md` for the full framework detection mapping.

1.3 Check Deployment Status

Look for the `.powerpages-site` folder:

**/.powerpages-site

**If not found**: Tell the user the site must be deployed first:

> "The `.powerpages-site` folder was not found. The site needs to be deployed at least once before authentication can be configured."

<!-- gate: setup-auth:1.3.deploy-first | category=plan | cancel-leaves=nothing -->

> 🚦 **Gate (plan · setup-auth:1.3.deploy-first):** `.powerpages-site` missing — auth setup writes site settings inside that folder. Deploy first or stop. > > **Trigger:** Phase 1.3 detected no `.powerpages-site` folder. > **Why we ask:** Auto-deploy picks the wrong env; skipping leaves auth wiring broken. > **Cancel leaves:** Nothing — no auth files written yet.

Use `AskUserQuestion`:

| Question | Options | |----------|---------| | Your site needs to be deployed first. Would you like to deploy now? | Yes, deploy now (Recommended), No, I'll do it later |

**If "Yes, deploy now"**: Invoke `/deploy-site`, then resume.

**If "No"**: Stop — the site must b