power-bi-security

Power BI 安全技能

管理 Power BI 模型的行级安全性（RLS）和透视。

前提条件

pipx install pbi-cli-tool
pbi-cli skills install
pbi connect

安全角色（RLS）

# List all security roles
pbi security-role list

# Get role details
pbi security-role get "Regional Manager"

# Create a new role
pbi security-role create "Regional Manager" \
  --description "Restricts data to user's region"

# Delete a role
pbi security-role delete "Regional Manager"

透视

透视用于控制用户可见的表和列：

# List all perspectives
pbi perspective list

# Create a perspective
pbi perspective create "Sales View"

# Delete a perspective
pbi perspective delete "Sales View"

工作流：设置 RLS

# 1. Create roles
pbi security-role create "Sales Team" --description "Sales data only"
pbi security-role create "Finance Team" --description "Finance data only"

# 2. Verify roles were created
pbi --json security-role list

# 3. Export full model for version control (includes roles)
pbi database export-tmdl ./model-backup/

工作流：创建面向用户的透视

# 1. Create perspectives for different audiences
pbi perspective create "Executive Dashboard"
pbi perspective create "Sales Detail"
pbi perspective create "Finance Overview"

# 2. Verify
pbi --json perspective list

常见 RLS 模式

基于区域的安全性

创建一个按已认证用户所在区域进行筛选的角色：

pbi security-role create "Region Filter" \
  --description "Users see only their region's data"

然后，在模型中通过 TMDL 或 Power BI Desktop 使用 DAX 筛选表达式定义表权限。

基于部门的安全性

pbi security-role create "Department Filter" \
  --description "Users see only their department's data"

经理层级结构

pbi security-role create "Manager View" \
  --description "Managers see their direct reports' data"

最佳实践

• 创建名称清晰且具有描述性的角色
• 始终添加说明，解释访问限制
• 将模型导出为 TMDL 以进行版本控制（pbi database export-tmdl）
• 在发布到生产环境前，彻底测试 RLS
• 使用透视简化面向不同用户群体的模型
• 在外部记录角色与组的映射关系（在 Power BI Service 中，RLS 角色映射到 Azure AD 组）
• 使用 --json 输出进行自动化安全审计：pbi --json security-role list

---

注意事项

• **USERPRINCIPALNAME() 在 Desktop 和 Service 中返回的值不同：**Desktop 返回已登录用户的 AAD UPN；Service 返回嵌入式令牌中的 UPN，对于来宾用户或 B2B 身份，两者可能不同。在本地测试通过的 RLS 可能会在 Service 中悄然失效。
• **security-role create 只会创建角色框架 — 必须通过 TMDL 或 Desktop 添加表筛选表达式：**没有筛选表达式的角色在 Service 中会显示为“已应用”，但会返回所有行。创建角色后，务必导出 TMDL 并确认每个表都包含预期的 tablePermission 块。
• **对象级安全性与透视并不相同：**透视只会在字段列表中隐藏对象；用户仍可通过 DAX 查询隐藏的表或列。若要实现真正的安全性，请使用 OLS（在 TMDL 中编码为 metadataPermissions）— 透视仅用于改善用户体验。
• **RLS 角色在 Service 中映射到 AAD 组，而非个人用户：**在 Desktop 中将 [email protected] 直接添加到角色有效，但当用户离开组织后，这种做法在 Service 中很脆弱。务必绑定到组；由于 TMDL 只记录角色名称，因此应在外部记录角色与组的映射关系。
• **使用 LOOKUPVALUE 在用户映射表上实现动态 RLS，容易受到刷新滞后的影响：**如果新用户已添加到映射表，但数据集尚未刷新，该用户将看不到任何行，且不会出现错误。刷新计划必须与用户入职节奏相协调。
• **security-role delete 会一次性删除角色及其所有筛选表达式：**不会进行部分清理；如果报表依赖该角色，也不会发出警告。务必先导出 TMDL — 凭记忆恢复复杂的多表角色会很麻烦。