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 (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:

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 (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:

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:

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:

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:

"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 provider being added; the existing ones are kept untouched
• For local auth specifically — if Local Authentication is in EXISTING_PROVIDERS, always regenerate the local auth SPA code (login flow, registration page, forgot/reset password, redeem invitation) from the user's Phase 2.1 answers. Don't try to preserve hand-edited local-auth code — the local flows are complex enough that partial updates introduce more bugs than they avoid.

"Keep all existing providers (no new provider this run)":

• Skip the Phase 2.1 provider selection question entirely
• Re-derive AUTH_PROVIDERS from EXISTING_PROVIDERS only
• Useful for: fixing a site where the SPA UI is missing a provider that's already in site settings (the exact bug this branch was created to fix)

"Replace everything with a new configuration":

• Set EXISTING_PROVIDERS = []
• Delete existing OIDC/SAML2/WsFed/OpenAuth site-setting YAMLs as part of Phase 8.1
• Run Phase 2.1 as if no providers existed

DO NOT offer a "skip / no changes" option. If the user invokes setup-auth, they want auth set up — silently doing nothing is worse than asking.

Output

• Project root path confirmed
• Framework identified (React, Vue, Angular, or Astro)
• Deployment status verified
• Web roles inventory compiled
• EXISTING_PROVIDERS list compiled from site settings, with provider type, ProviderName slug, ClientId/Authority/etc. for each
• MERGE_MODE chosen: keep-and-add (default) | keep-only | replace-all
• SPA auth file inventory recorded (which files exist, whether they use AUTH_PROVIDERS array or legacy single-provider pattern)

Phase 2: Plan

Goal: Gather authentication requirements from the user and present the implementation plan for approval.

Actions

2.0 Smart Auth Inference (Before Asking)

Before asking the user which providers they want, analyze the site context from Phase 1 (site name, purpose, audience type) and try to infer appropriate auth settings automatically:

Inference rules:

If you can infer with confidence, present the recommendation with rationale:

"Based on your site purpose ({purpose}), I recommend:

• {provider} for authentication
• {registration mode} because {rationale}

Would you like to proceed with this configuration, or choose different providers?"

If "Yes": Skip Phase 2.1 provider selection and proceed directly to collecting provider-specific details (ClientId, tenant name, etc.) for the recommended provider(s).

If "No" or if you cannot infer with confidence: Fall back to Phase 2.1 below.

2.1 Gather Requirements

🚦 Gate (plan · setup-auth:2.1.requirements): Pick which auth features to build (login+logout / RBAC / both). Covers the conditional follow-up "which roles get access" sub-prompt in the same step.

Trigger: Phase 2.1 entry. Why we ask: Wrong feature set gets generated — e.g. building RBAC files when the user only wanted login. Cancel leaves: Nothing — no auth files written yet.

Re-run handling — when Phase 1.5 detected existing providers:

The behavior depends on the MERGE_MODE chosen in Phase 1.5:

• keep-only (user chose "keep all existing, no new provider this run") → Skip the new-provider selection question entirely. Proceed to the "Local Authentication" follow-ups only if local was detected. Phase 3.2 will generate AUTH_PROVIDERS from EXISTING_PROVIDERS only.
• keep-and-add (default — user wants to add one more) → Ask the user what to add. The provider selection question below should still be multi-select (the user could be adding multiple new providers in one go), but the existing providers are NOT in the list (they're already configured — the question is asking what's new). Common patterns:
  • User has Entra External ID, wants to add Local Auth → user selects "Local Authentication" → ask local follow-ups → Phase 3.2 merges
  • User has Entra External ID + Local, wants to add a second Entra External ID tenant → user selects "Entra External ID" → after collecting Authority/ClientId, ask: "You already have an Entra External ID provider configured for tenant {existing-tenant}. This new one is a separate instance — give it a distinct ProviderName slug (used in site setting keys like Authentication/OpenIdConnect/{ProviderName}/* and in code as the provider id)." Let the user pick a slug (default to the next incrementing number, e.g., OpenIdConnect_2) or pick a custom name (e.g., EntraExternalId_Employee).
• replace-all (user chose to wipe everything) → Run the provider selection question as on a first invocation.

Do NOT proactively ask "do you want to configure multiple instances?" at the start. Walk the user through configuring ONE provider at a time. When they finish configuring one and want another, they can re-run setup-auth → Phase 1.5 detects what's there → Phase 2.1 in keep-and-add mode asks "what do you want to add now?". This keeps the question count low for the common case (configure one provider) while still supporting the advanced case (multiple tenants).

IMPORTANT: Multiple providers are supported. The user may want more than one identity provider (e.g., Entra External ID + Google). If the user's initial prompt mentions specific providers, skip the provider selection question and proceed directly to collecting details for each mentioned provider.

IMPORTANT — Local Authentication: NEVER set up local authentication by default. Do NOT include it in the provider selection list, do NOT recommend it in smart inference, and do NOT configure it unless the user explicitly and specifically asks for it (e.g., "I want username/password login", "set up local login", "add local auth"). External identity providers (Entra External ID, Entra ID, OIDC, etc.) are always preferred. If the user says something ambiguous like "add login", default to an external provider — never to local auth.

If the user has NOT specified which provider(s) they want, use AskUserQuestion to determine the identity provider(s). This is a multi-select question — the user can choose one or more:

Then, for EACH selected provider, ask the mandatory follow-up questions below. Do not skip any provider — every selected provider needs its configuration collected before proceeding.

For each provider, also share the relevant Microsoft Learn documentation link so the user knows where to get the values:

For "Microsoft Account":

Docs: https://learn.microsoft.com/en-us/power-pages/security/authentication/openid-settings

For "Facebook":

Docs: https://learn.microsoft.com/en-us/power-pages/security/authentication/facebook-settings

For "Google":

Docs: https://learn.microsoft.com/en-us/power-pages/security/authentication/oauth2-google

For "OpenID Connect" (Okta, Auth0, etc.):

First, identify the specific OIDC provider — setup steps and the docs to read differ per vendor:

Use the answer as {provider} in the questions below and for Phase 2.1.2 Step A (reading the provider's docs). For Other, capture the provider's name from the user.

Orient the user first — don't jump straight to inputs. Now that they've picked {provider}, set expectations: you'll set up an app registration at {provider} for this site. The first thing you'll do is read {provider}'s own documentation — how it's set up depends on the provider. Then, depending on what {provider} supports, you'll either walk the user through the steps in the {provider} console, or — when {provider} supports it — configure it for the user. Either way you derive the metadata, Redirect URI, and claims automatically, and the app uses the no-secret code id_token flow — no client secret to manage.

Ask for the {provider} tenant — the sign-in domain (Okta: your-tenant.okta.com, Auth0: your-tenant.us.auth0.com):

If the user answered "Yes — I already have one", ask for the existing Client ID and Metadata Address now (Phase 8.1 needs them) and skip the Phase 2.1.2 app-registration setup. Otherwise the Client ID is not asked upfront — it comes from Phase 2.1.2, where you set up the app (guided, or configured for the user when the provider supports it) and derive the metadata from the provider's discovery document.

Docs: https://learn.microsoft.com/en-us/power-pages/security/authentication/openid-settings

For "Entra External ID" — use the 4-step walkthrough below. Do NOT just ask the user for Authority/ClientId/Metadata upfront — those values come from a tenant + app registration + user flow that the user may not have set up yet. Walk them through each prerequisite before asking for the corresponding value.

Reference doc: https://learn.microsoft.com/en-us/power-pages/security/authentication/entra-external-id See also ${PLUGIN_ROOT}/skills/setup-auth/references/authentication-reference.md for the full Entra External ID prerequisites section the steps below cross-reference.

Pre-computed values for THIS site — before starting the walkthrough, compute:

• SITE_URL = the deployed site URL (e.g., https://site-597pv.powerappsportals.com). Read from pac env who + the site name, or from the site's existing settings.
• PROVIDER_NAME = if this is a fresh add, default to OpenIdConnect_1 (or the next free OpenIdConnect_N slug per the CallbackPath uniqueness logic in Phase 8.1). The user can override to a custom slug like EntraExternalId_Customer for multi-instance setups.
• REDIRECT_URI = {SITE_URL}/signin-{PROVIDER_NAME-lowercased} — e.g., https://site-597pv.powerappsportals.com/signin-openidconnect_1. The user pastes this verbatim into the Entra app registration.
• APP_NAME_SUGGESTION = power-pages-{site-shortname} — e.g., power-pages-savoria
• USER_FLOW_NAME_SUGGESTION = {site-shortname}-signupsignin — e.g., savoria-signupsignin

Display these to the user before Step 1 so they have them handy.

Step 1 — Tenant

If "No", show:

Steps to create an Entra External ID tenant:

1. Open https://entra.microsoft.com/
2. Sign in with the account that should own the tenant
3. From the top, click Manage tenants → Create
4. Choose External (for customers) — NOT Workforce
5. Pick a domain prefix (the tenant subdomain) — e.g., contoso becomes contoso.ciamlogin.com. This appears in every login URL.
6. Free 30-day trial: no credit card required. You can attach a paid Azure subscription later.

Detailed guide: https://learn.microsoft.com/en-us/entra/external-id/customers/quickstart-tenant-setup

When you've created the tenant, switch to it (top-right tenant picker in entra.microsoft.com), then come back here.

If "I'm not sure", show: "At https://entra.microsoft.com/ → top-right tenant picker. Tenants for customers are labeled External. Workforce tenants won't work — that's a different product."

Then collect the tenant identifiers:

Validate: subdomain matches ^[a-z0-9-]+$ (no dots, no uppercase, no .ciamlogin.com suffix); tenant ID matches the UUID regex. If either fails, show the expected format and re-prompt.

Store as EXTERNAL_ID_TENANT_SUBDOMAIN and EXTERNAL_ID_TENANT_ID.

Step 2 — App registration

Confirm the Redirect URI first. The skill pre-computes a default based on the site URL and PROVIDER_NAME, but the user may prefer a different URI:

The Power Pages site needs a Redirect URI registered in your app registration. Based on the site URL and provider name, the default is:

{REDIRECT_URI}

You can keep this default, or use a different URI — for example, {SITE_URL}/signin-entra-customer or {SITE_URL}/auth/external-id. The host must be your Power Pages site; only the path can change.

If "Use a different URI", ask:

Validate the custom URI:

• Must start with {SITE_URL}/
• Path portion must match ^/[a-zA-Z0-9_\-/]+$ (alphanumeric, hyphen, underscore, additional slashes allowed)
• Path must NOT collide with any Authentication/OpenIdConnect/*/CallbackPath already in .powerpages-site/site-settings/ (from Phase 1.5 discovery)
• Path must NOT be a reserved Power Pages server path (/Account/..., /SignIn, /Register, /_layout/..., /api/...)

Re-prompt on invalid input. Then store the value as REDIRECT_URI for the rest of the walkthrough and Phase 8.1.

Note: The skill writes two site settings derived from this single REDIRECT_URI: the user-facing RedirectUri (the full URI, sent to the IdP) and the internal CallbackPath (just the path portion, used by the OWIN middleware to know which incoming request to handle). The maker doesn't need to think about CallbackPath separately — the skill derives it automatically from REDIRECT_URI by extracting the path portion.

If "No", show step-by-step with the confirmed Redirect URI verbatim:

Steps to register the app:

1. At https://entra.microsoft.com/, make sure you're in your External ID tenant (top-right picker)

2. Applications → App registrations → New registration

3. Name: {APP_NAME_SUGGESTION} (or your own name)

4. Supported account types: select Accounts in this organizational directory only (single tenant) — recommended for Power Pages. Multi-tenant configurations forcibly disable contact mapping by email for security.

5. Redirect URI: select Web, paste exactly:

   {REDIRECT_URI}
   

   Copy

   (Copy this verbatim. Any mismatch between this value and the RedirectUri site setting causes sign-in to fail with AADSTS50011: The reply URL specified in the request does not match.)

6. Click Register

7. Open the Authentication tab → under "Implicit grant and hybrid flows" check Access tokens AND ID tokens → Save

8. Open the API permissions tab → click Grant admin consent for {your tenant} → confirm

9. Go back to the Overview tab and copy the Application (client) ID (it's a GUID)

Detailed guide: https://learn.microsoft.com/en-us/entra/external-id/customers/quickstart-register-app

If "Yes" (existing app), before asking for the Client ID, also confirm the user has the matching Redirect URI registered:

Before continuing, please verify that your existing app registration has the following Redirect URI registered (under Authentication → Web in the Entra admin center):

{REDIRECT_URI}

If it's missing or different, add it now. An app registration can have multiple Web Redirect URIs registered — adding ours doesn't break any existing integrations. Sign-in will fail if the value in Power Pages doesn't match a registered URI exactly.

Then ask for the value:

Validate: must match UUID v4 format (^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$). Re-prompt on mismatch.

Store as EXTERNAL_ID_CLIENT_ID.

Do NOT ask about client secret. Entra External ID app registrations are public clients using PKCE — no secret needed. The skill will create site settings without ClientSecret and skip Phase 8.1.1 (Key Vault) for this provider. If the user has a confidential-client scenario that requires a secret, they can add it manually via the Power Pages admin center after deploy — document this as an advanced override in Phase 8.5 post-deploy notes.

Step 3 — User flow

User flows define what attributes are collected from users and what claims appear in the ID token. Without one, sign-in fails after the IdP redirect.

If "No", the walkthrough's user-flow-attribute selection must match the PROFILE_MAPPING_CHOICE collected later (Track B's profile mapping question). Since this step runs BEFORE that question, ask it now (just for Entra External ID):

The user flow needs to be told which attributes to collect from users and which claims to return in the token. The skill maps claims → Dataverse contact fields automatically — the attributes you select here determine what's available.

Store as PROFILE_ATTRIBUTES_CHOICE (this also drives PROFILE_MAPPING_CHOICE in Track B — they should be consistent; default both to "Standard" unless the user explicitly differs).

Then show:

Steps to create the user flow:

1. At https://entra.microsoft.com/, in your External ID tenant
2. External Identities → User flows → New user flow
3. Name: {USER_FLOW_NAME_SUGGESTION} (or your own — letters, digits, hyphens, underscores only)
4. Identity providers for sign-in: choose Email with password (Recommended — most familiar to customers) or Email one-time passcode (passwordless)
5. User attributes to collect (the sign-up form fields): based on your choice above, select:
   • Standard / Standard + phone: ☑ Email Address, ☑ Given Name, ☑ Surname{, ☑ Phone Number if Standard + phone}
   • Email only: ☑ Email Address
6. User attributes to return as claims (in the ID token): same selections as above — these power profile mapping into Dataverse contact fields
7. Click Create
8. Open the user flow you just created → Applications tab → Add application → select the app you registered in Step 2 → Select

Detailed guide: https://learn.microsoft.com/en-us/entra/external-id/customers/how-to-user-flow-sign-up-sign-in-customers

Then ask:

Validate: matches ^[a-zA-Z0-9_-]+$ (letters, digits, hyphens, underscores). Re-prompt on mismatch.

Store as EXTERNAL_ID_USER_FLOW.

Step 4 — Display name + Confirmation

Display name length guidance: keep labels around 28 characters or less to display on a single line in the horizontal-row Login page layout (which is the default). Longer labels still work — buttons grow vertically to wrap text to two lines — but single-line buttons look more polished. For reference:

• "Sign in with Entra External ID" — 30 chars (wraps on narrow cards, fits on wider)
• "Sign in with Microsoft Entra External ID" — 40 chars (wraps to two lines in the default horizontal layout)
• "Customer Sign In" — 16 chars (always single line, but less descriptive)

If the user has multiple external providers configured (e.g., Entra External ID + Google), shorter labels matter more because each button gets less width. For a single-provider site, longer labels are fine (the button spans the full row width).

Store as EXTERNAL_ID_DISPLAY_NAME.

Now derive the configuration and present a summary for confirmation:

• Authority: https://{EXTERNAL_ID_TENANT_SUBDOMAIN}.ciamlogin.com/{EXTERNAL_ID_TENANT_ID} (NO trailing /v2.0/ — Entra External ID uses the bare tenant path, NOT the B2C-style URL)
• MetadataAddress: https://{EXTERNAL_ID_TENANT_SUBDOMAIN}.ciamlogin.com/{EXTERNAL_ID_TENANT_ID}/v2.0/.well-known/openid-configuration
• AuthenticationType (provider identifier in AUTH_PROVIDERS array and ExternalLogin POST): same value as Authority
• RedirectUri: {REDIRECT_URI} (computed earlier)
• ClientId: {EXTERNAL_ID_CLIENT_ID}

Present this summary inline:

About to configure:

Field	Value
Provider	Microsoft Entra External ID
Tenant	{subdomain}.ciamlogin.com ({tenantId})
App (Client) ID	{clientId}
User flow	{userFlowName}
Redirect URI	{REDIRECT_URI} (must already be registered in your app)
Authority	{authority} (derived)
Metadata	{metadataAddress} (derived)
Display name	{displayName}
Login button	"{displayName}"
Client secret	None (public client / PKCE)

Continue to write these site settings?

If "No", re-prompt for the specific value the user wants to change.

Implementation note: Power Pages server treats Entra External ID as a generic OpenID Connect provider (no special CIAM handling). All settings go under Authentication/OpenIdConnect/{ProviderName}/. The provider value posted to /Account/Login/ExternalLogin must match the AuthenticationType site setting, which by default equals the authority URL.

For "SAML2":

Docs: https://learn.microsoft.com/en-us/power-pages/security/authentication/saml2-settings Login.gov (US government SAML IdP) — get its metadata endpoint from the SAML developer guide: https://developers.login.gov/saml/getting-started/

For "WS-Federation":

Docs: https://learn.microsoft.com/en-us/power-pages/security/authentication/ws-federation-settings

Profile mapping (for every external provider — OIDC, Entra External ID, SAML2, WS-Federation, social)

After collecting the provider's basic details, ask what user profile info should flow from the IdP to the Dataverse contact. Don't skip this — without it, contact records have empty firstname/lastname and the SPA falls back to displaying the email or username everywhere.

Store as PROFILE_MAPPING_CHOICE. Then ask:

Store as PROFILE_SYNC_FREQUENCY. This determines whether to write LoginClaimsMapping (every login) in addition to RegistrationClaimsMapping (first sign-in only).

Why "First sign-in only" is now the default: this skill optionally scaffolds a SPA profile page (/user-profile) where signed-in users can edit their own contact info. If LoginClaimsMapping is set, the server overwrites the user's edits with IdP claims on the very next login — which is confusing and silently undoes the user's work. "First sign-in only" lets the user own their profile after the contact is created. Switch to "Both" only when the IdP is the sole authoritative source for these fields (e.g., HR-managed workforce directory) and end-user edits should NOT persist.

Claim type values — the mapping format is comma-separated contactfield=claimtype (NOT JSON). For OIDC providers like Entra External ID, use OIDC short names:

For SAML2 / WS-Federation, the claim types are URIs (e.g., http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname). Adjust the "Standard" generated mapping accordingly. For social providers, the claim types are provider-specific (Google: given_name, Facebook: name).

Contact linking (for every external provider)

Ask whether to auto-link external sign-ins to existing contacts by email.

Store as CONTACT_LINKING_CHOICE. This drives AllowContactMappingWithEmail (true for "link", false for "create new").

Why "Link to the existing contact" is the default: the common flow is that admins pre-create contact records in Dataverse (often via invitation or import) and then expect those exact contacts to be picked up when the user signs in for the first time via the configured IdP. Without linking, the server creates a brand-new contact and the pre-created record sits orphaned — confusing for users and easy to misdiagnose. Linking by verified email is the well-known pattern for joining IdP identity to an existing CRM record.

⚠ Auto-link is for migration / pre-provisioned contacts: turn linking on when contacts already exist in Dataverse (data migration, admin import, invitations) and must be matched by email. On a greenfield site with no pre-existing contacts, normal first-sign-in contact creation works the same — linking simply has nothing to match.

⚠ Multi-tenant safety: For multi-tenant Entra External ID (Authority uses /organizations/ or /common/, or IssuerFilter is a wildcard), the Power Pages server forcibly disables AllowContactMappingWithEmail regardless of the site setting (BlockContactMappingSettingForMultitenantApp feature flag in LoginController.cs:2578-2587). Reason: email claims can't be trusted across tenants. If the user selects "Link to the existing contact" but the Authority is multi-tenant, warn them that linking won't work and recommend single-tenant Authority.

⚠ Security: When AllowContactMappingWithEmail = true, an attacker who can sign into the configured IdP using a victim's email can take over the victim's contact. Enable only when the IdP verifies emails (Entra External ID with single tenant verifies; arbitrary OIDC may not). Switch to "Create a new contact" if you're configuring an IdP whose email-verification stance you don't control (e.g., a generic OIDC endpoint).

For "Local Authentication" (only if user explicitly requested it): Ask the user how they want users to identify themselves when logging in:

This choice determines the Authentication/Registration/LocalLoginByEmail site setting (true for email, false for username) and affects every form field in the login, registration, and auth service code. When email is chosen, the login and registration forms show an Email field (type email). When username is chosen, the forms show a Username field (type text) and Email becomes a separate required field on the registration form (the server needs it for the contact record). Store this choice — it will be used in Phase 3 (auth service), Phase 5 (sign-in and registration pages), and Phase 8.1 (site settings).

For "Local Authentication" — also ask which registration mode the site should use:

Why this matters — the server enforces the following gating rules in RegistrationManager (see crm.solutions.portal/Samples/MasterPortal/Areas/Account/Models/RegistrationManager.cs):

Note: The Authentication/Registration/RequireInvitationCode setting is NOT a real server setting — the server doesn't read it. The "require invitation" behavior is enforced solely by OpenRegistrationEnabled = false + InvitationEnabled = true. Do not create that setting.

Store this choice as REGISTRATION_MODE — it drives:

• Whether to create the /registration page (always, unless Registration disabled)
• Whether to create the /redeem-invitation page (only when InvitationEnabled is true, i.e., Invitation-only or Both)
• Whether the /registration page calls fetchInvitationDetails() to pre-fill the email (only when InvitationEnabled is true)
• The deterministic set of site settings written in Phase 8.1
• Whether to default CAPTCHA on (open / both) or off (invitation-only — invitations already filter users)

For "Microsoft Entra ID" (workforce / employee tenant): No tenant or client info needed. Power Pages auto-configures the OIDC site settings (Authentication/OpenIdConnect/AzureAD/*) for the site's parent tenant when the site is created. The SPA derives the providerIdentifier (https://login.windows.net/{tenantId}/) at runtime from window.Microsoft.Dynamic365.Portal.tenant — no hardcoded values.

Claims mapping is also auto-configured silently — Phase 8.1 always writes Authentication/OpenIdConnect/AzureAD/RegistrationClaimsMapping and LoginClaimsMapping with the value firstname=given_name,lastname=family_name,emailaddress1=upn for the workforce Entra provider. No question is asked for this — the answer is deterministic. Workforce Entra ID issues v1.0 tokens by default (issuer sts.windows.net/{tid}/) which omit the email claim, so upn is the only reliable claim to populate emailaddress1. Without this mapping, contacts created on first sign-in have oid linked but firstname/lastname/email all empty (the User object renders with contactId but blank profile fields).

Only ask one optional question — the button display name. Provide a sensible default the user can accept:

Store as ENTRA_ID_DISPLAY_NAME (default "Sign in with Microsoft"). Phase 3.2 adds an entry to AUTH_PROVIDERS with type: 'entra-id', this display name, and no providerIdentifier (runtime-resolved).

Why no tenant ID? The tenant ID is essentially for SPA-button wiring (the value the SPA POSTs to /Account/Login/ExternalLogin). Power Pages exposes the site's parent tenant ID at runtime via window.Microsoft.Dynamic365.Portal.tenant, so the SPA can construct the providerIdentifier (https://login.windows.net/{tenantId}/) without asking the user. The server-side OIDC settings are already in place from site creation. Compare this to Entra External ID, where the tenant is a SEPARATE customer tenant unrelated to the site's parent — there we DO need the user to provide the tenant ID + subdomain because they can't be derived from Portal.tenant.

Docs: https://learn.microsoft.com/en-us/power-pages/security/authentication/openid-settings

Login page layout — when more than one auth provider is configured (including local + 1 external, or 2+ providers), the Login page renders all of them. Ask the user how they want providers laid out:

Store this choice as LOGIN_LAYOUT — Phase 5.1.1 renders the Login page based on it. If only one provider is configured (e.g., Entra External ID only with no local), LOGIN_LAYOUT is moot: the AuthButton's "Sign In" calls login() directly, no Login page is needed.

For the Primary spotlight layout, ask a follow-up:

Store as PRIMARY_PROVIDER_ID.

Then determine the scope:

Then ask about optional features:

Note: If they select Terms and Conditions, follow the Terms flow below.

Invitation-based registration is NOT in this list — it's controlled by the registration mode question above. Setting registration mode to Invitation-only or Both is what enables invitations.

Two-factor authentication (2FA) is intentionally NOT offered. Power Pages' built-in 2FA flow is server-rendered (/Account/Login/SendCode → /Account/Login/VerifyCode) and cannot be intercepted from the SPA — there's no SPA-equivalent UI for the code entry step, and bouncing the user out to a server page mid-login breaks the SPA experience. If the user explicitly asks for 2FA, tell them: "Power Pages built-in 2FA requires the legacy server-rendered SendCode/VerifyCode pages, which we don't support in SPA-based SPA sites yet. For external providers (Entra ID, Entra External ID, OIDC), enable MFA at the identity provider instead — it's transparent to Power Pages and stays inside the IdP's branded experience. For local accounts, 2FA on SPA sites is not currently supported." Do NOT create TwoFactorEnabled, RememberMeEnabled, or RememberBrowserEnabled site settings.

Profile page — ask whether to scaffold a SPA profile page that lets signed-in users edit their own contact info via the Power Pages Web API. This is a standalone question because it has its own infrastructure implications (Web API site settings on the contact entity + Self-scope table permission).

Store as INCLUDE_PROFILE_PAGE (boolean). Default false.

⚠ MANDATORY route name: /user-profile (NOT /profile). The path /profile is reserved by the Power Pages server for the legacy server-rendered profile page — using it as a SPA route creates a conflict that breaks the page. Always use /user-profile for the SPA route. The skill executor MUST NOT rename this route. Same for the file: src/pages/UserProfile.tsx (NOT Profile.tsx).

When true, Phase 5.1.9 generates src/pages/UserProfile.tsx (file name mandatory), extends authService.ts with getMyProfile / updateMyProfile (function names mandatory), evolves the AuthButton from inline [Avatar Name Sign Out] to a dropdown menu with "My Profile" and "Sign Out", and adds the /user-profile route (path mandatory) to App.tsx. Phase 8.1 writes the Web API site settings (Webapi/contact/enabled = true and Webapi/contact/fields with the COMPLETE default field list documented in Phase 8.1 — not a subset) and a Self-scope table permission on contact for the Authenticated Users role. The dropdown shape becomes the new default for AuthButton regardless of INCLUDE_PROFILE_PAGE so the component is ready for future menu items.

Profile page design — intentionally simple:

The page has two sections:

1. Account Details (read-only display at the top) — shows just the user's full name (firstname + lastname combined) and email. DO NOT display contactId, roles, sign-in method, provider name, last-login timestamp, or any other account metadata. Keep this section minimal.
2. Edit form (below) — only these editable fields. Email is intentionally NOT editable (changing email via Web API conflicts with auth provider claim mapping behavior and is surprising for external-auth users).

Default EDITABLE field set (the form MUST include exactly these 8 fields — do not add email, do not add middlename, do not add a Change Password link):

• First name (firstname)
• Last name (lastname)
• Mobile phone (mobilephone)
• Address line 1 (address1_line1)
• City (address1_city)
• State / Province (address1_stateorprovince)
• Postal code (address1_postalcode)
• Country (address1_country)

All fields are optional on submit. DO NOT include:

• ❌ emailaddress1 as an editable field (read-only in Account Details only)
• ❌ middlename (keep the form simple)
• ❌ A "Change password" link or button (password reset is handled by the existing /forgot-password flow, not the profile page)
• ❌ A "Sign out" button on the profile page (sign-out lives in the header AuthButton dropdown only)
• ❌ Display of contactId, userRoles, or any account metadata beyond name + email

The Web API fields site setting MUST include contactid plus the 8 editable fields above (9 total entries — lowercase). Phase 8.1 specifies the exact value verbatim.

Prerequisite for Yes: an "Authenticated Users" web role must exist (or any role with authenticatedusersrole: true flag). Phase 1.4 inventoried web roles — if none qualifies, warn the user that profile editing won't work until a role is assigned and offer to invoke /create-webroles first.

Cross-provider compatibility: the profile page works the same regardless of auth provider (local, Entra ID, Entra External ID, OIDC, social) because it operates on the contact record after sign-in — not on IdP-specific session state. Email is read-only on the page, so there's no provider-specific caveat to surface (the IdP remains the source of truth for email).

If "Terms and Conditions" is selected, first surface the GDPR prerequisite before collecting content — terms only function if the underlying solution is installed:

GDPR prerequisite: Terms require ALL THREE of these to be in place for the server to actually enforce them:

1. Authentication/Registration/TermsAgreementEnabled = true (site setting we will create)
2. The msdynce_PortalPrivacyExtensions solution must be installed in your Dataverse environment (IsGdprEnabled is portal-level)
3. The Account/Signin/TermsAndConditionsCopy content snippet must have non-empty text (we will create this)

Without the Privacy Extensions solution, the server silently ignores TermsAgreementEnabled. The setup-auth skill will still write all three pieces — but unless the solution is installed in Dataverse, the terms gate won't be enforced server-side.

Auto-detect the Privacy Extensions solution before asking. Run:

node "${PLUGIN_ROOT}/scripts/check-solution-installed.js" --solutionName "msdynce_PortalPrivacyExtensions"

The script prints JSON to stdout: { "installed": true, "version": "..." } if found, or { "installed": false } if the solution isn't in the environment. On infrastructure failure (no PAC environment, expired Azure CLI token, missing Read permission on the solutions table, network error), it exits non-zero and writes a human-readable reason to stderr.

Branch on the result:

If the user picks "Cancel" (in either the not-installed or fallback path): skip the Terms branch entirely, do not set TermsAgreementEnabled, do not create the Terms page or snippets.

Otherwise, collect the terms content. The server uses 4 content snippets — the skill hardcodes these values into the SPA Terms page component. Ask the user:

If the user provides custom text, use it. Otherwise use the default terms template (see authentication-reference.md for the default content).

Also collect optional customizations:

Store these 4 values — they'll be hardcoded into the Terms page component in Phase 5 and created as content snippets in Phase 8.1:

• TERMS_HEADING (default: "Terms and Conditions")
• TERMS_CONTENT (default: generic terms HTML)
• TERMS_AGREEMENT_TEXT (default: "I agree to these terms and conditions.")
• TERMS_BUTTON_TEXT (default: "Confirm")

Optionally ask about TermsPublicationDate:

If "Set a publication date", collect the date. The format should be ISO: YYYY-MM-DD (e.g., 2026-01-01). If "Every login", leave TermsPublicationDate unset.

If web roles were found in Phase 1.4, also ask:

2.1.1 Optional Advanced Settings

After collecting the required provider details, ask if the user wants to configure advanced settings:

If "Yes, show me the options", present the optional settings table relevant to the selected provider. Only show settings that apply to their provider type. For each setting the user wants to configure, collect the value.

Logout mode (external providers only — OIDC, Entra External ID, SAML2, WS-Fed, social)

Always offer this question to the user when an external provider is being configured (it's the most common advanced setting and has visible UX consequences). For local-auth-only sites, skip this question.

Two logout modes:

• Local logout (server default, simpler) — Power Pages clears its session cookie and redirects the user to returnUrl (defaults to /). The user remains signed in at the IdP. Next time they click the external provider button, the IdP's SSO cookie is still warm and they re-sign-in silently with no credential re-entry. This is the default UX for most consumer / customer-facing sites.
• Federated logout (RP-initiated) — Power Pages additionally calls the IdP's end_session_endpoint with id_token_hint and post_logout_redirect_uri. The IdP signs the user out of THEIR session too, then redirects the browser back to the site. The user is fully signed out across systems. Required for: shared-device scenarios, regulated industries with hard logout requirements, sites that explicitly want users to re-enter credentials each time.

If "Local logout only": do nothing further. Skip writing RPInitiatedLogout and PostLogoutRedirectUri site settings in Phase 8.1 — the server defaults handle it correctly (both default to false/unset).

If "Federated logout": this requires TWO pieces of configuration that MUST go together. Setting only RPInitiatedLogout=true without PostLogoutRedirectUri leaves users stranded on the IdP's "you have been signed out" page — confirmed via HAR analysis on a live Entra External ID site.

Step 1 — collect the post-logout redirect URI (default to the site root):

Validate the value: must be a fully-qualified URL on the same host as SITE_URL. Store as POST_LOGOUT_REDIRECT_URI.

Step 2 — for Entra External ID specifically, instruct the user to register the URL in their app registration:

Required app registration step (must be done in the Microsoft Entra admin center):

1. Go to App registrations → {your app} → Authentication
2. Scroll to the Front-channel logout URL field (under "Advanced settings", just above "Implicit grant and hybrid flows")
3. Enter: {POST_LOGOUT_REDIRECT_URI} — must match the value above exactly
4. Save

Why this is needed: Entra External ID rejects any post_logout_redirect_uri value that isn't pre-registered (same security model as Redirect URIs for sign-in). Without this registration, the IdP silently drops the parameter and the user is stranded after sign-out — even if Power Pages sends it correctly.

For other OIDC providers (Okta, Auth0, etc.), check the provider's docs for the equivalent registration. Most providers call this "Logout URL", "Post Logout Redirect URI", or "Allowed Sign-out Redirect URLs" under the app's settings.

Phase 8.1 will write BOTH RPInitiatedLogout=true AND PostLogoutRedirectUri={POST_LOGOUT_REDIRECT_URI} when this option is chosen.

OpenID Connect / Entra External ID optional settings:

SAML2 optional settings:

WS-Federation optional settings:

Social OAuth optional settings (Microsoft Account, Facebook, Google):

Local Authentication optional settings:

Session / Cookie settings (all providers):

Global auth toggles (all providers):

For each setting the user wants to configure, create the site setting using create-site-setting.js during Phase 8.1 alongside the required settings.

2.1.2 Set Up the IDP App Registration (check the provider's docs first)

Applies to OIDC providers (Okta, Auth0, Entra External ID, and other OIDC). For SAML2, WS-Federation, social, or local auth, use the Phase 2.1 walkthroughs.

Power Pages needs an OIDC app registration at the IDP, wired to this site. How you set it up depends entirely on the identity provider, so read the provider's own current documentation first.

Read first: ${PLUGIN_ROOT}/skills/setup-auth/references/idp-provisioning-reference.md — the Power Pages ↔ IDP contract (Redirect URI, the no-secret code id_token flow) and the per-IDP official documentation links.

Step A — check the provider's docs (always the first step). As soon as you know which IDP the user wants, read that provider's official documentation (via the reference links; use the Learn MCP microsoft_docs_search/microsoft_docs_fetch for Microsoft IDPs) to determine two things: (1) the exact steps to register and configure an OIDC app, and (2) the CLI it offers for configuring the app (Okta, Auth0, and Entra External ID each provide one). Do not proceed to any other step before this, and never invent console paths or endpoints.

Step B — choose how to set it up. Two ways — offer both:

• Guided (default, recommended) — you read the provider's docs and walk the user through the steps to perform in the provider's own console. Always available.
• Configure it for the user — when the provider offers a CLI for app configuration. Okta, Auth0, and Entra External ID all do, so always offer it for them. A CLI that isn't installed yet is not a reason to withhold the offer — installing it and signing in is part of this path.

For a provider that offers no such CLI, go Guided.

When the provider offers such a CLI (always for Okta, Auth0, Entra External ID), ask (otherwise skip this question and proceed Guided):

Step C — the app configuration Power Pages needs (inform, then approve). Power Pages' default is the no-secret code id_token flow, so the app is a Web application with no client secret. Present the target configuration and let the user approve or adjust:

• App type: Web application — no client secret
• Sign-in flow: code id_token (the app must issue ID tokens at the IDP)
• Redirect URI: <REDIRECT_URI> (exact — casing + signin- prefix)
• Scopes: openid profile email

In Guided, this is the checklist the user applies in the console. When you configure it for the user, it is the spec you apply.

Step D — execute sequentially and verify each step. Never one-shot. Do one step, verify it, then continue:

1. Register the app → capture/verify the Client ID.
2. Set the Redirect URI → verify it matches <REDIRECT_URI> exactly.
3. Enable ID token issuance (code id_token) → verify.

• Guided: instruct the user to perform each step in the console, then confirm the result before moving on.
• Configure it for the user: run the provider's CLI/API for each step, then read the object back to verify before the next.

Okta: enable Implicit (Hybrid) with Allow ID Token, assign the app to users (else access_denied "Policy evaluation failed"), and prefer the Org authorization server (https://{domain}). See the reference's Okta section.

🚦 Gate (consent · setup-auth:2.1.2.provision-idp): Explicit go/no-go before you configure a real app registration in the user's identity provider on the user's behalf.

Trigger: The user chose Configure it for me and the provider supports it; about to make real changes at the IDP on the user's behalf. Why we ask: This creates/configures a real object in the user's IDP tenant, so it should never happen without an explicit yes. Guided setup does not reach this gate — the user makes the changes. Cancel leaves: Nothing — no app is configured; the user can switch to Guided setup instead.

If "No": switch to the Guided flow.

Step E — open registration. External sign-ins obey the site's registration gating. Confirm the recommended default — Open for customer-facing providers (Auth0 / Okta / Entra External ID), Controlled for workforce Entra ID:

Store as OPEN_REGISTRATION_CHOICE. Phase 8.1 writes Authentication/Registration/OpenRegistrationEnabled (true for Open, false for Controlled). Pair this with the contact-linking (AllowContactMappingWithEmail) choice already collected in Phase 2.1.

Step F — record the results for Phase 8.1. However the app was set up, capture the values Phase 8.1 writes as site settings (identical for both flows): ClientId, Authority (and AuthenticationType = Authority), MetadataAddress (the provider's discovery endpoint — read from the IDP), RedirectUri. No ClientSecret — the no-secret flow needs none, so skip Phase 8.1.1 (Key Vault), same as Entra External ID. See the reference's "Resulting site settings" table.

2.2 Present Plan for Approval

Present the implementation plan inline:

• Which files will be created (auth service, types, authorization utils, components)
• How the auth UI will be integrated into the site's navigation
• Which routes/components will be protected and with which roles
• The site setting that needs to be configured (Authentication/Registration/ProfileRedirectEnabled = false)

🚦 Gate (plan · setup-auth:2.2.plan-approval): Final sign-off on the auth implementation plan before any file is written.

Trigger: Phase 2.2 presented the full plan inline. Why we ask: Wrong components generated; site settings written; ProfileRedirectEnabled flipped — fixable but adds churn. Cancel leaves: Nothing — no auth files written yet.

Use AskUserQuestion to get approval:

If "Approve and proceed": Continue to Phase 3.

If "I'd like to make changes": Ask the user what they want to change, revise the plan, and present it again for approval.

Output

• Authentication scope confirmed (login/logout, role-based access, or both)
• Target web roles selected
• Implementation plan approved by user

Phase 3: Create Auth Service

Goal: Create the authentication service, type declarations, and framework-specific auth hook/composable with local development mock support.

Reference: ${PLUGIN_ROOT}/skills/setup-auth/references/authentication-reference.md

Actions

3.1 Create Type Declarations

Create src/types/powerPages.d.ts with type definitions for the Power Pages portal object and user:

• PowerPagesUser interface — userName, firstName, lastName, email, contactId, userRoles[]
• PowerPagesPortal interface — User, version, type, id, geo, tenant, etc.
• Global Window interface extension for Microsoft.Dynamic365.Portal

3.2 Create Auth Service

Create the auth service file based on the detected framework and selected identity provider(s).

ALWAYS use the AUTH_PROVIDERS array pattern, even with one entry. Never generate a single AUTH_PROVIDER constant. The array pattern means adding a second provider later (e.g., a second Entra External ID tenant, or local + an external provider) is just appending to the array — no restructuring needed. This avoids the bug class where a re-run silently drops previously-configured providers because the single-constant pattern can't represent more than one.

The array MUST include:

• Every provider in EXISTING_PROVIDERS from Phase 1.5 (merged in based on the user's MERGE_MODE choice)
• Any new provider the user added via Phase 2.1

Use a stable id for each provider (e.g., entra-external-id-customer, entra-external-id-employee, local) so React keys and switch statements remain stable across re-runs.

All frameworks: Create src/services/authService.ts with these functions and types:

• AuthProviderType — string union: 'local' | 'oidc' | 'entra-id' | 'saml2' | 'ws-federation' | 'social'
• AuthProviderConfig — interface with id, type, displayName, optional providerIdentifier (required for 'oidc' / 'saml2' / 'ws-federation' / 'social'; OMIT for 'entra-id' — resolved at runtime), optional loginByEmail (local-only)
• AUTH_PROVIDERS: AuthProviderConfig[] — the array (one entry per configured provider, in the order they should appear on the Login page)
• LOCAL_PROVIDER — exported helper: AUTH_PROVIDERS.find(p => p.type === 'local') (undefined if no local)
• EXTERNAL_PROVIDERS — exported helper: AUTH_PROVIDERS.filter(p => p.type !== 'local')
• getCurrentUser() — reads from window.Microsoft.Dynamic365.Portal.User
• isAuthenticated() — checks if user exists and has userName
• getTenantId() — reads window.Microsoft.Dynamic365.Portal.tenant (the site's parent tenant GUID). Returns undefined if not yet populated.
• getAuthProvider() — DEPRECATED. For backward compat, returns the first local provider or the first provider overall. Prefer reading AUTH_PROVIDERS directly.
• fetchAntiForgeryToken() — fetches from /_layout/tokenhtml and parses HTML response
• resolveProviderIdentifier(provider) — returns the value to POST as provider to /Account/Login/ExternalLogin. For type='entra-id', derives https://login.windows.net/${getTenantId()}/ at runtime. For other external types, returns provider.providerIdentifier. Never hardcode tenant ID into the AUTH_PROVIDERS array for Entra ID — this resolver handles it.
• loginExternal(providerIdentifier, returnUrl?, invitationCode?) — Form POST to /Account/Login/ExternalLogin for external providers
• loginLocal(credential, password, rememberMe?, returnUrl?, invitationCode?) — fetch POST to /SignIn for local
• loginWithProvider(provider, { returnUrl?, invitationCode?, credentials? }) — router: dispatches to loginLocal() or loginExternal() based on provider.type. Uses resolveProviderIdentifier() so Entra ID's runtime resolution works transparently. This is what UI components should call.
• logout(returnUrl?) — redirects to /Account/Login/LogOff
• getAuthError() — parses ?message= or ?error= query params from server-side auth error redirects and returns a user-friendly error message
• getSessionExpiredMessage() — checks for ?sessionExpired=true and returns a session-expired message
• parseServerErrors(html) — Required for local auth. Parses validation errors from server HTML responses (.validation-summary-errors li, .alert-danger li, .field-validation-error). Used by login and register to show server errors in the SPA.
• register(fields, returnUrl?, invitationCode?) — Required when local auth is configured. POSTs registration form to /Account/Login/Register with anti-forgery token, email or username (based on LocalLoginByEmail choice from Phase 2.1), password, confirmPassword, and optional invitationCode. When LocalLoginByEmail is true, sends Email field. When false, sends Username field. See authentication-reference.md for the full implementation.
• forgotPassword(email) — Required when local auth is configured. MVC form POST to /Account/Login/ForgotPassword with Email + anti-forgery token. Server sends a password reset email. Uses fetch() like login. Returns a promise — on success (.then()), show a "check your email" confirmation. On failure (.catch()), show the error.
• resetPassword(userId, code, password, confirmPassword) — Required when local auth is configured. MVC form POST to /Account/Login/ResetPassword with UserId, Code, Password, ConfirmPassword, __RequestVerificationToken. The UserId and Code come from the URL query params (set by the email reset link). On success, redirects to /login?message=password_reset_success.
• TermsRequiredError — Required when terms are enabled. Custom error class thrown when the server redirects to the terms page after login or registration. The login/registration page catches this and navigates to the SPA /terms page.
• acceptTerms(returnUrl?) — Required when terms are enabled. Fetches the server terms page (GET /Account/Login/TermsAndConditions) to get the anti-forgery token, then POSTs acceptance (IsTermsAndConditionsAccepted=true, IsFacebook=False, UseExternalSignInAsync=False, IsInternalAADUser=False). Uses the response URL dynamically (server may serve terms from /Account/Login/TermsAndConditions or /TermsAndConditions).
• getUserDisplayName() — prefers full name, falls back to userName
• getUserInitials() — for avatar display

Terms detection in login and registration: Both loginLocal() and register() must check response.url.includes('TermsAndConditions') after the fetch completes. The server redirects to different URLs depending on the flow:

• Login: redirects to /Account/Login/TermsAndConditions
• Registration: redirects to /TermsAndConditions?ReturnUrl=%2F

Both are caught by response.url.includes('TermsAndConditions'). When detected, throw TermsRequiredError. The server also sets a DeferredLocalLoginCookie — it defers the session creation until terms are accepted.

CRITICAL — Use fetch() not form.submit() for local login and registration. Using form.submit() causes a full-page navigation — if the server returns an error, the user leaves the SPA and sees the server-rendered error page. Using fetch() instead keeps the user in the SPA: on success (redirect), navigate via window.location.href; on failure (200 with HTML), parse errors with parseServerErrors() and throw them so the page component can display them inline. See authentication-reference.md for the full implementation.

Login flow varies by provider type:

• Microsoft Entra ID: Form POST to /Account/Login/ExternalLogin with provider https://login.windows.net/{tenantId}/
• Entra External ID: Form POST to /Account/Login/ExternalLogin with provider set to the External ID AuthenticationType (configured via site settings Authentication/OpenIdConnect/{provider}/AuthenticationType). Uses OpenID Connect underneath with the External ID tenant authority URL.
• OpenID Connect: Form POST to /Account/Login/ExternalLogin with provider set to the OIDC AuthenticationType (configured via site settings Authentication/OpenIdConnect/{provider}/AuthenticationType)
• SAML2: Form POST to /Account/Login/ExternalLogin with provider set to the SAML2 AuthenticationType (configured via site settings Authentication/SAML2/{provider}/AuthenticationType)
• WS-Federation: Form POST to /Account/Login/ExternalLogin with provider set to the WS-Federation AuthenticationType (configured via site settings Authentication/WsFederation/{provider}/AuthenticationType)
• Local Authentication: Form POST to /SignIn with PasswordValue (not Password), anti-forgery token from /_layout/tokenhtml, and optionally RememberMe. When LocalLoginByEmail is true, send the Email field; otherwise send the Username field. Note: the login endpoint uses /SignIn and PasswordValue — these differ from the registration endpoint which uses /Account/Login/Register and Password. Does NOT use the ExternalLogin endpoint.
• Microsoft Account: Form POST to /Account/Login/ExternalLogin with provider urn:microsoft:account
• Facebook: Form POST to /Account/Login/ExternalLogin with provider Facebook
• Google: Form POST to /Account/Login/ExternalLogin with provider Google

CRITICAL: Power Pages authentication is server-side (session cookies). External login flows post a form to the server which redirects to the identity provider. Local login posts credentials directly to the server. There is no client-side token management. The fetchAntiForgeryToken() call gets a CSRF token for the form POST, not a bearer token.

SECRET MANAGEMENT: Never include ClientSecret, AppSecret, or any credential values in the auth service code or any file committed to source control. The providerIdentifier field is a public identifier (URL or name), not a secret. Actual secrets must be configured through the Power Pages admin center.

SERVER-RENDERED PAGE HANDLING: For external login flows, the Power Pages server may redirect to server-rendered pages during certain flows (e.g., first-time registration via ExternalLoginConfirmation, 2FA via SendCode/VerifyCode, terms acceptance via TermsAndConditions). These are server-side decisions that the SPA cannot intercept. To minimize these redirects:

• Ensure Authentication/Registration/OpenRegistrationEnabled is configured correctly — when true, new external users are auto-registered without the ExternalLoginConfirmation page
• Ensure TermsAgreementEnabled is false unless explicitly needed — otherwise every first login shows a server-rendered terms page
• For 2FA flows, the server renders SendCode and VerifyCode pages — these cannot be replaced by SPA code
• When the user returns from a server-rendered page, the SPA should check for auth state changes (getCurrentUser()) and update the UI accordingly
• The auth service's useAuth hook should call refresh() on mount to pick up session changes that happened outside the SPA

For local auth, all error handling is client-side — the login() and register() functions use fetch() (not form.submit()) so the user stays in the SPA. Server errors are parsed from HTML responses via parseServerErrors() and thrown for the UI to display inline.

3.3 Create Framework-Specific Auth Hook/Composable

Based on the detected framework:

• React: Create src/hooks/useAuth.ts — custom hook returning { user, isAuthenticated, isLoading, displayName, initials, login, logout, refresh }
• Vue: Create src/composables/useAuth.ts — composable using ref, computed, onMounted returning reactive auth state
• Angular: Create src/app/services/auth.service.ts — injectable service with BehaviorSubject for user state
• Astro: Create src/services/authService.ts only (no framework-specific wrapper needed — use the service directly in components)

3.4 Add Mock Data for Local Development

Auth only works when served from Power Pages (not during local npm run dev). Add a development mock pattern in the auth service:

// In development (localhost), return mock user data for testing
const isDevelopment = window.location.hostname === 'localhost' || window.location.hostname === '127.0.0.1';

The mock should return a fake user with configurable roles so developers can test role-based UI locally.

3.5 Create Session KeepAlive Hook

SPA session expiry problem: In SPAs, page navigation is client-side — no server requests are made. The session cookie's SlidingExpiration only renews when the browser sends a request to the server. Without a keepalive, the session silently expires even while the user is actively using the SPA. The default ExpireTimeSpan is 24 hours with renewal at the halfway point (12 hours), but this can be configured shorter.

Provider-agnostic — works for local AND external auth. Power Pages issues the same ApplicationCookie session cookie regardless of how the user signed in (local password, Entra External ID, generic OIDC, SAML2, social). The keepalive operates on that cookie, so the same hook covers every provider. isAuthenticated() reads from window.Microsoft.Dynamic365.Portal.User which is populated for any authenticated user. No provider-specific branches are needed.

External providers — two independent clocks. For external auth, the Power Pages session cookie and the IdP token (e.g., Entra External ID's ID token / refresh token) have separate lifetimes. The Power Pages session is what the SPA needs to keep alive; the IdP token is invisible to the SPA. When the Power Pages session does expire and the user is redirected to /login?sessionExpired=true, clicking the external provider button kicks off the IdP round-trip — but if the IdP's SSO cookie is still valid (typical), the round-trip is silent (no credential re-entry). The user lands back in the site signed in. This is the expected UX and requires no extra handling.

Create a session keepalive hook that periodically pings /_layout/tokenhtml to renew the session cookie:

• React: Create src/hooks/useSessionKeepAlive.ts
• Vue: Create src/composables/useSessionKeepAlive.ts
• Angular: Create src/app/services/session-keepalive.service.ts

The hook must:

• Define a SESSION_EXPIRE_MS constant based on the session timeout:
  • If the user configured a custom ApplicationCookie/ExpireTimeSpan in Phase 2.1.1, convert that timespan to milliseconds
  • If using defaults, use 24 * 60 * 60 * 1000 (24 hours)
• Derive timing from the session timeout — do NOT hardcode intervals:
  • intervalMs = min(SESSION_EXPIRE_MS / 3, 15 * 60 * 1000) — ping at 1/3 of the session timeout, capped at 15min. This ensures the ping happens well before the SlidingExpiration halfway renewal point.
  • idleTimeoutMs = min(SESSION_EXPIRE_MS * 0.9, 30 * 60 * 1000) — stop pinging when idle for 90% of the session timeout, capped at 30min.
  • Example: 10min session → intervalMs=3.3min, idleTimeoutMs=9min. 24h session → intervalMs=15min, idleTimeoutMs=30min.
• Ping /_layout/tokenhtml via fetchAntiForgeryToken() at the calculated interval
• Only ping when the user is authenticated (isAuthenticated())
• Only ping when the browser tab is visible (document.visibilityState !== 'hidden')
• Track user activity (mouse, keyboard, touch, scroll) and stop pinging after idleTimeoutMs of idle — let the session expire naturally for security
• Detect session expiry: if the ping fails, call onSessionExpired callback so the app can redirect to login with ?sessionExpired=true
• Skip entirely in development mode (no real session to keep alive)

Integrate the hook into the Layout component so it runs on every page. Pass an onSessionExpired callback that navigates to /login?sessionExpired=true. The login page already handles ?sessionExpired=true via getSessionExpiredMessage().

Output

• src/types/powerPages.d.ts created with Power Pages type definitions
• src/services/authService.ts created with login/logout functions
• Framework-specific auth hook/composable created
• Session keepalive hook created and integrated into Layout
• Local development mock data included

Phase 4: Create Authorization Utils

Goal: Create role-checking utilities and framework-specific authorization components (guards, directives, wrapper components).

Reference: ${PLUGIN_ROOT}/skills/setup-auth/references/authorization-reference.md

Actions

4.1 Create Core Authorization Utilities

Create src/utils/authorization.ts with:

• getUserRoles() — returns array of role names from current user
• hasRole(roleName) — case-insensitive single role check
• hasAnyRole(roleNames) — OR check across multiple roles
• hasAllRoles(roleNames) — AND check across multiple roles
• isAuthenticated() — re-exports from auth service
• isAdmin() — checks for "Administrators" role
• hasElevatedAccess(additionalRoles) — checks admin or specified roles

4.2 Create Framework-Specific Authorization Components

Based on the detected framework:

React:

• src/components/RequireAuth.tsx — renders children only for authenticated users, optional login prompt fallback
• src/components/RequireRole.tsx — renders children only for users with specified roles, supports requireAll mode
• src/hooks/useAuthorization.ts — hook returning { roles, hasRole, hasAnyRole, hasAllRoles, isAuthenticated, isAdmin }

Vue:

• src/composables/useAuthorization.ts — composable with computed roles and role-checking functions
• src/directives/vRole.ts — v-role directive for non-SPA role-based visibility

Angular:

• src/app/guards/auth.guard.ts — CanActivateFn with route data for required roles
• src/app/directives/has-role.directive.ts — structural directive *appHasRole="'RoleName'"

Astro:

• src/utils/authorization.ts only (use directly in component scripts)

4.3 Security Reminder

Add a comment at the top of the authorization utilities:

// IMPORTANT: Client-side authorization is for UX only, not security.
// Server-side table permissions enforce actual access control.
// Always configure table permissions via /integrate-webapi.

Output

• src/utils/authorization.ts created with role-checking functions
• Framework-specific authorization components created (guards, directives, or wrapper components)
• Security reminder comments included

Phase 5: Create Auth UI

Goal: Create the login/logout button component and integrate it into the site's navigation.

Actions

5.1 Create Auth Button Component

Based on the detected framework, create a login/logout button component:

• React: src/components/AuthButton.tsx + src/components/AuthButton.css
• Vue: src/components/AuthButton.vue
• Angular: src/app/components/auth-button/auth-button.component.ts + template + styles
• Astro: src/components/AuthButton.astro

The component should:

• Show a "Sign In" button when the user is not authenticated
• Show the user's display name, avatar (initials-based), and a "Sign Out" button when authenticated
• Include a loading state while checking auth status
• Be styled to match the site's existing design (read existing CSS variables/theme)

5.1.1 Create Sign-In Page

Route naming — avoid server conflicts: Power Pages reserves /SignIn, /Register, and all /Account/Login/* paths for server-rendered auth pages. SPA routes MUST NOT collide with these. Use /login for the sign-in page and /registration for the registration page.

Always create the /login page when AUTH_PROVIDERS.length > 1. When only one provider is configured (single external OR single local), the AuthButton's "Sign In" can call login() directly and no Login page is strictly needed — but creating one is still recommended since it gives a stable place to surface auth errors, the password reset link, the invitation banner, etc.

The Login page must:

• Import AUTH_PROVIDERS, LOCAL_PROVIDER, EXTERNAL_PROVIDERS, and loginWithProvider from authService
• Render every external provider as a button (loop EXTERNAL_PROVIDERS) — each button calls loginWithProvider(provider, { returnUrl, invitationCode })
• Render the local email/password form when LOCAL_PROVIDER exists. On submit, call loginWithProvider(LOCAL_PROVIDER, { returnUrl, invitationCode, credentials: { credential, password, rememberMe } })
• Use the credential field based on LOCAL_PROVIDER.loginByEmail — Email (type email) when true, Username (type text) when false
• Disable all buttons while any submission is in flight (an isSubmitting flag for local + externalSubmittingId for external)
• Catch TermsRequiredError from loginWithProvider and navigate to /terms
• Show the invitation banner when invitationCode is in the URL: "Sign in to redeem invitation {code}. The invitation will be linked to your account after you sign in."
• Show server-side auth errors parsed from ?message= query params (via getAuthError()) and session-expired messages from ?sessionExpired=true (via getSessionExpiredMessage())
• Include a "Forgot password?" link to /forgot-password (SPA route) when LOCAL_PROVIDER exists and ResetPasswordEnabled is true
• Include a "Create an account" link to /registration when REGISTRATION_MODE is Open registration only or Both (omit for Invitation-only and Registration disabled)

Render layout based on LOGIN_LAYOUT from Phase 2.1:

See authentication-reference.md for full code examples of each layout pattern in React.

When the /login page exists, the AuthButton's "Sign In" must navigate to /login (use <Link to="/login">) instead of calling any login function directly.

5.1.2 Create Registration Page

Always create the /registration page when REGISTRATION_MODE is not Registration disabled — regardless of whether the mode is Open registration only, Invitation-only, or Both, and regardless of whether local or external providers (or both) are configured. The page mirrors the Login page layout when both local and external providers exist: external provider buttons in a horizontal row at the top, an "or sign up with email" divider, and the local registration form below (when local auth is configured). In invitation-only mode the page is reached via the /redeem-invitation flow (Phase 5.1.7) or via the server-bouncing flow (Code-Site-Shell-Header catches /account/login/register), not direct navigation — but the SPA route must still exist so React Router can render it.

Important architectural note: The server-side registration page (/Account/Login/Register) is an ASP.NET Web Forms page, NOT an MVC action. The local register() function in authService handles this by first fetching the server page (GET), parsing the ViewState and control names, then POSTing with the correct payload. This only applies when the user submits the local registration form — external provider buttons skip this entirely and go through loginExternal().

External provider buttons (when EXTERNAL_PROVIDERS.length > 0):

Render external provider sign-up buttons in a horizontal row at the top of the page — same layout pattern as the Login page (Phase 5.1.1). Each button calls loginExternal(providerIdentifier, returnUrl, invitationCode) from authService — when the user clicks "Sign up with Entra External ID" the SPA initiates external auth with the invitation code (if present) in the URL. The server's ExternalLoginCallback then either auto-links via AllowContactMappingWithEmail, or surfaces the SPA-ified ExternalLoginConfirmation page (Phase 5.1.8), or redeems the invitation if one was provided. This is the same code path as the Login page external buttons — loginExternal() doesn't care whether the user came from /login or /registration; the server creates the contact on first sign-in if one doesn't exist.

If EXTERNAL_PROVIDERS.length > 0 AND LOCAL_PROVIDER exists, show the divider ("or sign up with email") between the external buttons and the local form. If only external providers (no local), show ONLY the external buttons with no divider and no local form — the page becomes effectively "pick a provider to sign up with".

Local form (when LOCAL_PROVIDER exists):

The local registration form must:

• Call the register() function from authService, which handles the Web Forms ViewState pattern (fetch server page → parse → POST with correct control names)
• Show the correct credential field based on the LocalLoginByEmail choice from Phase 2.1:
  • Email mode (LocalLoginByEmail = true): Show an Email field (type email). This is both the login identifier and email address.
  • Username mode (LocalLoginByEmail = false): Show a Username field (type text) AND a separate Email field (type email). Both are required — Username is the login identifier, Email is needed for the contact record.
• Include Password and Confirm Password fields (both type password)
• Validate that passwords match client-side before submitting
• Display server-side registration errors parsed from ?message= query params (via getAuthError())
• Parse and pass through invitationCode from the URL query string (for invitation-based registration flows where the user arrives via ?invitationCode=...)
• Include an "Already have an account? Sign in" link back to /login
• Skip the auth redirect in development mode — in dev mode the mock user is always "authenticated", which would block testing the registration form. Add: const isDev = window.location.hostname === 'localhost' and only redirect if isAuthenticated && !isDev.
• Be styled to match the site's existing sign-in page design (centered card layout)

Layout — matches the Login page (Phase 5.1.1). When the user picks LOGIN_LAYOUT in Phase 2.1, that layout choice (horizontal row / vertical stack / primary spotlight / tabbed) applies to both /login AND /registration so users get a consistent experience across the two pages.

Pre-fill email from invitation (when InvitationEnabled is true — i.e., Invitation-only or Both modes):

When the user arrives at /registration?invitationCode=X, the email field should pre-fill with the invited contact's email (matching the server-rendered page's behavior). Implement by calling fetchInvitationDetails(invitationCode) on mount:

useEffect(() => {
  if (!invitationCode) return
  fetchInvitationDetails(invitationCode).then(details => {
    if (details.email) setEmail(details.email)
  }).catch(() => { /* silent — user can enter email manually */ })
}, [invitationCode])

The fetchInvitationDetails() function (in authService.ts) GETs /Account/Login/Register?invitationCode={code} and parses the email from the rendered HTML's #EmailTextBox input value attribute. See authentication-reference.md for the implementation.

The email input must be controlled (value={email}) and editable — the user can change it if needed (this matches server behavior).

Framework-specific implementation:

• React: Create src/pages/Registration.tsx and add <Route path="/registration" element={<Registration />} /> to the router. See the RegisterForm component in authentication-reference.md for the implementation pattern — adapt it to match the site's existing styling patterns (inline styles, CSS variables, etc.)
• Vue: Create src/pages/Registration.vue and add the route to src/router/index.ts
• Angular: Create src/app/pages/registration/registration.component.ts and add the route to the router config
• Astro: Create src/pages/registration.astro

If REGISTRATION_MODE is Registration disabled, skip creating the /registration page entirely — there's no flow that should land users there.

5.1.3 Create Forgot Password Page (Local Auth Only)

If local authentication is configured AND ResetPasswordEnabled is true, create a /forgot-password page. This is a simple form that collects the user's email and POSTs to the server, which sends a password reset link via email.

Note: The forgot password endpoint (/Account/Login/ForgotPassword) is an MVC form (like login), NOT a Web Forms page (like registration). A simple fetch() POST with Email + __RequestVerificationToken works. The forgotPassword() function in authService handles this.

The forgot password page must:

• Show an email input field
• Call forgotPassword(email) from authService on submit
• Handle both success and error: Use .then() for success (show "Check your email" confirmation with green checkmark, hide the form) and .catch() for errors (show error inline, reset button). Do NOT only handle .catch() — the button will get stuck in "Sending..." state if .then() is not handled.
• Track emailSent state — when true, replace the form with a success message: "We've sent a password reset link to your email address. Please check your inbox and follow the instructions." with a "Back to sign in" link
• Display server errors inline (the forgotPassword() function uses fetch and throws parsed errors)
• Include a "Back to sign in" link to /login
• Use the same validate-on-blur pattern as login and registration (validate email format on blur, clear on change)

The login page's "Forgot password?" link should point to /forgot-password (SPA route), NOT /Account/Login/ForgotPassword (server URL).

After the server processes the request, it sends a reset email. The reset link in the email points to the server's /Account/Login/ResetPassword?UserId=...&Code=... — but this gets intercepted by the Header template redirect script (see Phase 5.1.6) and redirected to the SPA /reset-password page.

5.1.4 Validation Pattern for All Auth Pages (Local Auth Only)

All local auth pages (login, registration, forgot password) must implement validate-on-blur, clear-on-change for real-time field validation. This is the modern UX pattern — errors appear when the user leaves a field and disappear as they correct it.

Implementation pattern:

1. Track touched state per field (which fields the user has interacted with)
2. On blur (onBlur): mark field as touched, run validation, show error immediately
3. On change (onChange): if the field was already touched, re-validate and clear the error as soon as the value becomes valid. Also clear server errors on any change.
4. On submit: mark ALL fields as touched, validate everything, show all errors at once
5. showError(field) helper: only return the error if the field has been touched

Validation rules:

The password strength validation matches the default Power Pages password policy (EnforcePasswordPolicy). If the site creator customizes the password policy via Authentication/UserManager/PasswordValidator/* site settings, the client-side validation should match.

5.1.5 Create Terms and Conditions Page (When Terms Enabled)

If the user enabled Terms and Conditions in Phase 2, create a /terms SPA page. This page works for ALL auth flows — local sign-in, local registration, AND external providers (Entra External ID, OIDC, social) — via two complementary mechanisms:

1. Local auth flows (loginLocal, register): use fetch() so the SPA stays in-page. The auth service detects the server's TermsAndConditions redirect from response.url and throws TermsRequiredError. The login/registration page catches it and navigates to /terms.
2. External auth flows (loginExternal, loginWithProvider external branch): use form.submit() so the browser leaves the SPA during the IdP round-trip. After IdP callback, the server may redirect to /Account/Login/TermsAndConditions?ReturnUrl=/&UseExternalSignInAsync=True&IsFacebook=False&IsInternalAADUser=False. The Code-Site-Shell-Header script (Phase 5.1.6) catches this URL and redirects to the SPA /terms route, preserving the query string so acceptTerms() knows which sign-in completion path the server expects.

The terms page must:

• Hardcode the 4 snippet values collected in Phase 2 as constants at the top of the component:

  const TERMS_HEADING = '<value from Phase 2 or default>'
  const TERMS_CONTENT = '<HTML content from Phase 2 or default>'
  const TERMS_AGREEMENT_TEXT = '<value from Phase 2 or default>'
  const TERMS_BUTTON_TEXT = '<value from Phase 2 or default>'
  

  Copy
• Display the heading, terms content (rendered as HTML via dangerouslySetInnerHTML), checkbox with agreement text, and confirm button
• The confirm button calls acceptTerms('/') from authService — this reads the query string from window.location.search, fetches the server terms page (with the same query string preserved) to get the anti-forgery token, then POSTs the acceptance back to the same URL with the flags from the query string in the body
• The confirm button is disabled until the checkbox is checked
• Display server errors inline if acceptTerms() throws
• Include a "Back to sign in" link to /login

Login and Registration pages must catch TermsRequiredError (local auth path):

• In the Login page's loginLocal() catch block: if err instanceof TermsRequiredError, navigate to /terms
• In the Registration page's register() catch block: if err instanceof TermsRequiredError, navigate to /terms

No SPA code changes needed in loginExternal for the external auth path — the header-template redirect (Phase 5.1.6) handles it transparently. The external user lands at /terms?ReturnUrl=/&UseExternalSignInAsync=True&... after the IdP round-trip; the SPA renders the Terms page; acceptTerms() uses the query string to POST back with the correct UseExternalSignInAsync / IsFacebook / IsInternalAADUser flags.

How the server triggers terms (for reference):

• Local login flow: Server redirects to /Account/Login/TermsAndConditions after auth — caught via response.url.includes('TermsAndConditions') in loginLocal()
• Local registration flow: Server redirects to /TermsAndConditions?ReturnUrl=%2F after registration — caught via response.url.includes('TermsAndConditions') in register()
• External login flow: Server redirects from /Account/Login/ExternalLoginCallback to /Account/Login/TermsAndConditions?ReturnUrl=/&UseExternalSignInAsync=True&IsFacebook=False&IsInternalAADUser=False — caught via header-template redirect

acceptTerms() must be query-string-aware (required when external providers are configured alongside terms):

export async function acceptTerms(returnUrl?: string): Promise<void> {
  // Parse the flags from window.location.search — set by the server's redirect URL.
  // For local-auth users (no query string), defaults apply.
  const params = new URLSearchParams(window.location.search);
  const useExternalSignInAsync = params.get('UseExternalSignInAsync') || 'False';
  const isFacebook = params.get('IsFacebook') || 'False';
  const isInternalAADUser = params.get('IsInternalAADUser') || 'False';

  // Fetch the server terms page WITH the original query string preserved
  const serverTermsUrl = `/Account/Login/TermsAndConditions${window.location.search}`;
  const pageResponse = await fetch(serverTermsUrl, { credentials: 'same-origin', redirect: 'follow' });

  // ... extract anti-forgery token from rendered HTML ...

  // POST back to the same URL with body flags matching the query-string flags.
  // DO NOT hardcode UseExternalSignInAsync=False — external users need True.
  const body = new URLSearchParams();
  body.set('__RequestVerificationToken', antiForgeryToken);
  body.set('IsTermsAndConditionsAccepted', 'true');
  body.set('UseExternalSignInAsync', useExternalSignInAsync);
  body.set('IsFacebook', isFacebook);
  body.set('IsInternalAADUser', isInternalAADUser);
  body.set('InvitationCode', '');
  // ... POST and handle response ...
}

See authentication-reference.md for the full implementation.

Framework-specific implementation:

• React: Create src/pages/Terms.tsx and add <Route path="/terms" element={<Terms />} /> to the router

Content updates: When the site creator wants to change the terms text, they update the constants in the Terms page component and redeploy. The content snippets in Dataverse (Account/Signin/TermsAndConditionsCopy etc.) must also be updated to match — the server-rendered terms page reads from snippets, and the SPA reads from the hardcoded constants. Both must stay in sync.

5.1.6 Create Reset Password Page + Header Template Redirect (Local Auth Only)

If local authentication is configured AND ResetPasswordEnabled is true, create a full SPA reset password experience. This involves two pieces:

1. Code-Site-Shell-Header Template

The password reset email sends the user to /Account/Login/ResetPassword?UserId=...&Code=... — a server-rendered page. To keep the user in the SPA, we need a client-side redirect script that runs on server-rendered pages.

Why a new template? The pac pages upload-code-site command intentionally replaces the original "Header" and "Footer" web template content with <div/> on every upload. Any script added to the Header template gets wiped. The workaround is to create a separate web template (Code-Site-Shell-Header) and point the website record to it instead.

Create a new web template in .powerpages-site/web-templates/code-site-shell-header/:

Code-Site-Shell-Header.webtemplate.yml:

id: <generate-a-new-uuid>
name: Code-Site-Shell-Header

Code-Site-Shell-Header.webtemplate.source.html:

<div/>
<script>
  // SPA Site Shell Header — Server-to-SPA redirect for auth pages.
  // This template runs on server-rendered pages and redirects to SPA equivalents.
  // Uses a separate template because pac pages upload-code-site wipes the original Header.
  (function () {
    var path = window.location.pathname.toLowerCase();
    var search = window.location.search;
    var spaBase = window.location.origin;
    // Add an entry here for each server-rendered auth page that has a SPA equivalent.
    // Only include entries the site actually needs (e.g., omit /redeeminvitation when
    // InvitationEnabled is false).
    var redirects = {
      '/account/login/resetpassword': '/reset-password',
      '/account/login/redeeminvitation': '/redeem-invitation',
      '/register': '/redeem-invitation',
      '/account/login/register': '/registration',
      '/account/login/externallogincallback': '/external-login-confirmation',
      '/account/login/termsandconditions': '/terms',
      '/account/login/externalauthenticationfailed': '/login',
      '/signin': '/login'
    };
    // Special case: ExternalAuthenticationFailed may arrive with no query string
    // (generic failure) or with ?message=access_denied (user-denied at IdP).
    // Ensure the Login page always shows SOME error indication.
    if (path === '/account/login/externalauthenticationfailed' && !search) {
      window.location.replace(spaBase + '/login?message=external_auth_failed');
      return;
    }
    for (var serverPath in redirects) {
      if (path === serverPath) {
        window.location.replace(spaBase + redirects[serverPath] + search);
        return;
      }
    }
  })();
</script>

Conditional entries — only include redirect entries for pages that exist in the SPA:

About the two new entries (/register and /account/login/register): these handle a specific external-auth flow that's hard to discover otherwise. When an external user (Entra External ID, OIDC, SAML2, social) clicks the "Sign in" button WITHOUT first clicking an invitation email link, and they don't have an existing contact in Dataverse, the server forces them through a server-rendered invitation flow:

1. POST /Account/Login/ExternalLogin → IdP → /signin-{ProviderName-lowercased} → /Account/Login/ExternalLoginCallback
2. ExternalLoginCallback finds no contact + no invitation → redirects to /Register?ReturnUrl=/ (the RedeemInvitation form, server-rendered)
3. User enters invitation code → server validates → redirects to /Account/Login/Register?invitationCode=... (the local Register Web Forms page, which has external provider buttons rendered on it)
4. User clicks an external provider button on the Register page → /Account/Login/ExternalLogin?InvitationCode=... → external auth round 2 with invitation in URL → contact created + invitation redeemed

Without the /register and /account/login/register redirects, the user sees the server-rendered RedeemInvitation form and the Web Forms Register page — both break the SPA UX. These redirects apply to ALL external providers, not just Entra External ID, because the server's bouncing logic is provider-agnostic.

Then update website.yml to point headerwebtemplateid to the new template's ID:

headerwebtemplateid: <new-template-uuid>

The original "Header" template stays as <div/> (the upload command will keep wiping it, which is fine). The Code-Site-Shell-Header template survives uploads because the command only targets the templates named "Header" and "Footer".

This is extensible — additional server-to-SPA redirects can be added to the redirects object (e.g., for email confirmation pages).

2. SPA Reset Password Page

Create a /reset-password page that:

• Reads UserId and Code from the URL query params (preserved by the header redirect)
• Shows "Invalid Reset Link" with a link to /forgot-password if either param is missing
• Shows new password + confirm password fields with validate-on-blur (password strength validation same as registration)
• Calls resetPassword(userId, code, password, confirmPassword) from authService on submit
• On success, redirects to /login?message=password_reset_success
• On error, shows server errors inline

The resetPassword() function is an MVC form POST (no ViewState) to /Account/Login/ResetPassword with fields: __RequestVerificationToken, UserId, Code, Password, ConfirmPassword. Note: the password field is Password here (NOT PasswordValue like login — different endpoints use different field names).

Login page must handle the success message: Check for ?message=password_reset_success in the URL on mount and display a green success banner: "Your password has been reset. Please sign in with your new password."

Framework-specific implementation:

• React: Create src/pages/ResetPassword.tsx and add <Route path="/reset-password" element={<ResetPassword />} /> to the router

5.1.7 Create Redeem Invitation Page (Invitation Modes Only)

If REGISTRATION_MODE is Invitation-only or Both, create a /redeem-invitation SPA page. This is the landing page users hit when they click an invitation email link. The link format is {site-url}/Account/Login/RedeemInvitation?invitation={code} — the Code-Site-Shell-Header redirect (Phase 5.1.6) catches it and forwards to the SPA route.

Two paths land users on /redeem-invitation:

1. Direct invitation link: User clicks the email link /Account/Login/RedeemInvitation?invitation={code} → header script redirects to /redeem-invitation?invitation={code}. Clean SPA entry — invitation code in URL from the start.

2. Server-bounce path (external auth, no contact, no invitation): User clicks "Sign in with [external provider]" on the Login page WITHOUT first clicking an invitation link. They complete external auth, the server's ExternalLoginCallback finds no contact + no invitation, and redirects them to /Register?ReturnUrl=... (the alias for LoginController.RedeemInvitation). The header script catches /register and redirects to /redeem-invitation — same SPA page, no invitation code pre-filled, user types it in. This path applies to all external providers, not just Entra External ID — the server-side bouncing logic is provider-agnostic. Confirmed via HAR analysis on a live site with Entra External ID + Terms.

Server flow this replaces: The server's LoginController.RedeemInvitation action (crm.solutions.portal/Samples/MasterPortal/Areas/Account/Controllers/LoginController.cs lines 3232-3310) validates the invitation code and branches:

• RedeemByLogin = false (new user) → 302 redirect to /Account/Login/Register?invitationCode={code} — server expects registration with the code
• RedeemByLogin = true (existing user) → 200 OK with Login view, invitation code embedded in the form action URL — server expects sign-in, then redeems invitation in RedirectOnPostAuthenticate after auth
• Invalid / expired / already-redeemed code → 200 OK with form re-rendered, error in #redeemInvitation-validation-summary (all three conditions surface the same Invalid_Invitation_Code_Exception)

SPA design — fully replaces the server-rendered page:

The SPA page calls redeemInvitation(code, redeemByLogin) from authService, which uses fetch() with redirect: 'manual' to intercept the server's 302 redirect. Based on the response:

• response.type === 'opaqueredirect' → server validated code + would have redirected to Register → SPA navigates to /registration?invitationCode={code} (existing page from Phase 5.1.2)
• 200 OK with Login form markers in HTML → user wanted login flow → SPA navigates to /login?invitationCode={code} (existing page — must also be updated, see below)
• 200 OK with validation summary in HTML → invalid code → throw parsed server error (use existing parseServerErrors() helper)

DevTools artifact: After the POST, the browser's network panel will show the 302 Location target (e.g., /Account/Login/Register) as an aborted (net::ERR_ABORTED) request. This is expected — it's the redirect we intentionally chose not to follow via redirect: 'manual'. The flow uses response.type === 'opaqueredirect' to detect the redirect occurred without actually following it.

The redeem invitation page must:

• Read invitation or InvitationCode from the URL query (handle both casings — emails may use either)
• Pre-fill the invitation code input but keep it editable (in case user types it in manually with no email link)
• Show a checkbox: "Sign in with an existing account instead of registering" (this controls RedeemByLogin)
• Validate-on-blur: invitation code required and non-empty
• On submit, call redeemInvitation() and navigate based on the returned nextStep
• Display server errors inline (parsed via existing parseServerErrors)
• Include a "Back to sign in" link to /login
• Be styled to match the rest of the auth pages

Login page update (required):

The Login page (Phase 5.1.1) must also be updated when invitation mode is enabled:

1. Read invitationCode from URL query params on mount
2. If present, show an info banner: "Sign in to redeem invitation {code}. The invitation will be linked to your account after you sign in."
3. Pass invitationCode to loginLocal() as the new 5th parameter — the auth service appends it as ?InvitationCode={code} on the /SignIn POST URL. The server's Login(model, returnUrl, invitationCode) handler reads this and redeems the invitation in RedirectOnPostAuthenticate after successful authentication.

Framework-specific implementation:

• React: Create src/pages/RedeemInvitation.tsx and add <Route path="/redeem-invitation" element={<RedeemInvitation />} /> to the router. See the RedeemInvitation component in authentication-reference.md for the implementation pattern.
• Vue / Angular / Astro: Mirror the React pattern in the framework's idioms.

Auth service additions (required when invitation mode is enabled):

• redeemInvitation(invitationCode, redeemByLogin, returnUrl) — see Phase 3.2 for the function inventory; full code in authentication-reference.md
• fetchInvitationDetails(invitationCode) — already covered in Phase 5.1.2 for email pre-fill
• loginLocal() updated to accept optional invitationCode parameter (5th arg) — appends ?InvitationCode={code} to the /SignIn URL

5.1.8 Create External Login Confirmation Page (External Providers Only)

If any external provider is configured (OIDC, Entra External ID, SAML2, WS-Federation, social), create a /external-login-confirmation SPA page. This captures the first-time external sign-in flow that the server would otherwise render as ExternalLoginConfirmation.aspx.

Server flow this replaces: When a user signs in externally for the first time and no Dataverse contact exists, the server's LoginController.ExternalLoginCallback action (crm.solutions.portal/Samples/MasterPortal/Areas/Account/Controllers/LoginController.cs ~line 761) renders the ExternalLoginConfirmation view AT the callback URL (/Account/Login/ExternalLoginCallback). The view shows an editable email field plus hidden firstName/lastName/username from claims, and POSTs to /Account/Login/ExternalLoginConfirmation.

Why this can be SPA-ified (same pattern as Reset Password and Redeem Invitation):

• The __External cookie (5-minute TTL, AuthenticationMode = Passive, Secure = Always) stores the claims between the IdP callback and the form POST. It's auto-sent on same-origin fetches.
• The SPA fetches the server URL, parses the rendered HTML to extract pre-fill values + anti-forgery token, shows its own form, and POSTs back. The server processes the form unchanged.

Skip conditions — server skips this page entirely when:

• The user's email claim matches an existing contact AND AllowContactMappingWithEmail = true → server auto-signs in
• The user has an invitation code AND it resolves to an existing contact in the ESS system → server auto-signs in
• Registration is disabled or the user isn't allowed to register

In those cases the user goes straight to home after IdP callback — the SPA page never mounts.

Redirect chain

Email link / "Sign in with Entra External ID" button
   ↓
POST /Account/Login/ExternalLogin → server redirects to IdP
   ↓
User authenticates at IdP → IdP callback to /signin-{providername}
   ↓
OIDC middleware processes callback (sets __External cookie with claims)
   ↓
Forward to /Account/Login/ExternalLoginCallback
   ↓
ExternalLoginCallback action: new user, no existing contact
   → returns ExternalLoginConfirmation view at the callback URL
   ↓
┌─ Code-Site-Shell-Header script catches /account/login/externallogincallback ─┐
│  → window.location.replace('/external-login-confirmation' + query)            │
└────────────────────────────────────────────────────────────────────────────────┘
   ↓
SPA /external-login-confirmation page mounts
   → calls fetchExternalLoginDetails()
     → GET /Account/Login/ExternalLoginCallback (__External cookie auto-sent)
     → server returns the same rendered HTML
     → SPA parses #Email, #FirstName, #LastName, #Username, #InvitationCode,
       __RequestVerificationToken, and the form's action URL for ReturnUrl
   ↓
SPA renders own form, email pre-filled and editable
   ↓
User clicks "Create my account"
   → confirmExternalLogin() POST /Account/Login/ExternalLoginConfirmation
     (form fields + anti-forgery token, redirect:'manual')
   ↓
   ├── response.type === 'opaqueredirect' → window.location.href = returnUrl
   │     (server sets ApplicationCookie BEFORE returning 302 — user is signed in)
   ├── 200 OK with validation-summary → throw parsed error (e.g., duplicate email
   │     when RequireUniqueEmail is true and user typed an existing email)
   └── 200 OK with TermsAndConditions markers → throw TermsRequiredError →
         SPA navigates to /terms

Auth service additions (when any external provider is configured)

Add three things to src/services/authService.ts — full code in authentication-reference.md:

• ExternalLoginCookieExpiredError class — thrown when the __External cookie has expired (5-minute TTL exceeded). The page navigates to /login with an expired-session message.
• fetchExternalLoginDetails() — fetches /Account/Login/ExternalLoginCallback, parses HTML for pre-fill values and anti-forgery token. Throws ExternalLoginCookieExpiredError if the form isn't present.
• confirmExternalLogin(details) — POSTs to /Account/Login/ExternalLoginConfirmation with redirect:'manual'. Branches on response type to navigate or throw.

SPA page

Create src/pages/ExternalLoginConfirmation.tsx:

• On mount, calls fetchExternalLoginDetails(). Three states: loading, cookie-expired, ready.
• When cookie expired: shows "Sign-in session expired" with a "Back to sign in" link to /login.
• When ready: shows the user's full name read-only (from claims), an editable email input (default = email claim), and an "invitation banner" if invitationCode is non-empty.
• On submit, calls confirmExternalLogin(details). Handles TermsRequiredError → navigate to /terms. Handles ExternalLoginCookieExpiredError (mid-session expiry) → switch UI to the expired state.
• Server-side validation errors shown inline via parseServerErrors.

Routing

Add <Route path="/external-login-confirmation" element={<ExternalLoginConfirmation />} />.

DevTools artifact

After the POST, the network panel may show the 302 Location target (e.g., the returnUrl path) as an aborted (net::ERR_ABORTED) request — same as the RedeemInvitation pattern. Expected behavior from redirect:'manual', not an error.

Edge cases

• 2FA: If the user has 2FA enabled, the challenge happens AFTER SignInAsync completes (during the 302 redirect). The SPA-ified flow doesn't interfere — the 2FA challenge (SendCode/VerifyCode) is its own server-rendered flow that cannot be intercepted.
• SameSite=Strict: If the __External cookie is configured with SameSite=Strict, the SPA's fetch won't include it and fetchExternalLoginDetails throws ExternalLoginCookieExpiredError immediately. Default is Lax (set via SameSiteCookieHelper.GetOwinSameSiteFromSiteSettings) — works fine.
• Invited user via external login: Invitation code is captured from the form action URL by fetchExternalLoginDetails and re-sent on the POST. The server redeems the invitation as part of contact creation.

5.1.9 Create Profile Page (When INCLUDE_PROFILE_PAGE = true)

Conditional on INCLUDE_PROFILE_PAGE = true (Phase 2.1). Skip this entire phase otherwise.

Creates a /user-profile SPA page where signed-in users edit their contact record via the Power Pages Web API. Provider-agnostic — works for local + all external providers because it operates on the contact record after sign-in.

⚠ MANDATORY NAMING — do not deviate:

Item	Required name	Wrong examples to AVOID
SPA route	/user-profile	❌ /profile (server-reserved), /my-profile, /account/profile
Page component file	src/pages/UserProfile.tsx	❌ Profile.tsx, MyProfile.tsx, UserProfilePage.tsx
Component export name	UserProfile (default export)	❌ Profile, ProfilePage
Service function — read	getMyProfile(contactId)	❌ getOwnContact, getProfile, fetchProfile
Service function — write	updateMyProfile(contactId, payload)	❌ patchOwnContact, updateProfile, saveProfile
Type — contact shape	ProfileContact	❌ Contact, UserContact
Type — patch payload	ProfileUpdate	❌ ContactUpdate, ProfilePatch

Why naming matters: the file/route names are referenced by other parts of this skill (Phase 7.1 verification, Phase 8.3 summary), the auth-reference.md, and the eval scenarios. Renaming creates a broken-cross-reference cascade. The route /profile specifically MUST NOT be used because the Power Pages server reserves it for the legacy server-rendered profile page (`Authentication/Registration/ProfileRedirectE