---

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 code 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 code 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.

Initial request: $ARGUMENTS

Prerequisites:

• An existing Power Pages code 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 be deployed first.

1.4 Check Web Roles

Look for web role YAML files in .powerpages-site/web-roles/:

**/.powerpages-site/web-roles/*.yml

Read each file and compile a list of existing web roles (name, id, flags).

<!-- gate: setup-auth:1.4.create-webroles | category=plan | cancel-leaves=nothing -->

🚦 Gate (plan · setup-auth:1.4.create-webroles): No web roles found — role-based authorization needs at least one role. Create roles first or skip and add later.

Trigger: Phase 1.4 found no YAML files in .powerpages-site/web-roles/. Why we ask: Auto-invoking /create-webroles runs another full skill; auto-skipping leaves RBAC checks against an empty role set. Cancel leaves: Nothing — no auth files written yet.

If no web roles exist: Warn the user that web roles are needed for authorization. Ask via AskUserQuestion whether to create them first:

| Question | Options | |----------|---------| | No web roles were found. Web roles are required for role-based authorization. Would you like to create them now? | Yes, create web roles first (Recommended), Skip — I'll add roles later |

If "Yes": Invoke /create-webroles, then resume.

If "Skip": Continue — auth service and login/logout will still work, but role-based authorization will need roles created later.

1.5 Discover Existing Auth Configuration

Always run this discovery step, even on a first invocation — the site may have site settings from a prior run, or from hand-editing the YAML files, even if no SPA auth code exists yet. The goal is to make sure we never silently drop a provider that's already configured server-side.

Step 1 — Scan .powerpages-site/site-settings/ for already-configured providers.

Detect existing providers by matching site-setting filenames against these patterns:

| Pattern | Maps to provider type | |---|---| | Authentication-OpenIdConnect-{Name}-AuthenticationType.sitesetting.yml | OIDC (Entra External ID, Okta, Auth0, generic OIDC, B2C — all share the OIDC path) | | Authentication-SAML2-{Name}-AuthenticationType.sitesetting.yml | SAML2 | | Authentication-WsFederation-{Name}-AuthenticationType.sitesetting.yml | WS-Federation | | Authentication-OpenAuth-{Microsoft\|Facebook\|Google}-{ClientId\|AppId}.sitesetting.yml | Social OAuth | | Authentication-Registration-LocalLoginEnabled.sitesetting.yml with value true | Local Authentication |

For each detected provider, read its full set of .sitesetting.yml files to extract: Authority / MetadataAddress, ClientId / AppId, AuthenticationType (the providerIdentifier), Caption or display name (if present), and the {Name} slug used in the keys (e.g., OpenIdConnect_1, EntraExternalId).

Distinguishing Entra ID variants from OIDC — by Authority URL pattern:

| Authority pattern | Provider type | Notes | |---|---|---| | https://login.windows.net/{guid}/ (no /v2.0/) — site's parent tenant | Microsoft Entra ID (workforce) — type: 'entra-id' | Auto-populated by Power Pages on site creation. The {Name} slug is usually AzureAD. Set providerIdentifier to undefined in AUTH_PROVIDERS — runtime resolver derives it from Portal.tenant. | | https://{subdomain}.ciamlogin.com/{tenantId} (no trailing /v2.0/) | Entra External ID — type: 'oidc' | Customer tenant. Must include explicit providerIdentifier matching the Authority. | | https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/v2.0/{policy} | Azure AD B2C (legacy) — type: 'oidc' | Older B2C product. Must include explicit providerIdentifier. | | Any other OIDC authority (Okta, Auth0, etc.) | OIDC — type: 'oidc' | Must include explicit providerIdentifier. |

The Entra ID (workforce) case is special — when Phase 1.5 discovery detects Authentication/OpenIdConnect/AzureAD/* settings on the site (which Power Pages auto-creates for the parent tenant), add a single entry to EXISTING_PROVIDERS:

{
  id: 'entra-id',
  type: 'entra-id',
  displayName: existingCaption || 'Sign in with Microsoft',
  // NO providerIdentifier — resolveProviderIdentifier() derives it from Portal.tenant
}

Do NOT extract the tenant ID from the existing Authority site setting just to hardcode it back into AUTH_PROVIDERS — the runtime resolver handles it. This keeps the SPA code portable if the site is ever cloned to a different tenant.

Step 2 — Scan for existing SPA auth code.

Check for these files and read their key markers:

• src/services/authService.ts or .js — look for AUTH_PROVIDERS array (current pattern) vs single AUTH_PROVIDER constant (legacy)
• src/types/powerPages.d.ts — exists or not
• src/utils/authorization.ts — exists or not
• Auth components (AuthButton.*, Login.*, Registration.*, RedeemInvitation.*, etc.) — list which exist
• src/pages/Login.tsx — extract which providers it currently renders (via AUTH_PROVIDERS import or inline)

Step 3 — Present findings to the user.

If providers were detected from site settings, present them with their config:

I found these existing auth providers on your site:

  ✓ Entra External ID
    - ProviderName: OpenIdConnect_1
    - Tenant: ba275000-98c8-404d-a6f0-c5450f2aa668
    - ClientId: e728d63e-1190-495a-ae29-663e9cc10877
    - Configured in site settings: yes
    - Surfaced in SPA UI: NO (authService.ts has no entry for this provider)

  ✓ Local Authentication
    - LoginByEmail: true
    - Surfaced in SPA UI: yes

Use AskUserQuestion:

| Question | Header | Options | |----------|--------|---------| | I found existing auth providers on your site. What would you like to do? | Existing auth | Keep all existing providers and add a new one (Recommended) — preserves what's there, adds what you ask for next, Keep all existing providers (no new provider this run) — re-generates SPA code to surface what's already in site settings, Replace everything with a new configuration — wipes existing site settings and SPA code, starts fresh |

"Keep all existing providers and add a new one" (default path):

• Store the discovered providers as EXISTING_PROVIDERS — these will be merged into the AUTH_PROVIDERS array generated in Phase 3.2
• Phase 2.1 will prompt for the NEW pr