setup-auth

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

为Power Pages代码站点配置通过Microsoft Entra ID实现的登录/登出认证以及基于角色的授权。此技能会创建认证服务、类型声明、授权工具、认证UI组件，以及适合站点框架的基于角色的访问控制模式。

Core Principles

核心原则

Client-side auth is UX only — Power Pages authentication is server-side (session cookies). Client-side role checks control what users see, not what they can access. Server-side table permissions enforce actual security.
Framework-appropriate patterns — Every auth artifact (hooks, composables, services, directives, guards) must match the detected framework's idioms and conventions.
Development parity — Include mock data for local development so developers can test auth flows and role-based UI without deploying to Power Pages.

Initial request: $ARGUMENTS

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

客户端认证仅用于用户体验 — Power Pages认证是服务器端的（会话Cookie）。客户端角色检查仅控制用户可见内容，而非实际可访问内容。服务器端表权限才是实际安全控制的保障。
适配框架的模式 — 所有认证工件（钩子、组合式函数、服务、指令、守卫）必须符合检测到的框架的设计风格与约定。
开发一致性 — 包含本地开发用的模拟数据，以便开发者无需部署到Power Pages即可测试认证流程和基于角色的UI。

初始请求：$ARGUMENTS

前置条件：
已通过
/create-site
创建现有的Power Pages代码站点
站点至少已部署一次（必须存在
.powerpages-site
文件夹）
已通过
/create-webroles
创建Web角色

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 4: Create Authorization Utils — Role-checking functions and wrapper components
Phase 5: Create Auth UI — Login/logout button integrated into navigation
Phase 6: Implement Role-Based UI — Apply role-based patterns to site components
Phase 7: Verify Auth Setup — Validate all auth files exist, build succeeds, auth UI renders
Phase 8: Review & Deploy — Summary and deployment prompt

阶段1：检查前置条件 — 验证站点是否存在、检测框架、检查部署状态和Web角色
阶段2：规划 — 收集认证需求并提交方案供审批
阶段3：创建认证服务 — 包含登录/登出功能和类型声明的认证服务
阶段4：创建授权工具 — 角色检查函数和包装组件
阶段5：创建认证UI — 集成到导航栏的登录/登出按钮
阶段6：实现基于角色的UI — 为站点组件应用基于角色的模式
阶段7：验证认证设置 — 验证所有认证文件是否存在、构建是否成功、认证UI是否正常渲染
阶段8：审核与部署 — 总结工作并提示部署

Phase 1: Check Prerequisites

阶段1：检查前置条件

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

目标： 确认项目存在、识别框架、验证部署状态和Web角色、检查是否存在现有认证代码。

Actions

操作步骤

1.1 Locate Project

1.1 定位项目

Look for

powerpages.config.json

in the current directory or immediate subdirectories:

text

**/powerpages.config.json

If not found: Tell the user to create a site first with

/create-site

powerpages.config.json

：

text

**/powerpages.config.json

若未找到：告知用户需先通过

/create-site

创建站点。

1.2 Detect Framework

1.2 检测框架

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.

读取

package.json

以确定框架（React、Vue、Angular或Astro）。完整的框架检测映射请参考

${CLAUDE_PLUGIN_ROOT}/references/framework-conventions.md

。

1.3 Check Deployment Status

1.3 检查部署状态

Look for the

.powerpages-site

folder:

text

**/.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

/deploy-site

, then resume.

If "No": Stop — the site must be deployed first.

查找

.powerpages-site

文件夹：

text

**/.powerpages-site

若未找到：告知用户需先部署站点：

"未找到
.powerpages-site
文件夹。在配置认证前，站点至少需部署一次。"

使用

AskUserQuestion

：

问题	选项
您的站点需要先完成部署。是否现在进行部署？	是，立即部署（推荐）, 否，我稍后自行部署

若选择“是，立即部署”：调用

/deploy-site

，之后继续流程。

若选择“否”：终止流程 — 站点必须先完成部署。

1.4 Check Web Roles

1.4 检查Web角色

Look for web role YAML files in

.powerpages-site/web-roles/

text

**/.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

/create-webroles

, then resume.

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

在

.powerpages-site/web-roles/

中查找Web角色YAML文件：

text

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

读取每个文件并编译现有Web角色列表（名称、ID、标记）。

若不存在Web角色：警告用户授权需要Web角色。询问用户是否要先创建：

问题	选项
未找到Web角色。基于角色的授权需要Web角色。是否要先创建Web角色？	是，先创建Web角色（推荐）, 跳过 — 我稍后自行添加角色

若选择“是”：调用

/create-webroles

，之后继续流程。

若选择“跳过”：继续流程 — 认证服务和登录/登出功能仍可正常工作，但基于角色的授权需后续创建角色后才能使用。

1.5 Check for Existing Auth Code

1.5 检查现有认证代码

Search for existing auth files to avoid duplicating work:

src/services/authService.ts

src/services/authService.js

```
src/types/powerPages.d.ts
```

src/utils/authorization.ts

src/utils/authorization.js

Auth components (e.g.,
```
AuthButton.tsx
```
,
```
AuthButton.vue
```
)

If auth files already exist, present them to the user and ask whether to overwrite or skip.

搜索现有认证文件以避免重复工作：

src/services/authService.ts

或

src/services/authService.js

```
src/types/powerPages.d.ts
```

src/utils/authorization.ts

或

src/utils/authorization.js

认证组件（如
```
AuthButton.tsx
```
、
```
AuthButton.vue
```
）

若已存在认证文件，展示给用户并询问是否覆盖或跳过。

Output

输出结果

Project root path confirmed
Framework identified (React, Vue, Angular, or Astro)
Deployment status verified
Web roles inventory compiled
Existing auth code conflicts identified (if any)

已确认项目根路径
已识别框架（React、Vue、Angular或Astro）
已验证部署状态
已整理Web角色清单
已识别现有认证代码冲突（若有）

Phase 2: Plan

阶段2：规划

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

目标： 收集用户的认证需求并提交实现方案供审批。

Actions

操作步骤

2.1 Gather Requirements

2.1 收集需求

Use

AskUserQuestion

to determine the scope:

Question	Options
Which authentication features do you need?	Login & Logout + Role-based access control (Recommended), Login & Logout only, Role-based access control only (auth service already exists)

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

Question	Options
Which web roles should have access to protected areas of the site?	(List discovered web role names as options)

使用

AskUserQuestion

确定范围：

问题	选项
您需要哪些认证功能？	登录&登出 + 基于角色的访问控制（推荐）, 仅登录&登出, 仅基于角色的访问控制（已存在认证服务）

若在阶段1.4中找到Web角色，额外询问：

问题	选项
哪些Web角色应拥有站点受保护区域的访问权限？	（列出已发现的Web角色名称作为选项）

2.2 Present Plan for Approval

2.2 提交方案供审批

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

)

Use

AskUserQuestion

to get approval:

Question	Options
Here is the implementation plan for authentication and authorization. Would you like to proceed?	Approve and proceed (Recommended), I'd like to make changes

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.

直接展示实现方案：

将创建的文件（认证服务、类型定义、授权工具、组件）
认证UI将如何集成到站点导航中
哪些路由/组件将受保护以及对应的角色

需要配置的站点设置（

Authentication/Registration/ProfileRedirectEnabled = false

）

使用

AskUserQuestion

获取审批：

问题	选项
以下是认证与授权的实现方案。是否继续？	批准并继续（推荐）, 我需要修改方案

若选择“批准并继续”：进入阶段3。

若选择“我需要修改方案”：询问用户需要修改的内容，修订方案后再次提交审批。

Output

输出结果

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

已确认认证范围（登录/登出、基于角色的访问控制，或两者兼具）
已选择目标Web角色
实现方案已获得用户批准

Phase 3: Create Auth Service

阶段3：创建认证服务

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

Reference:

${CLAUDE_PLUGIN_ROOT}/skills/setup-auth/references/authentication-reference.md

目标： 创建认证服务、类型声明，以及支持本地开发模拟数据的框架特定认证钩子/组合式函数。

参考：

${CLAUDE_PLUGIN_ROOT}/skills/setup-auth/references/authentication-reference.md

Actions

操作步骤

3.1 Create Type Declarations

3.1 创建类型声明

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
```

创建

src/types/powerPages.d.ts

，包含Power Pages门户对象和用户的类型定义：

PowerPagesUser

接口 —

userName

、

firstName

、

lastName

、

email

、

contactId

、

userRoles[]

PowerPagesPortal

接口 —

User

、

version

、

type

、

id

、

geo

、

tenant

等

全局
```
Window
```
接口扩展，添加
```
Microsoft.Dynamic365.Portal
```

3.2 Create Auth Service

3.2 创建认证服务

Create the auth service file based on the detected framework:

All frameworks: Create

src/services/authService.ts

with these functions:

getCurrentUser()

— reads from

window.Microsoft.Dynamic365.Portal.User

```
isAuthenticated()
```
— checks if user exists and has
```
userName
```

getTenantId()

— reads from portal config (

window.Microsoft.Dynamic365.Portal.tenant

)

fetchAntiForgeryToken()

— fetches from

/_layout/tokenhtml

and parses HTML response

```
login(returnUrl?)
```
— creates a form POST to
```
/Account/Login/ExternalLogin
```
with:
- Anti-forgery token from
```
/_layout/tokenhtml
```
- Provider URL:
```
https://login.windows.net/{tenantId}/
```
- Return URL (defaults to current page)
```
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.

根据检测到的框架创建认证服务文件：

所有框架：创建

src/services/authService.ts

，包含以下函数：

getCurrentUser()

— 从

window.Microsoft.Dynamic365.Portal.User

读取用户信息

```
isAuthenticated()
```
— 检查用户是否存在且拥有
```
userName
```

getTenantId()

— 从门户配置读取（

window.Microsoft.Dynamic365.Portal.tenant

）

fetchAntiForgeryToken()

— 从

/_layout/tokenhtml

获取并解析HTML响应

```
login(returnUrl?)
```
— 向
```
/Account/Login/ExternalLogin
```
提交表单POST请求，包含：
- 来自
```
/_layout/tokenhtml
```
  的防伪造令牌
- 提供商URL：
```
https://login.windows.net/{tenantId}/
```
- 返回URL（默认为当前页面）
```
logout(returnUrl?)
```
— 重定向到
```
/Account/Login/LogOff
```
```
getUserDisplayName()
```
— 优先使用全名，回退使用userName
```
getUserInitials()
```
— 用于头像显示

重要提示：Power Pages认证是服务器端的（会话Cookie）。登录流程是向服务器提交表单，再由服务器重定向到Entra ID。不存在客户端令牌管理。

fetchAntiForgeryToken()

调用获取的是表单POST用的CSRF令牌，而非Bearer令牌。

3.3 Create Framework-Specific Auth Hook/Composable

3.3 创建框架特定的认证钩子/组合式函数

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)

根据检测到的框架：

React：创建

src/hooks/useAuth.ts

— 自定义钩子，返回

{ user, isAuthenticated, isLoading, displayName, initials, login, logout, refresh }

Vue：创建
```
src/composables/useAuth.ts
```
— 使用
```
ref
```
、
```
computed
```
、
```
onMounted
```
的组合式函数，返回响应式认证状态
Angular：创建
```
src/app/services/auth.service.ts
```
— 可注入服务，使用
```
BehaviorSubject
```
管理用户状态
Astro：仅创建
```
src/services/authService.ts
```
（无需框架特定包装 — 直接在组件中使用服务）

3.4 Add Mock Data for Local Development

3.4 添加本地开发用模拟数据

Auth only works when served from Power Pages (not during local

npm run dev

). Add a development mock pattern in the auth service:

typescript

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

认证仅在Power Pages部署环境中生效（本地

npm run dev

环境不生效）。在认证服务中添加开发环境模拟模式：

typescript

// 在开发环境（localhost）中，返回模拟用户数据用于测试
const isDevelopment = window.location.hostname === 'localhost' || window.location.hostname === '127.0.0.1';

模拟数据应返回带有可配置角色的虚拟用户，以便开发者在本地测试基于角色的UI。

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
Local development mock data included

已创建
```
src/types/powerPages.d.ts
```
，包含Power Pages类型定义
已创建
```
src/services/authService.ts
```
，包含登录/登出函数
已创建框架特定的认证钩子/组合式函数
已添加本地开发用模拟数据

Phase 4: Create Authorization Utils

阶段4：创建授权工具

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

Reference:

${CLAUDE_PLUGIN_ROOT}/skills/setup-auth/references/authorization-reference.md

目标： 创建角色检查工具和框架特定的授权组件（守卫、指令、包装组件）。

参考：

${CLAUDE_PLUGIN_ROOT}/skills/setup-auth/references/authorization-reference.md

Actions

操作步骤

4.1 Create Core Authorization Utilities

4.1 创建核心授权工具

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

创建

src/utils/authorization.ts

，包含：

```
getUserRoles()
```
— 返回当前用户的角色名称数组
```
hasRole(roleName)
```
— 不区分大小写的单角色检查
```
hasAnyRole(roleNames)
```
— 多角色或检查
```
hasAllRoles(roleNames)
```
— 多角色与检查
```
isAuthenticated()
```
— 从认证服务重新导出
```
isAdmin()
```
— 检查是否拥有“Administrators”角色
```
hasElevatedAccess(additionalRoles)
```
— 检查是否为管理员或拥有指定角色

4.2 Create Framework-Specific Authorization Components

4.2 创建框架特定的授权组件

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 declarative 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)

根据检测到的框架：

React：

```
src/components/RequireAuth.tsx
```
— 仅为已认证用户渲染子组件，可选登录提示回退内容
```
src/components/RequireRole.tsx
```
— 仅为拥有指定角色的用户渲染子组件，支持
```
requireAll
```
模式

src/hooks/useAuthorization.ts

— 钩子，返回

{ roles, hasRole, hasAnyRole, hasAllRoles, isAuthenticated, isAdmin }

Vue：

```
src/composables/useAuthorization.ts
```
— 包含计算属性角色和角色检查函数的组合式函数
```
src/directives/vRole.ts
```
—
```
v-role
```
指令，用于声明式的基于角色的可见性控制

Angular：

```
src/app/guards/auth.guard.ts
```
—
```
CanActivateFn
```
，使用路由数据指定所需角色

src/app/directives/has-role.directive.ts

— 结构型指令

*appHasRole="'RoleName'"

Astro：

仅使用
```
src/utils/authorization.ts
```
（直接在组件脚本中使用）

4.3 Security Reminder

4.3 安全提示

Add a comment at the top of the authorization utilities:

typescript

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

在授权工具顶部添加注释：

typescript

// 重要提示：客户端授权仅用于用户体验，而非安全控制。
// 服务器端表权限才是实际的访问控制保障。
// 请始终通过`/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

已创建
```
src/utils/authorization.ts
```
，包含角色检查函数
已创建框架特定的授权组件（守卫、指令或包装组件）
已添加安全提示注释

Phase 5: Create Auth UI

阶段5：创建认证UI

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

目标： 创建登录/登出按钮组件并集成到站点导航中。

Actions

操作步骤

5.1 Create Auth Button Component

5.1 创建认证按钮组件

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)

根据检测到的框架，创建登录/登出按钮组件：

React：

src/components/AuthButton.tsx

src/components/AuthButton.css

Vue：
```
src/components/AuthButton.vue
```

Angular：

src/app/components/auth-button/auth-button.component.ts

+ 模板 + 样式

Astro：
```
src/components/AuthButton.astro
```

组件应：

用户未认证时显示“登录”按钮
用户已认证时显示用户显示名称、头像（基于首字母）和“登出”按钮
检查认证状态时显示加载状态
样式与站点现有设计匹配（读取现有CSS变量/主题）

5.2 Integrate into Navigation

5.2 集成到导航栏

Find the site's navigation component and integrate the auth button:

Search for the nav/header component in the site's source code
Import the AuthButton component
Add it to the navigation bar (typically in the top-right area)

Do NOT replace the existing navigation — add the auth button alongside existing nav items.

找到站点的导航组件并集成认证按钮：

在站点源码中搜索导航/头部组件
导入AuthButton组件
将其添加到导航栏中（通常位于右上角区域）

请勿替换现有导航 — 将认证按钮添加到现有导航项旁。

5.3 Git Commit

5.3 Git提交

Stage and commit the auth files:

powershell

git add -A
git commit -m "Add authentication service and auth UI component"

暂存并提交认证文件：

powershell

git add -A
git commit -m "添加认证服务和认证UI组件"

Output

输出结果

Auth button component created for the detected framework
Auth button integrated into the site's navigation
Changes committed to git

已为检测到的框架创建认证按钮组件
已将认证按钮集成到站点导航栏中
变更已提交到git

Phase 6: Implement Role-Based UI

阶段6：实现基于角色的UI

Goal: Identify protected content areas and apply role-based authorization patterns to the site's components.

目标： 识别受保护内容区域并为站点组件应用基于角色的授权模式。

Actions

操作步骤

6.1 Identify Protected Content

6.1 识别受保护内容

Analyze the site's components to find content that should be role-gated:

Admin-only sections (dashboards, settings)
Authenticated-only content (profile, data views)
Role-specific features (edit buttons, create forms)

Present findings to the user and confirm which areas to protect.

分析站点组件，找到需要角色权限控制的内容：

管理员专属区域（仪表板、设置）
仅认证用户可见内容（个人资料、数据视图）
角色专属功能（编辑按钮、创建表单）

向用户展示分析结果并确认需要保护的区域。

6.2 Apply Authorization Patterns

6.2 应用授权模式

Based on the user's choices, wrap the appropriate components:

React example:

tsx

<RequireAuth fallback={<p>Please sign in to view this content.</p>}>
  <Dashboard />
</RequireAuth>

<RequireRole roles={['Administrators']} fallback={<p>Access denied.</p>}>
  <AdminPanel />
</RequireRole>

Vue example:

vue

<div v-role="'Administrators'">
  <AdminPanel />
</div>

Angular example:

typescript

{ path: 'admin', component: AdminComponent, canActivate: [authGuard, roleGuard], data: { roles: ['Administrators'] } }

根据用户选择，为相应组件添加包装：

React示例：

tsx

<RequireAuth fallback={<p>请登录以查看此内容。</p>}>
  <Dashboard />
</RequireAuth>

<RequireRole roles={['Administrators']} fallback={<p>访问被拒绝。</p>}>
  <AdminPanel />
</RequireRole>

Vue示例：

vue

<div v-role="'Administrators'">
  <AdminPanel />
</div>

Angular示例：

typescript

{ path: 'admin', component: AdminComponent, canActivate: [authGuard, roleGuard], data: { roles: ['Administrators'] } }

6.3 Git Commit

6.3 Git提交

Stage and commit:

powershell

git add -A
git commit -m "Add role-based access control to site components"

暂存并提交：

powershell

git add -A
git commit -m "为站点组件添加基于角色的访问控制"

Output

输出结果

Protected content areas identified and confirmed with user
Role-based authorization patterns applied to components
Changes committed to git

已识别受保护内容区域并获得用户确认
已为组件应用基于角色的授权模式
变更已提交到git

Phase 7: Verify Auth Setup

阶段7：验证认证设置

Goal: Validate that all auth files exist, the project builds, and the auth UI renders correctly.

目标： 验证所有认证文件是否存在、项目是否可构建、认证UI是否正常渲染。

Actions

操作步骤

7.1 Verify File Inventory

7.1 验证文件清单

Confirm the following files were created:

```
src/types/powerPages.d.ts
```
— Power Pages type declarations
```
src/services/authService.ts
```
— Auth service with login/logout functions
Framework-specific auth hook/composable (e.g.,
```
src/hooks/useAuth.ts
```
for React)
```
src/utils/authorization.ts
```
— Role-checking utilities
Framework-specific authorization components (e.g.,
```
RequireAuth.tsx
```
,
```
RequireRole.tsx
```
for React)
Auth button component (e.g.,
```
src/components/AuthButton.tsx
```
for React)

Read each file and verify it contains the expected exports and functions:

Auth service:

login

logout

getCurrentUser

isAuthenticated

fetchAntiForgeryToken

Authorization utils:

hasRole

hasAnyRole

hasAllRoles

getUserRoles

确认已创建以下文件：

```
src/types/powerPages.d.ts
```
— Power Pages类型声明
```
src/services/authService.ts
```
— 包含登录/登出函数的认证服务
框架特定的认证钩子/组合式函数（如React的
```
src/hooks/useAuth.ts
```
）
```
src/utils/authorization.ts
```
— 角色检查工具
框架特定的授权组件（如React的
```
RequireAuth.tsx
```
、
```
RequireRole.tsx
```
）
认证按钮组件（如React的
```
src/components/AuthButton.tsx
```
）

读取每个文件并验证其包含预期的导出内容和函数：

认证服务：

login

、

logout

、

getCurrentUser

、

isAuthenticated

、

fetchAntiForgeryToken

授权工具：

hasRole

、

hasAnyRole

、

hasAllRoles

、

getUserRoles

7.2 Verify Build

7.2 验证构建

Run the project build to catch any import errors, type errors, or missing dependencies:

powershell

npm run build

If the build fails, fix the issues before proceeding.

运行项目构建以捕获导入错误、类型错误或缺失依赖：

powershell

npm run build

若构建失败，修复问题后再继续。

7.3 Verify Auth UI Renders

7.3 验证认证UI渲染

Start the dev server and verify the auth button appears in the navigation:

powershell

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.

启动开发服务器并验证认证按钮是否出现在导航栏中：

powershell

npm run dev

使用Playwright导航到站点并截图，确认认证按钮可见：

导航到
```
http://localhost:<port>
```
截取浏览器截图
验证认证按钮（登录/模拟用户）出现在导航区域

若认证按钮不可见或页面存在渲染错误，修复问题。

Output

输出结果

All auth files verified (present and contain expected exports)
Project builds successfully
Auth UI renders correctly in the browser

所有认证文件已验证（存在且包含预期导出内容）
项目构建成功
认证UI在浏览器中正常渲染

Phase 8: Review & Deploy

阶段8：审核与部署

Goal: Create required site settings, present a summary of all work, and prompt for deployment.

目标： 创建所需的站点设置、展示所有工作内容的总结、提示部署。

Actions

操作步骤

8.1 Create Site Setting

8.1 创建站点设置

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:

powershell

node "${CLAUDE_PLUGIN_ROOT}/scripts/generate-uuid.js"

Create

.powerpages-site/site-settings/authentication-registration-profileredirectenabled.yml

yaml

id: <UUID from generate-uuid.js>
name: Authentication/Registration/ProfileRedirectEnabled
value: false

站点需要将

Authentication/Registration/ProfileRedirectEnabled

设置为

false

，以防止Power Pages在用户登录后重定向到个人资料页面（代码站点中不存在此页面）。

检查

.powerpages-site/site-settings/

是否存在。若存在，创建站点设置文件：

powershell

node "${CLAUDE_PLUGIN_ROOT}/scripts/generate-uuid.js"

创建

.powerpages-site/site-settings/authentication-registration-profileredirectenabled.yml

：

yaml

id: <UUID from generate-uuid.js>
name: Authentication/Registration/ProfileRedirectEnabled
value: false

8.2 Record Skill Usage

8.2 记录技能使用情况

Reference:

${CLAUDE_PLUGIN_ROOT}/references/skill-tracking-reference.md

Follow the skill tracking instructions in the reference to record this skill's usage. Use

--skillName "SetupAuth"

参考：

${CLAUDE_PLUGIN_ROOT}/references/skill-tracking-reference.md

按照参考文档中的技能跟踪说明记录此技能的使用情况。使用

--skillName "SetupAuth"

。

8.3 Present Summary

8.3 展示总结

Present a summary of everything created:

Component	File(s)	Status
Type Declarations	`src/types/powerPages.d.ts`	Created
Auth Service	`src/services/authService.ts`	Created
Auth Hook/Composable	`src/hooks/useAuth.ts` (or framework equivalent)	Created
Authorization Utils	`src/utils/authorization.ts`	Created
Auth Components	`RequireAuth` , `RequireRole` (or framework equivalent)	Created
Auth Button	`src/components/AuthButton.tsx` (or framework equivalent)	Created
Site Setting	`ProfileRedirectEnabled = false`	Created

展示所有已创建内容的总结：

组件	文件	状态
类型声明	`src/types/powerPages.d.ts`	已创建
认证服务	`src/services/authService.ts`	已创建
认证钩子/组合式函数	`src/hooks/useAuth.ts` （或框架等效文件）	已创建
授权工具	`src/utils/authorization.ts`	已创建
授权组件	`RequireAuth` 、 `RequireRole` （或框架等效组件）	已创建
认证按钮	`src/components/AuthButton.tsx` （或框架等效组件）	已创建
站点设置	`ProfileRedirectEnabled = false`	已创建

8.4 Ask to Deploy

8.4 询问是否部署

Use

AskUserQuestion

Question	Options
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

/deploy-site

If "No": Remind the user:

"Remember to deploy your site using
/deploy-site
when you're ready. Authentication will not work until the site is deployed with the new site settings."

使用

AskUserQuestion

：

问题	选项
认证与授权已配置完成。要使登录功能生效，需要部署站点。是否现在进行部署？	是，立即部署（推荐）, 否，我稍后自行部署

若选择“是，立即部署”：调用

/deploy-site

。

若选择“否”：提醒用户：

"请记得在准备就绪后通过
/deploy-site
部署站点。在新站点设置部署完成前，认证功能无法正常工作。"

8.5 Post-Deploy Notes

8.5 部署后注意事项

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
```
/integrate-webapi
```
for actual data security
Local development: The auth service includes mock data for testing on localhost — remove or disable before production

部署完成后（或用户选择跳过部署），提醒用户：

在部署站点上测试：认证仅在已部署的Power Pages站点上生效，
```
localhost
```
环境不生效
Entra ID配置：必须在Power Pages管理中心配置站点的身份提供商以使用Microsoft Entra ID
分配Web角色：必须在Power Pages管理中心为用户分配相应的Web角色
表权限：客户端认证检查仅用于用户体验 — 请通过
```
/integrate-webapi
```
配置服务器端表权限以实现实际的数据安全
本地开发：认证服务包含用于localhost测试的模拟数据 — 生产环境前请移除或禁用

Output

输出结果

```
ProfileRedirectEnabled
```
site setting created
Full summary presented to user
Deployment prompted (or skipped with reminder)
Post-deploy guidance provided

已创建
```
ProfileRedirectEnabled
```
站点设置
已向用户展示完整总结
已提示部署（或用户选择跳过并收到提醒）
已提供部署后指导

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
Phase 7	Verify Auth Setup — validate files exist, build succeeds, auth UI renders
Phase 8	Review & Deploy — site setting, summary, deployment prompt

Update each task with

TaskUpdate

as phases are completed.

在开始时使用

TaskCreate

跟踪每个阶段：

任务	描述
阶段1	检查前置条件 — 验证站点、框架、部署状态、Web角色
阶段2	规划 — 收集需求并获得用户批准
阶段3	创建认证服务 — 认证服务、类型定义、框架钩子/组合式函数
阶段4	创建授权工具 — 角色检查函数和组件
阶段5	创建认证UI — AuthButton组件和导航集成
阶段6	实现基于角色的UI — 为组件应用授权模式
阶段7	验证认证设置 — 验证文件存在、构建成功、认证UI渲染正常
阶段8	审核与部署 — 站点设置、总结、部署提示

在完成各阶段后使用

TaskUpdate

更新任务状态。

Key Decision Points

关键决策点

Phase 1.3: Deploy now or stop? (site must be deployed before auth setup)
Phase 1.4: Create web roles now or skip? (roles needed for authorization)
Phase 1.5: Overwrite or skip existing auth files?
Phase 2.1: Which auth features to include? (login/logout, role-based, or both)
Phase 2.2: Approve plan or request changes?
Phase 6.1: Which content areas to protect with role-based access?
Phase 8.3: Deploy now or later?

Begin with Phase 1: Check Prerequisites

阶段1.3：立即部署还是终止？（配置认证前必须部署站点）
阶段1.4：立即创建Web角色还是跳过？（授权需要角色）
阶段1.5：覆盖还是跳过现有认证文件？
阶段2.1：需要哪些认证功能？（登录/登出、基于角色的访问控制，或两者兼具）
阶段2.2：批准方案还是要求修改？
阶段6.1：哪些内容区域需要通过角色访问控制保护？
阶段8.3：立即部署还是稍后部署？

从阶段1：检查前置条件开始执行