Manage Users and Groups with HCP Boundary

10min
HCP
Boundary
Terraform

Users and groups in Boundary are collectively known as principals. Assigning grants on roles is performed through principal IDs; that is, the unique IDs of users, groups, or both.

This tutorial focus on completing user management tasks within a Boundary environment.

All resource IDs in this tutorial are illustrations only. IDs are uniquely generated for every resource upon creation. Be sure to use the resource IDs that are generated for your environment.

Prerequisites

This tutorial assumes that you successfully completed the Manage Scopes tutorial.

Users

Users in Boundary represent an internal notion of a particular entity (human, machine, etc.). Users can be correlated with one or more account resources via auth methods. Accounts represent external notions of a particular entity. Among other use-cases, this mechanism allows for an easy way to switch users to new IdPs within the organization deploying Boundary.

An auth method can be defined at the org and global scopes. In this tutorial, you will create an account and user for an auth method at the org level.

Currently, all auth methods create users upon authentication. If there is no user linked with an account, Boundary creates a user when the authentication against that account was successful. This behavior may be convenient, but in other situations (such as when you want Terraform to describe the Boundary resources), this may be undesirable. The steps in this tutorial demonstrate manually making these resources and linking them. A future Boundary update will allow turning off auto-vivification on a per-auth-method basis.

Add an auth method

Enable a password-type auth method in the IT_Support org which you created in the Manage Scopes tutorial.

Create a password auth method in the IT_Support org.

$ boundary auth-methods create password \
  -scope-id=$ORG_ID \
  -name="org_auth_method" \
  -description="Org auth method"

Example:

$ boundary auth-methods create password \
  -scope-id=$ORG_ID \
  -name="org_auth_method" \
  -description="Org auth method"

Auth Method information:
  Created Time:                Fri, 27 May 2022 11:14:30 MDT
  Description:                 Org auth method
  ID:                          ampw_ZbB6UXpW3B
  Name:                        org_auth_method
  Type:                        password
  Updated Time:                Fri, 27 May 2022 11:14:30 MDT
  Version:                     1

  Scope:
    ID:                        o_u54jrD6ydN
    Name:                      IT_Support
    Parent Scope ID:           global
    Type:                      org

  Authorized Actions:
    no-op
    read
    update
    delete
    authenticate

  Authorized Actions on Auth Method's Collections:
    accounts:
      create
      list
    managed-groups:
      create
      list

  Attributes:
    Minimum Login Name Length: 3
    Minimum Password Length:   8

In this example output, the password auth method ID is ampw_ZbB6UXpW3B.

Copy the auth method ID and save it as an environment variable, PW_AUTH_ID.

Example:

$ export PW_AUTH_ID=ampw_ZbB6UXpW3B

In your Terraform configuration file, define a boundary_auth_method resource to create a new auth method under the IT_Support scope which you created in the Manage Scopes tutorial.

resource "boundary_auth_method" "password" {
  name        = "org_auth_method"
  description = "Password auth method for org"
  type        = "password"
  scope_id    = boundary_scope.org.id
}

Create an account

Create an account for the org-scoped auth method.

NOTE: User names must be all lowercase alphanumeric of at least 3 characters and the password must be 8 or more characters. (The minimum lengths can be changed in the attributes for the auth method if desired.)

Create an account named "test_account". For the password, use supersecure. Or, use a password of your choosing, but be sure to remember it!

$ boundary accounts create password \
  -auth-method-id=$PW_AUTH_ID \
  -login-name="tester01" \
  -name=test_account \
  -description="Test password account"
Please enter the password (it will be hidden):

Example output:

$ boundary accounts create password \
  -auth-method-id=$PW_AUTH_ID \
  -login-name="tester01" \
  -name=test_account \
  -description="Test password account"
Please enter the password (it will be hidden):

Account information:
  Auth Method ID:      ampw_ZbB6UXpW3B
  Created Time:        Fri, 27 May 2022 11:16:47 MDT
  Description:         Test password account
  ID:                  acctpw_A8R1escktO
  Name:                test_account
  Type:                password
  Updated Time:        Fri, 27 May 2022 11:16:47 MDT
  Version:             1

  Scope:
    ID:                o_u54jrD6ydN
    Name:              IT_Support
    Parent Scope ID:   global
    Type:              org

  Authorized Actions:
    no-op
    read
    update
    delete
    set-password
    change-password

  Attributes:
    Login Name:        tester01

In this example, the generated account ID is acctpw_A8R1escktO.

Copy the ID of test_account and save it as an environment variable, ACCOUNT_ID.

$ export ACCOUNT_ID=acctpw_A8R1escktO

In your Terraform configuration file, define a boundary_account_password resource to create a new account in the org_auth_method you created in the previous step.

resource "boundary_account_password" "test_account" {
  name           = "test_account"
  description    = "Test password account"
  type           = "password"
  login_name     = "tester01"
  password       = "supersecure"
  auth_method_id = boundary_auth_method.password.id
}

Create a user

Next, create a user at the org scope.

Create a user, "tester01" under the IT_Support org.

$ boundary users create -name="tester01" -description="A test user" -scope-id=$ORG_ID

User information:
  Created Time:        Fri, 27 May 2022 11:17:35 MDT
  Description:         A test user
  ID:                  u_ogz79sV4sT
  Name:                tester01
  Updated Time:        Fri, 27 May 2022 11:17:35 MDT
  Version:             1

  Scope:
    ID:                o_u54jrD6ydN
    Name:              IT_Support
    Parent Scope ID:   global
    Type:              org

  Authorized Actions:
    no-op
    read
    update
    delete
    add-accounts
    set-accounts
    remove-accounts

In the example output, the tester01 user ID is u_ogz79sV4sT.

Copy the generated user ID and save it as an environment variable, USER_ID.

Example:

$ export USER_ID=u_ogz79sV4sT

Now, associate the tester01 user with the test_account account previously created.

$ boundary users set-accounts -id=$USER_ID -account=$ACCOUNT_ID

User information:
  Created Time:        Fri, 27 May 2022 11:17:35 MDT
  Description:         A test user
  ID:                  u_ogz79sV4sT
  Name:                tester01
  Updated Time:        Fri, 27 May 2022 11:18:37 MDT
  Version:             2

  Scope:
    ID:                o_u54jrD6ydN
    Name:              IT_Support
    Parent Scope ID:   global
    Type:              org

  Authorized Actions:
    no-op
    read
    update
    delete
    add-accounts
    set-accounts
    remove-accounts

  Accounts:
    ID:                acctpw_A8R1escktO
    Scope ID:          o_u54jrD6ydN

In your Terraform configuration file, define a boundary_user resource to create a new user and associate that with test_account you created in the previous step.

resource "boundary_user" "tester01" {
  name        = "tester01"
  description = "A test user"
  account_ids = [
     boundary_account_password.test_account.id
  ]
  scope_id    = boundary_scope.org.id
}

Verify Users

Now, test to make sure that you can authenticate with Boundary as tester01 user.

Authenticate with Boundary using the newly created user "tester01".

$ boundary authenticate password \
  -login-name="tester01" \
  -auth-method-id=$PW_AUTH_ID
Please enter the password (it will be hidden):

Example output:

$ boundary authenticate password \
  -login-name="tester01" \
  -auth-method-id=$PW_AUTH_ID
Please enter the password (it will be hidden):

Authentication information:
  Account ID:      acctpw_A8R1escktO
  Auth Method ID:  ampw_ZbB6UXpW3B
  Expiration Time: Fri, 03 Jun 2022 11:19:57 MDT
  User ID:         u_ogz79sV4sT

The token was successfully stored in the chosen keyring and is not displayed here.

To continue the tutorial, re-authenticate with the admin username and password that you were using. Make sure to then select the IT_Support group again.

$ boundary authenticate password \
  -auth-method-id=ampw_1234567890 \
  -login-name=admin
Please enter the password (it will be hidden):

Log out by selecting Deauthenticate from the upper-right menu.
Select IT_Support to set the scope to log in.
Enter tester01 in the Login Name field, and supersecure in the Password field.
Click Sign In.
Log out by selecting Sign Out from the upper-right menu.
To continue the tutorial, re-authenticate with the admin username and password that you were using.
Leave the scope to be Global and enter the Login Name and Password.

This tutorial uses a pre-existing admin account to manage Terraform resources. This approach allows Boundary to be configured programmatically, with minimal bootstrapping of Boundary with accounts or users. If using this method, consider utilizing Terraform input variables, like the sample code for this tutorial demonstrates. Also note that the account must already exist in order for Terraform to manage resources using this method.

To configure the Boundary provider using Terraform, provide the valid auth method ID, login name, and password for a pre-existing auth method to authenticate. The user must have appropriate grants assigned to manage resources in the desired scope. The next tutorial will discuss roles and grants.

provider "boundary" {
  addr                            = "http://127.0.0.1:9200"
  auth_method_id                  = "ampw_sOXVI7JS2l"
  password_auth_method_login_name = "tester01"
  password_auth_method_password   = "supersecure"
}

These values can be hard-coded into the Terraform config, or supplied using variables like this tutorial demonstrates.

Do NOT add this configuration to your main.tf file. It has already been configured.

Groups

A group in Boundary is a resource that represents a collection of users that are treated equally for the purposes of access control. A group is a principal, which allows it to be assigned to roles. Roles assigned to a group are indirectly assigned to the users in the group, and users receive all permissions of the assigned roles. Groups can be defined at the Global, Organization, or Project scope.

The group resource membership is managed manually. If using an OIDC Auth provider, such as Auth0, Okta or Azure AD, Managed Groups can be used to automatically map membership to a collection of accounts defined by the auth method's identity provider using filtering.

Create a group

Create a user at the org scope.

Create a group, "group01" under the IT_Support org.

$ boundary groups create -name="group01" -description="A test group" -scope-id=$ORG_ID

Group information:
  Created Time:        Fri, 27 May 2022 11:20:55 MDT
  Description:         A test group
  ID:                  g_wRpm66iPOX
  Name:                group01
  Updated Time:        Fri, 27 May 2022 11:20:55 MDT
  Version:             1

  Scope:
    ID:                o_u54jrD6ydN
    Name:              IT_Support
    Parent Scope ID:   global
    Type:              org

  Authorized Actions:
    no-op
    read
    update
    delete
    add-members
    set-members
    remove-members

In the example output, the group01 group ID is g_wRpm66iPOX.

Copy the generated group ID and save it as an environment variable, GROUP_ID.

Example:

$ export GROUP_ID=g_wRpm66iPOX

Now, add the tester01 user created previously to group01.

$ boundary groups add-members -id=$GROUP_ID -member=$USER_ID

Group information:
  Created Time:        Fri, 27 May 2022 11:20:55 MDT
  Description:         A test group
  ID:                  g_wRpm66iPOX
  Name:                group01
  Updated Time:        Fri, 27 May 2022 11:21:42 MDT
  Version:             2

  Scope:
    ID:                o_u54jrD6ydN
    Name:              IT_Support
    Parent Scope ID:   global
    Type:              org

  Authorized Actions:
    no-op
    read
    update
    delete
    add-members
    set-members
    remove-members

  Members:
    ID:                u_ogz79sV4sT
    Scope ID:          o_u54jrD6ydN

In your Terraform configuration file, define a boundary_group resource to create a new group and associate it with the tester01 user you created in the previous step.

resource "boundary_group" "group01" {
  name        = "My group"
  description = "A test group"
  member_ids  = [boundary_user.tester01.id]
  scope_id    = boundary_scope.org.id
}

The entire main.tf file contents are printed below for reference.

main.tf

terraform {
  required_providers {
    boundary = {
      source  = "hashicorp/boundary"
      version = "1.0.7"
    }
  }
}

variable "boundary_addr" {
  type = string
}

variable "auth_method_id" {
  type = string
}

variable "password_auth_method_login_name" {
  type = string
}

variable "password_auth_method_password" {
  type = string
}

provider "boundary" {
  addr                            = var.boundary_addr
  auth_method_id                  = var.auth_method_id
  password_auth_method_login_name = var.password_auth_method_login_name
  password_auth_method_password   = var.password_auth_method_password
}

resource "boundary_scope" "org" {
  scope_id                 = "global"
  name                     = "IT_Support"
  description              = "IT Support Team"
  auto_create_default_role = true
  auto_create_admin_role   = true
}

resource "boundary_scope" "project" {
  name             = "QA_Tests"
  description      = "Manage QA machines"
  scope_id                 = boundary_scope.org.id
  auto_create_admin_role   = true
  auto_create_default_role = true
}

resource "boundary_host_catalog_static" "devops" {
  name        = "DevOps"
  description = "For DevOps usage"
  scope_id    = boundary_scope.project.id
}

resource "boundary_host_static" "postgres" {
  name            = "postgres"
  description     = "Postgres host"
  address         = "127.0.0.1"
  host_catalog_id = boundary_host_catalog_static.devops.id
}

resource "boundary_host_static" "localhost" {
  name            = "localhost"
  description     = "Localhost for testing"
  address         = "localhost"
  host_catalog_id = boundary_host_catalog_static.devops.id
}

resource "boundary_host_set_static" "test-machines" {
  name            = "test-machines"
  description     = "Host set for postgres"
  host_catalog_id = boundary_host_catalog_static.devops.id
  host_ids = [
      boundary_host_static.postgres.id,
      boundary_host_static.localhost.id,
  ]
}

resource "boundary_target" "tests" {
  type                     = "tcp"
  name                     = "tests"
  description              = "Test target"
  scope_id                 = boundary_scope.project.id
  session_connection_limit = -1
  default_port             = 22
  host_source_ids = [
    boundary_host_set_static.test-machines.id
  ]
}

resource "boundary_auth_method" "password" {
  name        = "org_password_auth"
  description = "Password auth method for org"
  type        = "password"
  scope_id    = boundary_scope.org.id
}

resource "boundary_account_password" "test_account" {
  name           = "test_account"
  description    = "Test password account"
  type           = "password"
  login_name     = "tester01"
  password       = "supersecure"
  auth_method_id = boundary_auth_method.password.id
}

resource "boundary_user" "tester01" {
  name        = "tester01"
  description = "A test user"
  account_ids = [
     boundary_account_password.test_account.id
  ]
  scope_id    = boundary_scope.org.id
}

resource "boundary_group" "group01" {
  name        = "My group"
  description = "A test group"
  member_ids  = [boundary_user.tester01.id]
  scope_id    = boundary_scope.org.id
}

Save this file.

Now apply the Terraform config. Enter yes when prompted for confirmation.

$ terraform apply -var "boundary_addr=$BOUDNARY_ADDR" -var "auth_method_id=$BOUNDARY_AUTH_METHOD_ID" -var "password_auth_method_login_name=admin" -var "password_auth_method_password=password"

boundary_scope.org: Refreshing state... [id=o_u8j8RSASFv]
boundary_scope.project: Refreshing state... [id=p_zFs59oil3J]
boundary_host_catalog_static.devops: Refreshing state... [id=hcst_8iV7jlvqi7]
boundary_host_static.localhost: Refreshing state... [id=hst_mZxekgMKS6]
boundary_host_static.postgres: Refreshing state... [id=hst_KCvhOn9l1Y]
boundary_host_set_static.test-machines: Refreshing state... [id=hsst_2kyFXQrsqY]
boundary_target.tests: Refreshing state... [id=ttcp_HwZP7XG1PR]

Note: Objects have changed outside of Terraform

Terraform detected the following changes made outside of Terraform since the last "terraform apply":

  # boundary_target.tests has been changed
  ~ resource "boundary_target" "tests" {
      + application_credential_source_ids = []
        id                                = "ttcp_HwZP7XG1PR"
        name                              = "tests"
        # (7 unchanged attributes hidden)
    }

Unless you have made equivalent changes to your configuration, or ignored the relevant attributes using ignore_changes, the following plan may
include actions to undo or respond to these changes.

──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # boundary_account_password.test_account will be created
  + resource "boundary_account_password" "test_account" {
      + auth_method_id = (known after apply)
      + description    = "Test password account"
      + id             = (known after apply)
      + login_name     = "tester01"
      + name           = "test_account"
      + password       = "supersecure"
      + type           = "password"
    }

  # boundary_auth_method.password will be created
  + resource "boundary_auth_method" "password" {
      + description           = "Password auth method for org"
      + id                    = (known after apply)
      + min_login_name_length = (known after apply)
      + min_password_length   = (known after apply)
      + name                  = "org_password_auth"
      + scope_id              = "o_u8j8RSASFv"
      + type                  = "password"
    }

  # boundary_group.group01 will be created
  + resource "boundary_group" "group01" {
      + description = "A test group"
      + id          = (known after apply)
      + member_ids  = (known after apply)
      + name        = "My group"
      + scope_id    = "o_u8j8RSASFv"
    }

  # boundary_user.tester01 will be created
  + resource "boundary_user" "tester01" {
      + account_ids = (known after apply)
      + description = "A test user"
      + id          = (known after apply)
      + name        = "tester01"
      + scope_id    = "o_u8j8RSASFv"
    }

Plan: 4 to add, 0 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

boundary_auth_method.password: Creating...
boundary_auth_method.password: Creation complete after 0s [id=ampw_pWFjqh3pks]
boundary_account_password.test_account: Creating...
boundary_account_password.test_account: Creation complete after 0s [id=acctpw_kYycBlo7Wd]
boundary_user.tester01: Creating...
boundary_user.tester01: Creation complete after 0s [id=u_5B7g3YUFMf]
boundary_group.group01: Creating...
boundary_group.group01: Creation complete after 0s [id=g_wueUZm3ZGq]

Apply complete! Resources: 4 added, 0 changed, 0 destroyed.

By itself, group membership does not inherently assign its members any permissions. In the next tutorial, a role will be assigned to the group and the included members will inherit the role's permissions.

Next steps

This tutorial demonstrated the steps to add a new authentication method to an org (IT_Support), created a new user and group within the org, and added the user as a member of the group. You verified that you can authenticate and logged into the IT_Support org using the newly created user credential.

The next step is to define the permissions to control what operations members of the group can perform. In the Manage Roles and Permissions tutorial, you will create a role, assign grants to the role, and then add the group as a principle of the new role. This group members will then inherit the defined permissions.