Using role scope
Overview
This topic explains how to work with role scope for custom roles.
This topic includes:
- Background information on resources, role scope, and role attributes
- How to define role scope using a role attribute
- How to set a role attribute value when you assign a role to a member or team
Background: Resources, role scope, and role attributes
When you create a new role, you can specify resources that the role can or cannot access in the following ways:
Types of resources a role can access | Example |
---|---|
All instances of the resource. | All projects |
All instances of the resource with a few exceptions. | All projects except “Project A” |
Only specific instances of the resource, where the instances are named explicitly in the role’s policy statements. | ”Project A,” “Project B,” and “Project C” |
Only specific instances of the resource, where the instances have a particular tag. To learn more, read Tags. | All projects with the “development” tag. |
Only specific instances of the resource, where the instance properties match a particular value. | All environments that are marked as critical. To learn more, read Property-based selectors. |
Only specific instances of the resource, where the instances are specified based on a parameter. This parameter is called a role attribute. In this option, you define the role attribute when you create the custom role, and you specify its value when you assign the role to an account member or team. For example, you can define the role attribute as “developerProjectKey,” set the value of the role attribute to “Project A” when you assign the role to member A, and then set the value of the role attribute to “Project B” when you assign the role to member B. This option is discussed in more detail in the sections below: Define role scope using attribute key, Set role attribute values. | ”developerProjectKey” |
Define role scope using attribute key
If multiple members or teams should have similar permissions, but work with different resources, then defining role scope using an attribute key lets you reuse the same role for many members or teams. This means the total number of roles in your account is much smaller, and much easier to maintain.
To define role scope using a role attribute when you create a new role policy:
- From the “New role” page, click Advanced to open the “Scope using attribute key” section:
- Click + Add resource type.
- Select a resource type from the menu, for example, “Project.”
- At the prompt, enter a key for the role attribute:
- The role attribute is now a parameter for this role.
- In the role’s policy statements, use the role attribute key any place that you would normally use a specific instance of that resource. For example, if you selected the “Project” resource type in step 3, then you can use the role attribute to allow access only to projects:
- Click Create role.
You set the value of the role attribute when you assign this role to a member or team. In this example, you would enter values for one or more project keys when you assign this role. To learn how, read Set role attribute values, below.
To learn more about creating custom roles, read Creating custom roles and policies.
Set role attribute values
You set a role attribute value, or specific resource, when you assign a role to an account member or team. In the “Assign access” dialog, enter the values for the role attribute in the Resources field:
You can enter one or more values when you set the role attribute. For example, you can set the value of the role attribute to projectA
(the project key of “Project A”) when you assign the role to one member, and then set the value of the role attribute to projectB
and projectC
(the project keys of “Project B” and “Project C”) when you assign the role to a different member.
You can also use the REST API: Custom roles.
In the REST API, use the syntax ${roleAttribute/<attributeKey>}
, for example ${roleAttribute/developerProjectKey}
, in your policy statements.
To learn more about assigning roles to account members, read Adding member roles. To learn more about assigning roles to teams, read Managing team permissions.