Assigning scopes, principals, roles and grants

Scopes

In Boundary, scopes help in structuring and managing principals. They provide a framework for organizing resources and permissions that enables effective identity and access management. Scopes are structured hierarchically, with three main levels:

• Global - the highest-level scope of Boundary where administrators configure and manage Boundary for the entire company.
• Organization - organization scopes are contained in the global scope and are typically used to represent business units, organizations, or departments. Organization scopes can also be used to contain multiple production-level auth methods in separate scopes.
• Project - project scopes are contained in Organization scopes and be used to separate different business workflows. For example, projects can be used to represent different teams, products, or environments.

Assigning principals

In Boundary, principals refer to entities that can be assigned roles and granted permissions. The main types of principals in Boundary are:

• Users: These are individual accounts representing human users or machines. Users can be associated with one or more accounts via authentication methods.
• Groups: These are collections of users. A group can include multiple users, allowing for easier management of permissions by assigning roles to the group rather than individual users.
• Managed Groups: Managed groups are typically used in conjunction with identity providers like LDAP or OIDC, where membership is determined based on authentication attributes.

These principals can be assigned to roles, which define the permissions they have within Boundary. Each principal is identified by a unique ID, which is used when assigning them to roles.

Assigning roles to managed groups

We recommend adding a user to a group, and then adding the group to the role(s), instead of adding the user directly to the role(s). This way, you can manage multiple users at the same time, and it is easier to change the permissions of the user by adding/removing them from groups. You can manage OIDC/LDAP users and managed groups the same way, directly in the identity provider.

Roles are collections of capability grants, which are permissions allow roles to take actions and access resources.

1. Create a role
   • Firstly, you need to create a role within Boundary. Roles can be defined at the global, organization, or project scopes. A role is a collection of grants that can be assigned to principals, which include respective managed groups.
2. Assign principals to the role
   • Once the role is created, you can assign managed groups as principals to that role. This is done by adding the unique ID of the managed group to the role's principal IDs. This step effectively links the managed group to the role, allowing its members to inherit the permissions defined by the role.

Grant permissions to roles

With the managed group created and automatically managing group membership based on auth methods configured, the next step is to define grants for those principals which are your managed groups.

1. Define grants: Grants are defined using grant strings, which specify the actions that can be performed on resources. When you define grants permissions, please consider RBAC and Principle of Least Privilege (PoLP) in mind. These grant strings are added to the role. All grants take one of four forms: ID only, type only, pinned ID, or wildcards. The following is an example of a grant string:

   ids=<id>;type=<type>;actions=<action list>;output_fields=<fields list>
   
   • ids: Specifies the resource IDs the grant applies to. Wildcards can be used to apply the grant to all resources of a type.
   • type: Specifies the type of resource, such as host-catalog, auth-method, group, etc.
   • actions: Specifies the actions allowed on the resources, such as read, list, create, etc.
   • output_fields: Specifies which fields of the resource should be visible.

2. Assign Grants to the Role: After defining the grants, they are assigned to the role. This process involves specifying the grant strings in the role configuration. Once the grants are assigned, the managed group (as a principal) will have permissions to perform the specified actions on the resources.

Example scenario

In our example scenario, we will start with creating the following roles at the Global scope level for boundary administrators and boundary viewers:

Global scope roles:

• boundary_global_admin role has the grant of:

  ids=*;type=*;actions=*
  

• boundary_global_viewer role has the grant of:

  ids=*;type=*;actions=read,list
  

The next step is that we will create a role at the Organization level scope to manage the organization and roles at the Project level scope for multiple projects within an organization, and also the roles to access the targets. (Note: You can scale multiple organizations, and multiple projects based on your organizational structures.)

Organization scope role for PLATFORM_ORG:

• platform_org_admin role has the grant of:

  ids=*;type=*;actions=*
  

Project scope role for INFRA_PROJECT:

• infra_project_support role has the grant of:

  ids=*;type=target;actions=list,read,authorize-session
  ids=*;type=session;actions=read:self,cancel:self,list
  

Project scope role for PRODUCT1_PROJECT:

• dev_project1_support role has the grant of:

  ids=*;type=target;actions=list,read,authorize-session
  ids=*;type=session;actions=read:self,cancel:self,list
  

Useful resources

• Refer to Assignable permissions for more information about the permissions you can assign to Boundary principals.
• Refer to Permission grant formats for more information about grant strings and example formats.
• Refer to Manage roles and permissions for instructions to configure roles and grant scopes for principals.
• Refer to the Resource table for a cheat sheet to help you manage your permissions.