Managing principals

Users and groups in Boundary are collectively known as principals. You assign grants on roles to principal IDs — the unique IDs of users, groups, or both.

Users represent an internal notion of a particular identity, such as a person or a machine. A user can be linked to one or more account resources through auth methods. Accounts represent an external notion of an identity, which lets you switch a user to a new auth method or identity provider without losing their role assignments.

This page describes how to link a user to an existing account, and then authenticate as that user. If you do not already have an auth method and account, refer to Configure authentication to create one before you continue. The examples on this page use a password account, but linking a user to an account works the same way regardless of auth method type.

Note

All auth methods automatically create ("auto-vivify") a user the first time someone authenticates successfully against an account, if no user is already linked to that account. Manually creating and linking a user, as described in this topic, is useful when you want explicit control over user creation, such as when Terraform manages your Boundary resources. Refer to What is a primary auth method? for more information.

Create a user

Create a user in the same scope as the account you want to link it to, and then link the two together.

First, create the user resource:

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

Then link the user to an existing account:

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

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

  # Reference the account resource you created for this user
  account_ids = [boundary_account.myuser.id]
  scope_id    = "SCOPE_ID"
}

Log in

Authenticate as the linked user to confirm the account and user are connected correctly. Use the authenticate subcommand for your auth method type. Refer to Configure authentication for OIDC, LDAP, and password examples.

$ boundary authenticate password -auth-method-id $PASSWORD_AUTH_METHOD_ID -login-name myuser

More information

To better understand Boundary's permissions model, refer to Permissions in Boundary.
To configure the auth methods your principals authenticate with, refer to Configure authentication.
For more information about the Boundary resources described in this topic, refer to the Users, Auth methods, and Accounts domain model topics.
To learn more about creating or managing users, refer to the CLI users topic or the API User service topic.
To learn more about creating or managing auth methods, refer to the CLI auth-methods topic or the API Auth method service topic.
To learn more about creating or managing accounts, refer to the CLI accounts topic or the API Account service topic.

Next steps

To dynamically control access to resource using filters with OIDC or LDAP managed groups, refer to Filter managed groups.