Role assignments

A role assignment binds a principal to a role at a scope. It applies at that scope and everything below it — see Scopes and inheritance.

Who can assign roles

You need rbac/members/write at the scope you assign at, and an Owner role — Owner or Platform Owner — at that scope or above it, assigned to you directly or held through an active just-in-time grant. Contributor does not have rbac/members/write and cannot assign roles.

Important

Owner held through a group does not count here. A member of a group that holds Owner sees Add role assignment, but the platform refuses the assignment with "Only users with an Owner role can assign permissions." The same applies to removing assignments, creating and changing custom roles, and deciding just-in-time requests.

Furthermore:

• Only a Platform Owner can assign or remove Platform Owner, and only one who holds Platform Owner through a permanent assignment made directly to them at /.
• Platform Owner, Platform Contributor, Platform Reader and LLM Gateway Consumer can only be assigned at the root scope /, which in practice means by a Platform Owner.
• Custom roles cannot be assigned at /.
• The principal must belong to the boundary's tenant — see Tenants and guests.
• The platform's own service principals cannot be given or relieved of roles.
• The same principal, role and scope can be assigned only once.

Assign a role

1. In the portal at https://portal.example.com, open Access control (IAM) in the boundary's sidebar and choose Add role assignment.
2. Member — type at least two characters of a name or email and pick the user, group or service principal. If nobody matches and you typed an email address, the sheet offers Invite … by email — see Users and invitations.
3. Role — pick the role. The built-in roles are described in Built-in roles; a boundary's custom roles are listed with them.
4. Scope — keep All resource groups (boundary scope) for the whole boundary, or pick a resource group, and optionally one resource in it. The platform roles are always assigned at the root, so no scope is offered for them.
5. Choose Add assignment.

The new assignment is in force within a minute or two.

To grant access on one resource only, you can also open the resource, go to its Access Control tab and choose Add role assignment. That dialog assigns at the resource itself and offers only roles that grant something on that type of resource. The boundary's Access Control tab does the same at boundary scope.

Tip

Searching a managed identity by name only looks at the first 20 identities, so it usually misses. Paste its Principal ID into the search field of a resource's or the boundary's Access Control tab instead — see Give a managed identity a role.

Change an assignment

On the Role assignments tab, choose the pencil next to an assignment, pick another role or scope and choose Save changes. The new assignment is created first and the old one removed afterwards.

Remove an assignment

Choose the bin next to the assignment and confirm with Remove. On a resource's Access Control tab only assignments made at that resource can be removed there; inherited ones are managed where they were made.

The Platform and System toggle on the Role assignments tab separates the platform's own service principals (System) from everyone else. Their assignments are read-only.

With the CLI

Find the principal and the role, then create the assignment:

stsh iam principal alice
stsh iam role list
stsh iam assignment create \
  --set principalId=<principal-id> \
  --set principalType=User \
  --set roleDefinitionId=<role-id> \
  --set scope=/boundaries/<boundary-id>/resourcegroups/web

principalType is User, Group or ServicePrincipal. List and remove assignments with stsh iam assignment list and stsh iam assignment delete <assignment-id>.