Managing principals

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 either users, groups, or both.

This page will walk you through managing users within Boundary. (Groups will be added at a later time.)

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.

In this example, we're going to show you how to create an account and user for an auth method to allow that user to login to Boundary. Because an auth method can be at the org and global scopes, we're going to create an org-scoped auth method in the default generated org in a dev mode server. (If you're not running dev mode, you'll need to substitute appropriate generated IDs in the steps below.)

Currently, all auth methods auto-vivify users on authentication; that is, on successful authentication against an account, if there is no user already linked with that account, a user will be automatically created. This may be a nice time-saver, but in other situations (such as when you want Terraform to fully describe the Boundary resources) this may be undesirable, so the steps below walk you through manually making these resources and linking them. A future Boundary update will allow turning off auto-vivification on a per-auth-method basis.

Create an auth method

Create a password-type auth method in the generated default org:

$ boundary auth-methods create password -scope-id o_1234567890 -name org_auth_method -description 'Org auth method'

Auth Method information:
  Created Time:                Tue, 29 Sep 2020 08:32:04 PDT
  Description:                 Org auth method
  ID:                          ampw_PbE6nNT72a
  Name:                        org_auth_method
  Type:                        password
  Updated Time:                Tue, 29 Sep 2020 08:32:04 PDT
  Version:                     1

  Scope:
    ID:                        o_1234567890
    Name:                      Generated org scope
    Parent Scope ID:           global
    Type:                      org

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

Create an account

Create an account for the org-scoped auth method. Note that by default, 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.)

boundary accounts create password -auth-method-id ampw_PbE6nNT72a -login-name 'myuser' -name my_account -description 'My password account'

Account information:
  Auth Method ID:      ampw_PbE6nNT72a
  Created Time:        Tue, 29 Sep 2020 08:35:02 PDT
  Description:         My password account
  ID:                  acctpw_BOn3EcqQfe
  Name:                my_account
  Type:                password
  Updated Time:        Tue, 29 Sep 2020 08:35:02 PDT
  Version:             1

  Scope:
    ID:                o_1234567890
    Name:              Generated org scope
    Parent Scope ID:   global
    Type:              org

  Attributes:
    Login Name:        myuser

resource "boundary_account" "my_user" {
  name           = "myuser"
  description    = "Login account for my user"
  type           = "password"
  login_name     = "myuser"
  password       = "supersecure"
  auth_method_id = "ampw_PbE6nNT72a"
}

Create a user

Next, create a user at the org scope.

First, create the user resource:

$ boundary users create -name "myuser" -description "My user resource" -scope-id o_1234567890

User information:
  Created Time:        Tue, 29 Sep 2020 06:37:12 PDT
  Description:         My user resource
  ID:                  u_yXhZpt5PX3
  Name:                myuser
  Updated Time:        Tue, 29 Sep 2020 06:37:12 PDT
  Version:             1

  Scope:
    ID:                o_1234567890
    Name:              Generated org scope
    Parent Scope ID:   global
    Type:              org

Then associate the user with the account previously created:

$ boundary users set-accounts -id u_yXhZpt5PX3 -account acctpw_BOn3EcqQfe

User information:
  Created Time:        Tue, 29 Sep 2020 08:43:43 PDT
  Description:         My org user
  ID:                  u_yXhZpt5PX3
  Name:                my_user
  Updated Time:        Tue, 29 Sep 2020 08:54:11 PDT
  Version:             2

  Scope:
    ID:                o_1234567890
    Name:              Generated org scope
    Parent Scope ID:   global
    Type:              org

  Accounts:
    ID:                acctpw_BOn3EcqQfe
    Scope ID:          o_1234567890

resource "boundary_user" "myuser" {
  name        = "myuser"
  description = "My user resource"

  # taken from the example account resource defined above
  account_ids = [ boundary_account.myuser.id ]
  scope_id    = "o_1234567890"
}

Log in

Now you can test logging in.

$ boundary authenticate password -auth-method-id ampw_PbE6nNT72a

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