dv-security

技能：安全 — 角色分配与自我提权

**此技能使用一方 CLI——通过 PAC CLI 更改角色，通过 Dataverse CLI 验证。**请勿编写 Python 脚本来执行角色操作。

运行前预览

角色授权和自我提权具有破坏性（会改变安全态势，并记录到 Purview）。运行前，先用普通文字预览要执行的操作——目标用户、角色、环境——对于任何未知信息，请使用占位符（<ENV_URL>、<USER_EMAIL>），并在同一轮中请求确认和缺失值。省略原始 pac admin 代码块；用户不应为了批准安全变更而阅读 CLI 语法。

**核心原则：**用户应能从你的第一条回复中评估即将发生的操作。只问一句 “要使用哪个环境？” 不符合要求；用一句话预览则符合要求。

示例

分配角色（已提供用户，缺少环境）：

• ❌ “应该针对哪个环境？”
• ✅ “我将为 <ENV_URL> 上的 [email protected] 分配 System Administrator。请确认后继续，并提供目标环境 URL（或输入 ‘all’ 以列出并批量处理）。”

跨所有环境授予管理员访问权限：

• ❌ “请提供你的电子邮件地址。”
• ✅ “我将列出你的环境，然后在每个环境中并行地为 <YOUR_UPN> 分配 System Administrator。如果 assign-user 在任何环境中失败，我会对该环境改用自我提权（记录到 Purview）。请确认后继续，并提供你的 UPN。”

技能边界

需求	改用
创建或修改表、列、关系	dv-metadata
管理组织设置、审核、批量删除、保留策略	dv-admin
查询或读取记录	dv-query
写入、更新或删除记录	dv-data
租户级治理（DLP、环境生命周期）	pac admin --help

先决条件

• 已安装并完成身份验证的 PAC CLI（pac auth create）
• 目标环境中的 System Administrator 角色（或用于自我提权的 Global/PP/D365 Admin）
• 活动的身份验证配置文件：pac auth list
• 无头 / 受限出口主机：SDK 处理角色 / 用户 / 业务部门操作；仅限 PAC 的操作使用服务主体；使用 python scripts/auth.py --check 验证出口连接。请参阅 dv-connect/references/headless-hosts.md。

---

为用户分配安全角色

pac admin assign-user --user <email-or-object-id> --role "System Administrator" --environment <url>

参数

参数	别名	必填	描述
--user	-u	是	用户电子邮件（UPN）或 Azure AD 对象 ID
--role	-r	是	安全角色名称（例如，System Administrator、Basic User）
--environment	-env	是	目标环境 URL 或 ID
--application-user	-au	否	将用户视为应用程序用户（服务主体）
--business-unit	-bu	否	业务部门 ID。默认使用调用者的业务部门

---

验证分配结果——退出代码 0 并非证明

pac admin assign-user 即使失败也会以 0 退出（环境无法解析、角色名称错误、用户未知）。切勿将正常退出视为成功。

1. **查看输出，而不只是退出代码。**即使运行失败也会以 0 退出，但会打印错误（environment ... not found、role ... does not exist）。如果输出包含错误，请停止。
2. 使用你指定的确切 --environment 进行确认——不要重新解析或缩短它；不同的 ID 可能会在错误的组织中静默“成功”。使用 Dataverse CLI 读取并查询用户的角色：

# Resolve the user's systemuserid, then list their assigned roles.
# --context carries plugin/skill/agent attribution on the managed CLI call.
dataverse api request --target dataverse --method GET \
  --path "/api/data/v9.2/systemusers?%24select=systemuserid&%24filter=internalemailaddress eq '[email protected]'" \
  --environment <same-url-as-assign> \
  --context "app=dataverse-skills/<ver>;skill=dv-security;agent=<agent>"
dataverse api request --target dataverse --method GET \
  --path "/api/data/v9.2/systemusers(<systemuserid>)/systemuserroles_association?%24select=name" \
  --environment <same-url-as-assign> \
  --context "app=dataverse-skills/<ver>;skill=dv-security;agent=<agent>"

如果首次查询没有返回行，登录身份可能位于 domainname（AAD UPN），而非 internalemailaddress（主要电子邮件地址）——请使用 %24filter=domainname eq '<upn>' 重试；如果你是通过对象 ID 分配的，则使用 azureactivedirectoryobjectid eq '<objectid>' 重试。缺少行并不能证明授权失败。

如果目标角色不存在，则分配未生效——请重新运行、查看输出，或改用自我提权。

---

批量工作流：为多个环境分配角色

并行运行，切勿按顺序运行：

Step 1: pac admin list                                              -> Get all environments
Step 2: Filter by type if needed (e.g., Developer, Sandbox)        -> Identify targets
Step 3: Confirm with user — show list of target environments
Step 4: Run ALL assignments in a single bash call:

pac admin assign-user --user [email protected] --role "System Administrator" --environment https://dev1.crm.dynamics.com &
pac admin assign-user --user [email protected] --role "System Administrator" --environment https://dev2.crm.dynamics.com &
pac admin assign-user --user [email protected] --role "System Administrator" --environment https://dev3.crm.dynamics.com &
wait

Step 5: Verify each landed (exit 0 is not proof — see above), then report ("Assigned + verified on 3/3 environments")

重要：分配角色前，务必确认会影响哪些环境，并验证每次分配是否成功；干净的退出代码并不能证明操作成功。

---

租户管理员自我提权（备用方案）

自我提权与为其他用户分配角色有实质区别。 pac admin assign-user <other> 是将权限授予其他人；pac admin self-elevate 则是将权限授予命令调用者。两者的风险状况和审计要求不同，因此自我提权的确认流程更加严格。

如果 pac admin assign-user 因“用户尚未分配任何角色”而失败，请使用：

pac admin self-elevate --environment https://myorg.crm.dynamics.com

• 需要全局管理员、Power Platform 管理员或 Dynamics 365 管理员权限
• 所有提权操作都会记录到 Microsoft Purview
• 如果省略 --environment，则使用当前活动的身份验证配置文件

自我提权确认流程（比 assign-user 更严格）

运行 pac admin self-elevate 前，Agent 必须：

1. 明确说明风险。 在运行前摘要中包含以下措辞（或意思相同的内容）：

   "此操作会授予你 <env> 的系统管理员权限。操作会连同你的身份和时间戳记录到 Microsoft Purview。"

2. 记录原因。 请用户用一句话说明原因，例如工单 ID、事件编号，或自由填写的备注，如 "dev sandbox access — no ticket"。在运行前摘要中复述该原因，让用户看到将被记录的内容。
3. 等用户看过上述 (1) 和 (2) 后再明确确认。 在屏幕上显示风险说明和原因之前，不得接受用户单独回复的“是”。
4. 不得静默回退。 如果 pac admin assign-user 失败，先说明失败情况，再按此流程提供 self-elevate 选项；绝不能自动串联执行。

流程：始终先尝试 pac admin assign-user。admin self-elevate 是文档中说明的备用方案，必须遵守上述流程。

CLI 备用方案：如果 pac admin self-elevate 报错，请通过 Power Platform 管理中心 → 选择环境 → 访问权限 → 系统管理员角色 手动进行自我提权。所有提权操作仍会记录到 Purview。（在 PAC CLI 2.6.4 中，该命令会因 CLI 向后端发送空的 api-version= 而失败，并报出 bolt.authentication.http.AuthenticatedClientException / ApiVersionInvalid。）

---

安全规则

• 分配系统管理员角色前，务必先确认
• 批量操作前，显示目标环境列表
• 自我提权会被记录并可供审计——请提醒用户