Custom roles

When no built-in role fits, a boundary Owner can define one. A custom role belongs to its boundary: it is listed and assignable there, at the boundary, a resource group or a resource, but never at the root scope /.

Create a role

You need rbac/members/write, and Owner on the boundary or Platform Owner, assigned to you directly or held through an active just-in-time grant. Owner through a group is not enough: the platform refuses the role.

1. In the portal at https://portal.example.com, open Access control (IAM), go to Roles and choose Create custom role.

2. Basics — a Name (up to 128 characters, unique on the whole platform) and an optional Description.

3. Permissions — four lists, each a searchable checklist of the platform's actions grouped by area:

   • Allowed actions — the control-plane actions the role grants;
   • Excluded actions (NotActions) — actions to take back out of the allowed ones, useful with wildcards;
   • Allowed data actions — data actions such as secretvault/readSecrets or apps/readLogs;
   • Excluded data actions — data actions to take back out.

   Under Custom patterns you can add a wildcard pattern such as apps/* instead of ticking actions one by one.

4. Review shows the lists and the Assignable scope, which is the boundary. Choose Create role.

The portal opens the new role. Assign it like any other — see Assign a role.

Rules for the action lists

• Every action must exist in the platform's catalogue; a misspelt action is refused.
• Wildcards follow the matching rules in Actions and data actions: apps/* covers every Apps action, */read only two-part actions ending in read.
• */* is reserved for Platform Owners who hold the role through an assignment made directly to them at /.
• The role needs at least one action in Allowed actions. A role with data actions only is refused when you create it.
• X/write also grants X/delete. To grant writing without deleting, allow X/write and exclude X/delete.

A role people use in the portal usually also needs the reads the built-in scoped roles carry, or the pages it opens stay empty: boundaries/read, resourcegroups/read, kernel/operations/read, kernel/resourceStatus/read, kernel/activity/write, monitoring/read and search/read.

Clone a role

On the Roles tab, open a role's menu and choose Clone, or choose Clone on the role's page. The wizard opens with the role's lists filled in and the name followed by (copy). Cloning a built-in role is the quickest way to a variant of it.

The role as JSON

A role's page has three tabs: Permissions, Assignments — who holds the role, and where — and JSON, the full definition. The same shape creates a role through the CLI or the API:

{
  "name": "App Deployer",
  "description": "Deploy and scale apps, but not delete them.",
  "actions": ["apps/read", "apps/write", "apps/scale", "boundaries/read", "resourcegroups/read"],
  "notActions": ["apps/delete"],
  "dataActions": ["apps/readLogs"],
  "notDataActions": [],
  "assignableScopes": ["/boundaries/<boundary-id>"]
}

stsh iam role create --file app-deployer.json

Change or delete a role

The portal does not edit a custom role. Change it through the CLI or the API with the full definition — stsh iam role update <role-id> --file app-deployer.json — and the change applies to every assignment of the role. The same rules as for creating apply.

A custom role can only be deleted while nobody holds it: remove its assignments first (they are listed on its Assignments tab), then choose Delete. Built-in roles cannot be changed or deleted.

Note

The platform keeps every just-in-time request, whatever its status. A custom role that has ever been requested as just-in-time access therefore cannot be deleted: the deletion fails with an internal error, even when every request for it has long expired. The Assignments tab does not list just-in-time requests.