Scopes are a foundational part of Boundary. By modeling permission boundaries as a container, scopes allow users to partition resources and assign ownership of resources to principals.
There are three types of scopes within Boundary:
- Global (
Within the software itself and in the documentation, Boundary uses org instead of organization to remove ambiguity between different regional spellings of the word.
globalscope is the outermost scope. There is only one
globalscope, and it cannot be deleted. It is the entry point for initial administration, setup, and management of the org scopes.
globalscope can contain multiple org scopes. Orgs are used to hold IAM-related resources and project scopes.
- Each org scope can contain multiple project scopes. Projects are used to hold infrastructure-related resources.
Some resources can only be associated with a specific level of scope. For example, targets can only be created within a project, while users can be created at the global-level or an org-level. See the domain model for detailed resource-specific information.
In this tutorial, you will create two scopes: an org and a project.
All resource IDs in this tutorial are illustrations only. IDs are uniquely
generated for every resource upon creation, except for the resources generated
dev mode. Be sure to use the resource IDs generated for your
environment. For example, if you execute
boundary users create, use the
resource ID of the user printed in
stdout, not the ID in the example
To perform the tasks described in this tutorial, you need to have a Boundary
environment. Refer to the Getting
Started tutorial to learn about
installation and Boundary's
To complete this tutorial, you need:
A Boundary binary in your
PATH. This tutorial uses the 0.8.1 version of Boundary.
Boundary must be running in
Terraform 0.13.0 or greater provides an optional workflow for these tutorials. The binary must be available in your
PATH. A Recovery Key must also be copied from the output of
boundary dev. See the tutorial introduction if you do not have a recovery key.
Start by creating an org under the
The CLI and Admin Console create administrative roles automatically when a scope is generated. This allows the user that created the scope to immediately manage it.
Log in to Boundary as the admin user.
$ boundary authenticate password -auth-method-id ampw_1234567890 -login-name admin Please enter the password (it will be hidden): <password> Authentication information: Account ID: acctpw_1234567890 Auth Method ID: ampw_1234567890 Expiration Time: Fri, 03 Jun 2022 10:40:20 MDT User ID: u_1234567890 The token was successfully stored in the chosen keyring and is not displayed here.
Create a new org under the
global scope named "IT_Support" with the
description "IT Support Team".
$ boundary scopes create -scope-id=global -name=IT_Support -description="IT Support Team" Scope information: Created Time: Fri, 27 May 2022 10:40:27 MDT Description: IT Support Team ID: o_u54jrD6ydN Name: IT_Support Updated Time: Fri, 27 May 2022 10:40:27 MDT Version: 1 Scope (parent): ID: global Name: global Type: global Authorized Actions: no-op read update delete
List the existing scopes.
$ boundary scopes list Scope information: ID: o_1234567890 Version: 1 Name: Generated org scope Description: Provides an initial org scope in Boundary Authorized Actions: no-op read update delete ID: o_u54jrD6ydN Version: 1 Name: IT_Support Description: IT Support Team Authorized Actions: no-op read update delete
In this example, the generated scope ID for IT_Support is
Notice that org ID starts with
Copy the ID of the
IT_Support org and save it as the environment variable
$ export ORG_ID=<IT_Support_Org_ID>
$ export ORG_ID="o_u54jrD6ydN"
Next, create a new project named QA_Tests under the "IT_Support" scope with the description "Manage QA machines".
To create a project under the
IT_Support org, execute the
$ boundary scopes create -scope-id=$ORG_ID -name=QA_Tests -description="Manage QA machines" Scope information: Created Time: Fri, 27 May 2022 10:43:28 MDT Description: Manage QA machines ID: p_oMgeFL2hP6 Name: QA_Tests Updated Time: Fri, 27 May 2022 10:43:28 MDT Version: 1 Scope (parent): ID: o_u54jrD6ydN Name: IT_Support Parent Scope ID: global Type: org Authorized Actions: no-op read update delete
List the project under the
IT_Support org to verify.
$ boundary scopes list -scope-id=$ORG_ID Scope information: ID: p_oMgeFL2hP6 Version: 1 Name: QA_Tests Description: Manage QA machines Authorized Actions: no-op read update delete
In this example, the generated project ID is
p_MoXk2hMkhW. Notice that project
ID starts with
Copy the ID of the
QA_Tests project and save it as an environment variable,
$ export PROJECT_ID=<QA_Tests_Project_ID>
$ export PROJECT_ID="p_oMgeFL2hP6"
You created a new org, IT_Support which has the QA_Tests project. Those new scopes can help create logical groupings of Boundary resources such as targets, users, groups, and roles.
You are now ready to define scope-level resources and manage them per scope. Next, the Manage Targets tutorial demonstrates adding Targets to Boundary.