Initial configuration

After setting up a Boundary cluster, it is 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

You have reviewed the Boundary 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 administrator 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 administrator and anonymous users, and the global administrator credentials during the HCP Boundary cluster setup.

Steps 7-9 apply to both HCP Boundary and Boundary Enterprise. The term Boundary applies to both products for those steps.

Run the commands below 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 command line. 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. Use this method only for the initial setup, testing, or as a fallback mechanism if the primary auth method (for example 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 administrator account
- Create a login account within the password authentication method. Use this account 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 administrator user and associate with the login account
- Create the user admin_user and link it to the login account created in the previous step. Configure this user with administrative privileges to manage Boundary resources in the next step.
- Run the commands below 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 administrator role and assign to administrator user

Define an administrator 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 administrator role to the administrator 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 administrator 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 administrator 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 administrator and project administrator 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 administrator or project administrator 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