Initial configuration

After setting up a Boundary cluster, it's essential to perform initial configuration steps to ensure the environment is secure, functional, and ready for use. Below are the prerequisites and high-level steps you should follow.

Prerequisites

Boundary Enterprise

You have reviewed the Boundary Enterprise deployment guide and have a running Boundary cluster and the database has been initialized.
You have a valid recovery KMS as defined in the controller configuration file.

HCP Boundary

You have reviewed the HCP Boundary setup instructions and have a running HCP Boundary cluster.
You have authenticated to the HCP Boundary cluster using your admin credential.

High-level steps for initial configuration

Note

Steps 1-6 listed here apply only to the Boundary Enterprise version. For HCP Boundary, the system pre-creates the password-based authentication method, roles for global admin and anonymous users, and the global admin credentials during the HCP Boundary cluster setup.

Steps 7-9 apply to both HCP Boundary and Boundary Enterprise.

The commands below are run against the Boundary cluster. You can specify the Boundary cluster address using the -addr flag with the command or by exporting the BOUNDARY_ADDR environment variable before executing the commands.

For example, export BOUNDARY_ADDR=<HCP-BOUNDARY-CLUSTER-URL|BOUNDARY-ENT-CLUSTER-URL>

Authenticate with recovery KMS
- Start by authenticating to Boundary using the recovery KMS via the CLI. This grants you superuser privileges to configure initial resources. Please refer to log in with recovery KMS for detailed instructions.
Create an initial password auth method
- Set up a password-based authentication method at the Global scope level. This method should be used only for the initial setup, testing, or as a fallback mechanism if the primary auth method (e.g., LDAP or OIDC) fails or is unavailable.
- For example, run the below command to create a password auth method at the global scope level.
```
boundary auth-methods create password \
  -recovery-config /tmp/recovery.hcl \
  -scope-id 'global' \
  -name 'password' \
  -description 'Password auth method'
```
Create a login admin account
- Create a login account within the password authentication method. This account will be used to manage and configure Boundary. Please refer to create login account for the command to create the login account.
- For example, run the below command to create a login account.
```
boundary accounts create password \
  -recovery-config /tmp/recovery.hcl \
  -login-name "admin" \
  -auth-method-id <auth_method_id_from_last_step>
```
Create an admin user and associate with the login account
- Create an admin user and link it to the previously created login account. You will configure this user with administrative privileges to manage Boundary resources in the next step.
- Run the below commands to create and associate the user to the login account.
```
boundary users create -scope-id 'global' \
  -recovery-config /tmp/recovery.hcl \
  -name "admin_user" \
  -description "Global admin user"
 
boundary users add-accounts \
  -recovery-config /tmp/recovery.hcl \
  -id <admin_user_id> \
  -account <admin_account_id>
```

Create an admin role and assign to admin user

Define an admin role with permissions to manage all resources in Boundary. Assign this role to the admin user.
Run the below commands to create and assign the admin role to the admin user.

boundary roles create -name 'global_admin' \
  -recovery-config /tmp/recovery.hcl \
  -scope-id 'global'
 
boundary roles add-grants -id <global_admin_role_id> \
  -recovery-config /tmp/recovery.hcl \
  -grant 'ids=*;type=*;actions=*'
 
boundary roles add-principals -id <global_admin_role_id> \
  -recovery-config /tmp/recovery.hcl \
  -principal '<admin_user_id>'

Create a role for anonymous (unauthenticated) users

Run below command to allow anonymous users to list scopes and auth methods in the global and organization scopes.

boundary roles create -name 'global_anon_listing' \
  -recovery-config /tmp/recovery.hcl \
  -scope-id 'global
 
boundary roles add-grants -id <global_anon_listing_id> \
  -recovery-config /tmp/recovery.hcl \
  -grant 'ids=*;type=auth-method;actions=list,authenticate' \
  -grant 'ids=*;type=scope;actions=list,no-op' \
  -grant 'ids={{.Account.Id}};actions=read,change-password'
 
boundary roles add-grant-scopes -id <global_anon_listing_id> -grant-scope-id "children"
 
boundary roles add-principals -id <global_anon_listing_id> \
  -recovery-config /tmp/recovery.hcl \
  -principal 'u_anon'

Login using password auth method
- Run below command to login using password auth method.
```
boundary authenticate password \
  -auth-method-id <auth_method_id>
```
Create an Organization and Project scope
- Set up an Organization and a Project scope to organize resources and manage access control within Boundary.
- Please refer to create organization and project scope for detailed instructions.

Create roles with administrative privileges at the Organization and Project scope levels.

Run below command to create organization-admin role.

boundary roles create -name 'org_admin' \
  -scope-id 'global'
 
boundary roles set-grant-scopes \
  -id <org_admin_id> \
  -grant-scope-id <org_scope_id>
 
boundary roles add-grants -id <org_admin_id> \
  -grant 'ids=*;type=*;actions=*'

Run below command to create project-admin role.

boundary roles create -name 'project_admin' \
  -scope-id <org_scope_id> \
  -grant-scope-id <project_scope_id>
 
boundary roles add-grants -id <project_admin_id> \
  -grant 'ids=*;type=*;actions=*'

Assign users, groups, or managed groups as principals to the organization-admin and project-admin roles after setting up the LDAP or OIDC auth method. Please refer to the respective sections in this document for the instructions.
Run below commands to assign a principal (user, group, or managed group) to the organization-admin or project-admin roles.

boundary roles add-principals -id <org_admin_id> \
  -principal <user_id|group_id|managed_group_id>
 
boundary roles add-principals -id <project_admin_id> \
  -principal <user_id|group_id|managed_group_id>

People and process

Integrating identity providers