Understanding the Boundary Identity and Access Management Model

Learn how the domain model works in HashiCorp Boundary and how it approaches IAM.

In this article, we will look at HashiCorp Boundary, and in particular, we'll look at what scopes are, how they work, and their role in the domain model. We will also explore how Boundary approaches Identity and Access Management (IAM) and its relationship to scopes.

HashiCorp Boundary is an open source project announced at HashiConf Digital 2020 that enables users to securely access dynamic hosts and services with fine-grained authorization. It is designed to manage session connectivity to infrastructure; giving security, operations, and engineers visibility and access to dynamic infrastructure in a controlled manner. To learn more about the fundamentals of Boundary, HashiCorp co-founder and co-CTO, Armon Dadgar, has put together a whiteboard introduction video that explains its concepts in detail.


When conducting threat modeling exercises, it is common practice for identified risks to be mitigated by reducing their potential blast radius, which in turn reduces the attack surface. Boundary uses the concept of Scopes to help security operators achieve this type of mitigation.  A scope can be thought of as a container. Each scope has a permissions boundary that is isolated from other scopes at the same level, creating a defined blast radius.

The diagram below is a visual representation of the relationship between the different levels of scopes.

Diagram of the relationships between the different levels of Boundary scopes.

The top level scope is the global scope. Boundary administrators operate at this level to configure and manage Boundary for the entire business. At this level, they can manage child scopes, auth methods, users, groups, roles, and grants.

Below this, there are organizations, also referred to as orgs, which are a child scope of global.  Although the implementation can be flexible for organization scopes, a good use case here would be to scope by business units. An example of this would be creating organizations for the development team, operations team, and support team. This would give you a clear separation of concerns for each of the business units.

The lowest scope level is the project scope. An organization scope can have as many projects as they require based on their business workflows. To expand on the example used earlier, the development team organization could have project scopes for their different products. For example, they could have the following project scopes:

  • Product 1
  • Product 2
  • Product 3


As mentioned earlier, IAM is handled at the organization and global scope levels. Here, operators can create and manage principals. Principals are entities in Boundary that are either users or groups that can be assigned capabilities.

Users are tied to a single organization scope and can be placed in groups to ease the management of access control. Groups can contain users from different organizations or global scopes, which makes permissioning much simpler to implement without having to create multiple users for a single entity.

An auth method is the mechanism in Boundary used for authentication. An organization can have zero to many authentication methods associated with it. Currently Password is the only auth method supported in Boundary. Within an auth method, accounts can be created and tied to users. An account for the password auth method consists of a login name and password.  Once tied to a user, the principal can authenticate in Boundary using the username and password pairing.

Access Management

Boundary’s approach to access management starts at the bottom level with Actions. Actions are capabilities that can be performed against Boundary resources. Boundary supports generic Actions such as, Create, Read, Update, Delete, and List. However, there are many more that are resource-type-specific actions that can be used in grants.

The next level up is a Grant. A grant in Boundary contains an action(s) and the resource(s) that the action(s) are permitted to be performed against. This can be thought of like a rule. An example grant would specify the List Action against resource X. Grants can specify resource types or resource IDs.

Above the grants, Boundary has the concept of Roles. Roles are a collection of zero or more grants. Roles belong to a single scope and their lifecycle is dependent on the existence of that scope. Should the scope be deleted, the role would be deleted too. Roles are assigned to principals (users and groups) and govern what actions they are authorized to perform.

The diagram below illustrates the relationship between the different IAM components in Boundary.

Diagram illustrates the relationship between the different IAM components in Boundary

Next Steps

Hopefully this gives you a glimpse into how the HashiCorp Boundary domain model works. To remove the manual work of setting each piece up, all of the components mentioned in this blog can be managed using the Boundary Terraform provider. Operators can then use Terraform to provision and manage their infrastructure state through automation.

Using Terraform to manage Boundary introduces new possibilities for workflows. For example, operators can dynamically build up their Boundary Host Catalogs when they provision their infrastructure. To learn more, please visit the provider documentation on the Terraform Registry.

Sign up for the latest HashiCorp news