This skill should be used when the user asks to "set up authentication", "add login", "add logout", "configure Entra ID", "set up Azure AD auth", "add Microsoft login", "enable authentication", "set up sign in", "add role-based access", "add authorization", "protect routes", "add auth to my site", "configure identity provider", or wants to set up authentication (login/logout via Microsoft Entra ID) and role-based authorization for their Power Pages code site.
This skill should be used when the user asks to "set up authentication", "add login", "add logout", "configure Entra ID", "set up Azure AD auth", "add Microsoft login", "enable authentication", "set up sign in", "add role-based access", "add authorization", "protect routes", "add auth to my site", "configure identity provider", or wants to set up authentication (login/logout via Microsoft Entra ID) and role-based authorization for their Power Pages code site.
{"Stop":[{"hooks":[{"type":"command","command":"node \"${CLAUDE_PLUGIN_ROOT}/skills/setup-auth/scripts/validate-auth.js\"","timeout":15},{"type":"prompt","prompt":"If authentication/authorization was being set up in this session (via /power-pages:setup-auth), verify before allowing stop: 1) The site was found and framework detected, 2) An auth service file was created (authService.ts/js) with login/logout functions, 3) PowerPages type declarations were created (powerPages.d.ts), 4) Authorization utilities were created (authorization.ts/js) with role-checking functions, 5) Auth UI component was created (AuthButton or equivalent), 6) All auth files were verified (exist, contain expected exports, project builds successfully), 7) The user was asked whether to deploy the site. If any of these are incomplete, return { \"ok\": false, \"reason\": \"<specific issues>\" }. If no auth setup work happened or everything is complete, return { \"ok\": true }.\n","timeout":30}]}]}
Set Up Authentication & Authorization
Configure authentication (login/logout via Microsoft Entra ID) and role-based authorization for a Power Pages code site. This skill creates an auth service, type declarations, authorization utilities, auth UI components, and role-based access control patterns appropriate to the site's framework.
Core Principles
Client-side auth is UX only — Power Pages authentication is server-side (session cookies). Client-side role checks control what users see, not what they can access. Server-side table permissions enforce actual security.
Framework-appropriate patterns — Every auth artifact (hooks, composables, services, directives, guards) must match the detected framework's idioms and conventions.
Development parity — Include mock data for local development so developers can test auth flows and role-based UI without deploying to Power Pages.
Initial request: $ARGUMENTS
Prerequisites:
An existing Power Pages code site created via /power-pages:create-site
The site must be deployed at least once (.powerpages-site folder must exist)
Web roles must be created via /power-pages:create-webroles
Workflow
Phase 1: Check Prerequisites — Verify site exists, detect framework, check web roles
Phase 2: Plan — Gather auth requirements and present plan for approval
Phase 3: Create Auth Service — Auth service with login/logout and type declarations
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 /power-pages:create-site.
1.2 Detect Framework
Read package.json to determine the framework (React, Vue, Angular, or Astro). See ${CLAUDE_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."
Use AskUserQuestion:
Question
Options
Your site needs to be deployed first. Would you like to deploy now?
Yes, deploy now (Recommended), No, I'll do it later
If "Yes, deploy now": Invoke /power-pages: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).
If no web roles exist: Warn the user that web roles are needed for authorization. Ask if they want to create them first:
Question
Options
No web roles were found. Web roles are required for role-based authorization. Would you like to create them now?
Yes, create web roles first (Recommended), Skip — I'll add roles later
If "Yes": Invoke /power-pages: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 Check for Existing Auth Code
Search for existing auth files to avoid duplicating work:
src/services/authService.ts or src/services/authService.js
src/types/powerPages.d.ts
src/utils/authorization.ts or src/utils/authorization.js
logout(returnUrl?) — redirects to /Account/Login/LogOff
getUserDisplayName() — prefers full name, falls back to userName
getUserInitials() — for avatar display
CRITICAL: Power Pages authentication is server-side (session cookies). The login flow posts a form to the server which redirects to Entra ID. There is no client-side token management. The fetchAntiForgeryToken() call gets a CSRF token for the form POST, not a bearer token.
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 testingconst 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.
Output
src/types/powerPages.d.ts created with Power Pages type definitions
src/services/authService.ts created with login/logout functions
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 /power-pages: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:
Run the project build to catch any import errors, type errors, or missing dependencies:
npm run build
If the build fails, fix the issues before proceeding.
7.3 Verify Auth UI Renders
Start the dev server and verify the auth button appears in the navigation:
npm run dev
Use Playwright to navigate to the site and take a snapshot to confirm the auth button is visible:
Navigate to http://localhost:<port>
Take a browser snapshot
Verify the auth button (Sign In / mock user) appears in the navigation area
If the auth button is not visible or the page has rendering errors, fix the issues.
Output
All auth files verified (present and contain expected exports)
Project builds successfully
Auth UI renders correctly in the browser
Phase 8: Review & Deploy
Goal: Create required site settings, present a summary of all work, and prompt for deployment.
Actions
8.1 Create Site Setting
The site needs the Authentication/Registration/ProfileRedirectEnabled setting set to false to prevent Power Pages from redirecting users to a profile page after login (which doesn't exist in code sites).
Check if .powerpages-site/site-settings/ exists. If it does, create the site setting file:
Authentication and authorization are configured. To make login work, the site needs to be deployed. Would you like to deploy now?
Yes, deploy now (Recommended), No, I'll deploy later
If "Yes, deploy now": Invoke /power-pages:deploy-site.
If "No": Remind the user:
"Remember to deploy your site using /power-pages:deploy-site when you're ready. Authentication will not work until the site is deployed with the new site settings."
8.5 Post-Deploy Notes
After deployment (or if skipped), remind the user:
Test on deployed site: Auth only works on the deployed Power Pages site, not on localhost
Entra ID configuration: The site's identity provider must be configured in the Power Pages admin center to use Microsoft Entra ID
Assign web roles: Users must be assigned appropriate web roles in the Power Pages admin center
Table permissions: Client-side auth checks are for UX only — configure server-side table permissions via /power-pages:integrate-webapi for actual data security
Local development: The auth service includes mock data for testing on localhost — remove or disable before production
Output
ProfileRedirectEnabled site setting created
Full summary presented to user
Deployment prompted (or skipped with reminder)
Post-deploy guidance provided
Important Notes
Progress Tracking
Use TaskCreate at the start to track each phase:
Task
Description
Phase 1
Check Prerequisites — verify site, framework, deployment, web roles
Phase 2
Plan — gather requirements and get user approval
Phase 3
Create Auth Service — auth service, types, framework hook/composable
Phase 4
Create Authorization Utils — role-checking functions and components
Phase 5
Create Auth UI — AuthButton component and navigation integration
Phase 6
Implement Role-Based UI — apply authorization patterns to components
