From 24754933cf99c003479dc5086c2da55132651f37 Mon Sep 17 00:00:00 2001 From: Jeff Mitchell Date: Tue, 13 Oct 2020 12:14:40 -0400 Subject: [PATCH] Update users/groups workflow doc (#655) --- .../content/docs/common-workflows/index.mdx | 4 +- ...identities.mdx => manage-users-groups.mdx} | 59 +++++++++++++------ website/data/docs-navigation.js | 2 +- 3 files changed, 44 insertions(+), 21 deletions(-) rename website/content/docs/common-workflows/{manage-identities.mdx => manage-users-groups.mdx} (75%) diff --git a/website/content/docs/common-workflows/index.mdx b/website/content/docs/common-workflows/index.mdx index 9ad7055b14..d7dd0153ea 100644 --- a/website/content/docs/common-workflows/index.mdx +++ b/website/content/docs/common-workflows/index.mdx @@ -7,6 +7,6 @@ description: Common workflows for Boundary # Common Workflows -This section covers common workflows for managing targets, identities, and sessions within Boundary. This section assumes you've already covered the [getting started](/docs/getting-started) section and are familiar with basic Boundary knowledge. This section extends getting started by showing how to accomplish common workflows in the admin console, the command line, and with our [Terraform provider](https://github.com/hashicorp/terraform-provider-boundary). +This section covers common workflows for managing targets, identities, and sessions within Boundary. This section assumes you've already covered the [Getting Started](/docs/getting-started) section and are familiar with basic Boundary knowledge. This section extends Getting Started by showing how to accomplish common workflows in the admin console, the command line, and with our [Terraform provider](https://github.com/hashicorp/terraform-provider-boundary). -For more detailed guides on using Boundary please consult our [learn site](TBD). +For more detailed guides on using Boundary please consult our [Learn site](https://learn.hashicorp.com/boundary). diff --git a/website/content/docs/common-workflows/manage-identities.mdx b/website/content/docs/common-workflows/manage-users-groups.mdx similarity index 75% rename from website/content/docs/common-workflows/manage-identities.mdx rename to website/content/docs/common-workflows/manage-users-groups.mdx index 614b384c8c..a68a9a0849 100644 --- a/website/content/docs/common-workflows/manage-identities.mdx +++ b/website/content/docs/common-workflows/manage-users-groups.mdx @@ -1,31 +1,49 @@ --- layout: docs -page_title: Manage Identities -sidebar_title: Manage Identities -description: How to manage Boundary identities +page_title: Manage Users and Groups +sidebar_title: Manage Users and Groups +description: How to manage Boundary users and groups --- -# Manage Identities +# Managing Principals (Users and Groups) -Identities in Boundary are known as [Principals](/docs/concepts/domain-model/principals). Principals are embodied in two types of resources: +Users and Groups in Boundary are collectively known as principals. Assigning +[grants](/docs/concepts/security/permissions) on +[Roles](/docs/concepts/domain-model/roles) is performed through principal IDs; +that is, the unique IDs of either users, groups, or both. -1. Users -1. Groups +This page will walk you through managing users within Boundary. (Groups will be +added at a later time.) -Both users and groups can be granted access to resources through [grants](/docs/concepts/domain-model/grants) on [roles](/docs/concepts/domain-model/roles). +## Users -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. +Users in Boundary represent an _internal_ notion of a particular entity (human, +machine, etc.). Users can be correlated with one or more +[Account](/docs/concepts/domain-model/accounts) resources via [Auth +Methods](/docs/concepts/domain-model/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. -~> Note that all resource ID's in this example are illustration only - ID's are uniquely generated for every resource upon creation with the exception being -generated resources in `dev mode`. Please make sure to use the resource ID's that are generated when running this example. For example, if you run -`boundary users create`, use the resource ID of the user seen in stdout, not the ID in the example command. +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 resoruces) 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 auth method in the generated default org: +Create a password-type auth method in the generated default org: @@ -48,6 +66,7 @@ Auth Method information: Name: Generated org scope Parent Scope ID: global Type: org + Attributes: Minimum Login Name Length: 3 Minimum Password Length: 8 @@ -59,7 +78,7 @@ Auth Method information: 1. Navigate to an org, then to auth methods. 1. Choose the **New** button. -1. Fill the auth method details. +1. Fill in the auth method details. 1. Choose **Save** and view the auth method edit form page.