fusion-roles-cli

Fusion Roles CLI

适用场景

当需要从配置文件创建或更新 Fusion Roles V2 资源（角色、绑定、分配、作用域类型），或需要检查或导出已有角色状态时使用。

典型触发场景：

• “为我的服务部署角色配置”
• “根据这个 JSON 文件创建角色”
• “导出 fusion-myservice 的当前角色配置”
• “角色配置文件是什么样的？”
• “为这个 Entra 组添加绑定”
• “检查分配给此账户的角色”
• “试运行角色部署”

不适用场景

• 数据库预配——使用 fusion-infra-cli
• 管理 Azure AD 组本身——使用 Azure 门户或 Graph API
• Roles V1（旧版系统）——此工具仅面向 Roles V2
• 应用程序代码变更

前置条件

将 froles 安装为 .NET 全局工具：

dotnet tool install --global \
  --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" \
  Fusion.Roles.Cli

更新到最新版本：

froles --update

身份验证会自动使用 DefaultAzureCredential（获取 az login 会话）。传入 -t <token> 可覆盖。

核心工作流——部署角色配置

1. 创建配置文件

配置文件是一个 JSON 文件，用于声明系统的所有角色资源。务必包含 $schema 引用，以启用编辑器验证和自动补全。

最简示例（roles-config.json）：

{
  "$schema": "https://rolesv2.api.fusion.equinor.com/public/schemas/role-config.schema.json",
  "accessRoles": [
    {
      "systemIdentifier": "my-service",
      "name": "MyService.Project.Read",
      "description": "Read access to project resources"
    }
  ],
  "roles": [
    {
      "name": "project-viewer",
      "displayName": "Project Viewer",
      "accessRoleMappings": [
        { "accessRoleIdentifier": "MyService.Project.Read" }
      ]
    }
  ]
}

如需了解包含所有资源类型和字段定义的完整架构，请参阅 references/role-config-schema.md。

2. 试运行以验证变更

部署前务必先试运行，以发现意外变更：

froles create -e ci --file roles-config.json --dry-run

试运行会准确显示将要创建、修补或保持不变的内容，包括显示新增/移除角色的绑定差异。

3. 部署

# CI
froles create -e ci --file roles-config.json

# QA
froles create -e fqa --file roles-config.json

# Production
froles create -e fprd --file roles-config.json

create 具有幂等性，可以安全地重复运行。资源会根据自然键进行匹配；只有发生变化的字段才会被修补。

4. 导出当前状态（可选）

要导出系统的当前配置（适用于初始接入或审计）：

froles export my-service -e ci -o current-state.json

可以修改导出文件并将其传回 create。

对账行为

create 命令会根据自然键对账每种资源类型：

资源	自然键	行为
作用域类型	name	缺失时创建；若 description 发生变化则修补
访问角色	systemIdentifier + name	缺失时创建；若发生变化则修补
角色 / 可声明角色	name	缺失时创建；若发生变化则修补；访问角色映射会完全对账
绑定	identifier	修补所有字段；差异显示角色/组的新增和移除
角色分配	roleIdentifier + source + externalIdentifier	缺失时创建；若已存在则跳过

重要提示：角色/可声明角色上的访问角色映射会完全对账——配置中缺失的映射将被移除。只管理配置文件中声明的系统所属的访问角色。

环境

键	用途
ci	持续集成
fqa	QA / 预生产
fprd	生产
tr	培训环境

完整参考

如需完整的命令和标志参考，请运行：

froles --help
froles create --help

或参阅源文档：

• README.md
• USING_CREATE_COMMAND.md
• 源代码：tooling/fusion-roles-cli

安全

• 部署到生产环境前务必先试运行
• 访问角色映射对账会移除未映射的角色——请仔细检查试运行输出
• 切勿在配置文件中存储令牌；在流水线中始终通过机密变量使用 -t <token>
• delete role-assignments 具有破坏性——请先与用户确认并进行试运行