Manage users and groups

10min
|
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.

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.

Authenticate to Boundary as the admin user with the login name of password.

$ boundary authenticatePlease enter the login name (it will be hidden):Please enter the password (it will be hidden):Authentication information:  Account ID:      acctpw_VOeNSFX8pQ  Auth Method ID:  ampw_ZbB6UXpW3B  Expiration Time: Mon, 13 Feb 2023 12:35:32 MST  User ID:         u_1vUkf5fPs9The token was successfully stored in the chosen keyring and is not displayed here.

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, BOUNDARY_AUTH_METHOD_ID.

Example:

$ export BOUNDARY_AUTH_METHOD_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". Give it a password supersecure when prompted.

$ boundary accounts create password \  -auth-method-id=$BOUNDARY_AUTH_METHOD_ID \  -login-name="tester01" \  -name=test_account \  -description="Test password account"

Example output:

$ boundary accounts create password \  -auth-method-id=$BOUNDARY_AUTH_METHOD_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. Enter supersecure at the Please enter the password (it will be hidden): prompt.

$ boundary authenticatePlease enter the login name (it will be hidden):Please enter the password (it will be hidden):Authentication information:  Account ID:      acctpw_A8R1escktO  Auth Method ID:  ampw_ZbB6UXpW3B  Expiration Time: Mon, 13 Feb 2023 12:35:32 MST  User ID:         u_ogz79sV4sTThe token was successfully stored in the chosen keyring and is not displayed here.

Warning

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.

Example: If you are running Boundary in dev mode, authenticate as the admin user. When prompted, enter password which is the default admin password in dev mode.

$ boundary authenticatePlease enter the login name (it will be hidden):Please enter the password (it will be hidden):Authentication information:  Account ID:      acctpw_VOeNSFX8pQ  Auth Method ID:  ampw_ZbB6UXpW3B  Expiration Time: Mon, 13 Feb 2023 12:35:32 MST  User ID:         u_1vUkf5fPs9The token was successfully stored in the chosen keyring and is not displayed here.

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.
Warning
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. If you are running Boundary in dev mode, enter admin in the Login Name field, and password in the Password field.

This tutorial utilizes the recovery key workflow to configure Boundary with Terraform utilizing the recovery_kms_hcl attribute of the boundary provider:

provider "boundary" {  addr             = "http://127.0.0.1:9200"  recovery_kms_hcl = <<EOTkms "aead" {  purpose = "recovery"  aead_type = "aes-gcm"  key = "Wt7KhwRKB05YlznYd5i5iPIezLHzbVFrKeZ2ewhoMwk="  key_id = "global_recovery"}EOT}

This is useful because it allows Boundary to be configured programmatically, without first bootstrapping Boundary with accounts or users.

Another approach uses a pre-existing account to manage Terraform resources. This method is not recommended, since authentication passwords should not be stored in HCL for production environments. If using this method, consider utilizing Terraform input variables instead. Also note that the account must already exist in order for Terraform to manage resources using this method.

Note

Do NOT copy the following snippet into your main.tf configuration. The following configuration is only provided as an example.

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. Note that a valid auth_method_id must be provided when configuring Boundary using this method, and 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"}

Do NOT add this configuration to your main.tf file.

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.

terraform {  required_providers {    boundary = {      source  = "hashicorp/boundary"      version = "1.0.7"    }  }} provider "boundary" {  addr             = "http://127.0.0.1:9200"  recovery_kms_hcl = <<EOTkms "aead" {  purpose = "recovery"  aead_type = "aes-gcm"  key = "Zg5vogpvOjhM4USNEa21f2zLiKJlWl8Ulklp29gEAcI="  key_id = "global_recovery"}EOT} 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 applyboundary_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 mayinclude 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.

Manage targets

Manage roles and permissions