fusion-roles-cli

# Fusion Roles CLI ## When to use Use when Fusion Roles V2 resources (roles, bindings, assignments, scope types) need to be created or updated from a config file, or when existing role state needs to be inspected or exported. Typical triggers: - "Deploy the roles config for my service" - "Create roles from this JSON file" - "Export the current role config for fusion-myservice" - "What does a roles config file look like?" - "Add a binding for this Entra group" - "Check what roles are assigned to this account" - "Dry-run the role deployment" ## When not to use - Database provisioning — use `fusion-infra-cli` - Managing Azure AD groups themselves — use the Azure portal or Graph API - Roles V1 (legacy system) — this tool targets Roles V2 only - Application code changes ## Prerequisites Install `froles` as a .NET global tool: ```bash 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 ``` Update to latest: ```bash froles --update ``` Auth uses `DefaultAzureCredential` automatically (picks up `az login` session). Pass `-t <token>` to override. ## Core workflow — deploy a role config New to Roles V2? Read [references/concepts.md](references/concepts.md) first: system, access role, scope type, role, claimable role, assignment, binding, and when to use global or scoped access. ### 1. Create the config file The config file is a JSON file declaring all role resources for your system. Always include the `$schema` reference — it enables editor validation and autocompletion. Minimal example (`roles-config.json`): ```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" } ] } ] } ``` See [references/role-config-schema.md](references/role-config-schema.md) for the full schema with all resource types and field definitions. For an app repo, split the config per environment and concern (`roles.<env>.json`, `bindings.<env>.json`, `access-assignments.<env>.json`) and apply them in that order. See [references/file-layout.md](references/file-layout.md) for the layout, deploy order, reconcile flags, scoped vs global roles, and naming. ### 2. Dry-run to verify changes Always dry-run before deploying to catch unexpected changes: ```bash froles create -e ci --file roles-config.json --dry-run ``` The dry-run reads the current state from the server (GET requests, so you need access to the target environment) and prints what would be created, patched or left unchanged, including binding diffs. It sends no create, update or delete requests. ### 3. Deploy ```bash # 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` is **idempotent** — safe to run repeatedly. Resources are matched on natural keys; only changed fields are patched. ### 4. Export current state (optional) To export the current configuration for a system (useful for initial onboarding or auditing): ```bash froles export my-service -e ci -o current-state.json ``` The export file can be modified and fed back into `create`. ## Reconciliation behaviour The `create` command reconciles each resource type against its natural key: | Resource | Natural key | Behaviour | |----------|------------|-----------| | Scope types | `name` | Create if missing; patch `description` if changed | | Access roles | `systemIdentifier` + `name` | Create if missing; patch if changed | | Roles / claimable roles | `name` | Create if missing; patch if changed; access role mappings fully reconciled | | Bindings | `identifier` | Patch all fields; diff shows role/group additions and removals | | Role assignments | `roleIdentifier` + `source` + `externalIdentifier` | Create if missing; skip if exists; delete only with `--reconcile-assignments` | **Important**: Access role mappings on roles/claimable roles are **fully reconciled** — mappings absent from the config are removed. Only access roles belonging to systems declared in the config file are managed. Bindings and assignments are only deleted with `--reconcile-bindings=<system>` / `--reconcile-assignments[=<system>]` (see [references/file-layout.md](references/file-layout.md)). ## Environments | Key | Purpose | |-----|---------| | `ci` | Continuous integration | | `fqa` | QA / pre-production | | `fprd` | Production | | `tr` | Training environment | ## Full reference For complete command and flag reference, run: ```bash froles --help froles create --help ``` Or see the source documentation: - [README.md](https://github.com/equinor/fusion-core-services/blob/main/tooling/fusion-roles-cli/Fusion.Roles.Cli/README.md) - [USING_CREATE_COMMAND.md](https://github.com/equinor/fusion-core-services/blob/main/tooling/fusion-roles-cli/Fusion.Roles.Cli/USING_CREATE_COMMAND.md) - [Source: tooling/fusion-roles-cli](https://github.com/equinor/fusion-core-services/tree/main/tooling/fusion-roles-cli) ## Safety - Always dry-run before deploying to production - Access role mapping reconciliation removes unmapped roles — review the dry-run output carefully - `--reconcile-bindings` / `--reconcile-assignments` delete entries missing from the file — use only on complete files, dry-run first, confirm with the user - `--dry-run` only reads from the server; it skips all writes, so it cannot catch API validation errors. Apply to `ci` before `fprd` - Never store tokens in config files; always use `-t <token>` from a secret variable in pipelines - `delete role-assignments` is destructive — confirm with user and dry-run first