From 49daf1b0162104e1ef8e507b87efcb5ed5f9b3d0 Mon Sep 17 00:00:00 2001 From: Jeff Malnick Date: Sat, 17 Oct 2020 16:00:55 -0700 Subject: [PATCH] docs: how to install without generated resources (#713) * docs: add getting started with no generated resources and KMS recovery workflow * Update website/content/docs/installing/no-gen-resources.mdx Co-authored-by: Jeff Mitchell Co-authored-by: Jeff Mitchell --- .../docs/installing/no-gen-resources.mdx | 456 ++++++++++++++++++ website/data/docs-navigation.js | 2 +- 2 files changed, 457 insertions(+), 1 deletion(-) create mode 100644 website/content/docs/installing/no-gen-resources.mdx diff --git a/website/content/docs/installing/no-gen-resources.mdx b/website/content/docs/installing/no-gen-resources.mdx new file mode 100644 index 000000000..ecdac3852 --- /dev/null +++ b/website/content/docs/installing/no-gen-resources.mdx @@ -0,0 +1,456 @@ +--- +layout: docs +page_title: Installing Boundary Without Generated Resources +sidebar_title: Without Generated Resources +description: |- + How to install boundary without generated resources. +--- + +# Installing Boundary Without Generated Resources + +Initializing Boundary without generated resources for the first time can be a little confusing. How do you +create your first user and login to administer a Boundary deployment that has no authentication methods, +users, accounts, etc? This section describes how to get your freshly deployed Boundary installation off the +ground. + +## Recovery KMS Workflow + +Initializing Boundary without generated resources starts with your Boundary configuration file. Specifically, +the controller configuration specifies three KMS blocks: + +```hcl + +kms "aead" { + purpose = "root" + aead_type = "aes-gcm" + key = "sP1fnF5Xz85RrXyELHFeZg9Ad2qt4Z4bgNHVGtD6ung=" + key_id = "global_root" +} + +kms "aead" { + purpose = "worker-auth" + aead_type = "aes-gcm" + key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ=" + key_id = "global_worker-auth" +} + +kms "aead" { + purpose = "recovery" + aead_type = "aes-gcm" + key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ=" + key_id = "global_recovery" +} + +``` + +In this example, we're using hardcoded AEAD keys, but in a real world non-dev deployment, you +should use your cloud provider's KMS such as [AWS KMS](https://www.boundaryproject.io/docs/configuration/kms/awskms) to manage the keys Boundary +uses to encrypt sensitive information. + +The KMS block we're focused on is the `recovery` block. This block specifies the key used to "recover" Boundary +but you can also use it to authenticate to Boundary and manage it as a "global" super user. This allows +you to authenticate from the CLI or from Terraform in order to manage Boundary without any generated +resources. + +To authenticate to Boundary using the recovery KMS workflow: + + + + +To use the recovery workflow on the CLI, you must pass the `-recovery-config ` flag or set the environment +variable for `BOUNDARY_RECOVERY_CONFIG` for every command ran. Authentication takes place for every command +ran when using the recovery workflow, there is no `boundary authenticate` step: + +```bash +$ cat << EOF > /tmp/recovery.hcl +kms "aead" { + purpose = "recovery" + aead_type = "aes-gcm" + key = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ=" + key_id = "global_recovery" +} +EOF + +$ boundary users create -recovery-config /tmp/recovery.hcl +... +``` + + + + +To configure your provider to use the recovery KMS workflow, provide the KMS block as the value for +`recovery_kms_hcl`: + +```hcl +provider "boundary" { + addr = 'https://boundary.mycorp.com:9200' + recovery_kms_hcl = < + + + +## Initialize the Database + +Before you can start Boundary, the database must be initialized. It's useful to look at the help output for the init command: + +``` +$ boundary database init -h +... +``` + +From this command, you can see the flags available to skip the creation of auto-generated resources. + +To initialize the Boundary database without generated resources: + +``` +$ boundary database init -skip-initial-login-role -config /etc/boundary.hcl +``` + +When you start Boundary, you will effectively have a blank sheet to work against. The initial migrations in the database have been run (note that this includes creating special users like `u_anon` and the `global` scope) and the internal keyrings have been initialized. From here, it's required that +you use the KMS recovery workflow described above to create at a minimum an auth method, a user, an account, and a +role with sufficient grants. Otherwise, you need to continue to use the recovery workflow for management. It's important +to realize that this is effectively a global super user type of workflow and comes with security concerns. + +## Creating Your First Login Account + +This section covers how to configure your first auth method, user, account, and role to login to Boundary without +the recovery KMS workflow. In this example, we're going to make an admin user for the global and project level +scopes we create. This will allow our user to configure targets within those scopes and manage them. + +### Create Org and Project Scopes + +In this example, we're going to create an org and project scope and skip creating an administrator and admin role +for each scope. We're going to specify a role for managing these scopes by selected users in a later step. + + + + +```bash +$ boundary scopes create -name 'org' -scope-id 'global' \ + -recovery-config /tmp/recovery.hcl \ + -skip-admin-role-creation \ + -skip-default-role-creation + + +$ boundary scopes create -name 'project' -scope-id \ + -recovery-config /tmp/recovery.hcl \ + -skip-admin-role-creation \ + -skip-default-role-creation + +``` + + + + +```hcl +resource "boundary_scope" "org" { + scope_id = "global" + name = "organization" + description = "Organization scope" + + auto_create_admin_role = false + auto_create_default_role = false +} + +resource "boundary_scope" "project" { + name = "project" + description = "My first project" + scope_id = boundary_scope.org.id + auto_create_admin_role = false + auto_create_default_role = false +} +``` + + + + + + +### Create an Auth Method + +Create an auth method in the organization scope. + + + + +```bash +$ boundary auth-methods create password \ + -recovery-config /tmp/recovery.hcl \ + -scope-id \ + -name 'my_method' \ + -description 'My password auth method' +``` + + + + +```hcl +resource "boundary_auth_method" "password" { + name = "my_password_auth_method" + description = "Password auth method" + type = "password" + scope_id = boundary_scope.org.id +} +``` + + + + +### Create a Login Account + +Create a login account for the auth method. + + + + +```bash +$ boundary accounts create password \ + -recovery-config /tmp/recovery.hcl \ + -login-name "myuser" \ + -password "foofoofoo" \ + -auth-method-id + + +```hcl +resource "boundary_account" "myuser" { + name = "myuser" + description = "User account for my user" + type = "password" + login_name = "myuser" + password = "foofoofoo" + auth_method_id = boundary_auth_method.password.id +} +``` + + + + +### Create a User + +Create a user and associate the user with the login account created in the previous step. +This user will also be the principal in the role we create in the following step. + + + + +```bash +$ boundary users create -scope-id \ + -recovery-config /tmp/recovery.hcl \ + -name "myuser" \ + -description "My user!" + +$ boundary users add-accounts -id -account +``` + + + + +```hcl +resource "boundary_user" "myuser" { + name = "myuser" + description = "My user!" + account_ids = [boundary_account.myuser.id] + scope_id = boundary_scope.org.id +} +``` + + + + + +### Create Roles to Manage Scopes + +The following describes the four baseline roles you'll need to create to manage resources within the org and project +scopes created above. These roles are similar to the roles created for you in if generation had not been skipped during `boundary database init`, but declaring them explicitly +allows you to manage them independently and fully within Terraform or on the CLI. This is useful if you want to lock +them down more or have control over them in a declarative way. + +The following example creates 4 roles: +1. To allow anonymouns (unauthenticated) users the ability to list scopes and auth methods in the global scope. +1. To allow anonymouns (unauthenticated) users the ability to list scopes and auth methods in the orgnaization scope. +1. To allow `myuser` user administration grants at the org scope. +1. To allow `myuser` user administration grants at the project scope. + +#### Anonymous listing role for global scope + + + + +Assumes recovery key export from above steps is still set: + +```bash +# Create global anonymous listing role +$ boundary roles create -name 'global_anon_listing' \ + -recovery-config /tmp/recovery.hcl \ + -scope-id 'global' + +$ boundary add-grants -id \ + -recovery-config /tmp/recovery.hcl \ + -grant 'id=*;type=auth-method;actions=list,authenticate' \ + -grant 'type=scope;actions=list' \ + -grant 'id={{account.id}};actions=read,change-password' + +$ boundary add-principals -id \ + -recovery-config /tmp/recovery.hcl \ + -principal 'u_anon' +``` + + + + +```hcl +resource "boundary_role" "global_anon_listing" { + scope_id = "global" + grant_strings = [ + "id=*;type=auth-method;actions=list,authenticate", + "type=scope;actions=list", + "id={{account.id}};actions=read,change-password" + ] + principal_ids = ["u_anon"] +} +``` + + + + +#### Anonymous listing role for org scope + + + + +Assumes recovery key export from above steps is still set: + +```bash +$ boundary roles create -name 'org_anon_listing' \ + -recovery-config /tmp/recovery.hcl \ + -scope-id + +$ boundary add-grants -id \ + -recovery-config /tmp/recovery.hcl \ + -grant 'id=*;type=auth-method;actions=list,authenticate' \ + -grant 'type=scope;actions=list' \ + -grant 'id=*;actions=read,change-password' + +$ boundary add-principals -id \ + -recovery-config /tmp/recovery.hcl \ + -principal 'u_anon' +``` + + + + +```hcl +resource "boundary_role" "org_anon_listing" { + scope_id = boundary_scope.org.id + grant_strings = [ + "id=*;type=auth-method;actions=list,authenticate", + "type=scope;actions=list", + "id={{account.id}};actions=read,change-password" + ] + principal_ids = ["u_anon"] +} +``` + + + + +#### Org admin role for myuser + + + + +Assumes recovery key export from above steps is still set: + +```bash +$ boundary roles create -name 'org_admin' \ + -recovery-config /tmp/recovery.hcl \ + -scope-id 'global' \ + -grant-scope-id + +$ boundary add-grants -id \ + -recovery-config /tmp/recovery.hcl \ + -grant 'id=*;type=*;actions=*' + +$ boundary add-principals -id \ + -recovery-config /tmp/recovery.hcl \ + -principal +``` + + + + +```hcl +resource "boundary_role" "org_admin" { + scope_id = "global" + grant_scope_id = boundary_scope.org.id + grant_strings = [ + "id=*;type=*;actions=*" + ] + principal_ids = [boundary_user.myuser.id] +} +``` + + + + +#### Project admin for myuser + + + + +Assumes recovery key export from above steps is still set: + +```bash +$ boundary roles create -name 'project_admin' \ + -recovery-config /tmp/recovery.hcl \ + -scope-id \ + -grant-scope-id + +$ boundary add-grants -id \ + -recovery-config /tmp/recovery.hcl \ + -grant 'id=*;type=*;actions=*' + +$ boundary add-principals -id \ + -recovery-config /tmp/recovery.hcl \ + -principal +``` + + + + +```hcl +resource "boundary_role" "project_admin" { + scope_id = boundary_scope.org.id + grant_scope_id = boundary_scope.project.id + grant_strings = [ + "id=*;type=*;actions=*" + ] + principal_ids = [boundary_user.myuser.id] +} +``` + + + + + +### Login as Your New User + +```bash +boundary authenticate password \ + -auth-method-id \ + -login-name myuser + -password foofoofoo +``` diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index 0d2ec4f7a..dd34b1344 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -13,7 +13,7 @@ export default [ }, { category: 'installing', - content: ['systemd', 'postgres', 'high-availability'], + content: ['no-gen-resources', 'systemd', 'postgres', 'high-availability'], }, { category: 'api-clients',