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:

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:

froles --update

Auth uses DefaultAzureCredential automatically (picks up az login session). Pass -t <token> to override.

Core workflow — deploy a role config

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

{
  "$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 for the full schema with all resource types and field definitions.

2. Dry-run to verify changes

Always dry-run before deploying to catch unexpected changes:

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

The dry-run shows exactly what will be created, patched, or left unchanged — including binding diffs showing added/removed roles.

3. Deploy

# 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):

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

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.

Environments

Key	Purpose
`ci`	Continuous integration
`fqa`	QA / pre-production
`fprd`	Production
`tr`	Training environment

Full reference

For complete command and flag reference, run:

froles --help
froles create --help

Or see the source documentation:

Safety

Always dry-run before deploying to production
Access role mapping reconciliation removes unmapped roles — review the dry-run output carefully
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