From fe7645381206b62b467a4f2d86ea3560fd9e622e Mon Sep 17 00:00:00 2001 From: Nicolas Corrarello Date: Fri, 6 Oct 2017 17:32:26 +0100 Subject: [PATCH 1/6] Added Vault documentation for integrating with Identity Systems --- website/source/guides/acl.html.markdown | 137 ++++++++++++++++++++++++ 1 file changed, 137 insertions(+) diff --git a/website/source/guides/acl.html.markdown b/website/source/guides/acl.html.markdown index c6e8d55a8..d8dc18c06 100644 --- a/website/source/guides/acl.html.markdown +++ b/website/source/guides/acl.html.markdown @@ -347,3 +347,140 @@ Error bootstrapping: Unexpected response code: 500 (Invalid bootstrap reset inde This is because the reset file is in place, but with the incorrect index. The reset file can be deleted, but Nomad will not reset the bootstrap until the index is corrected. +## Vault Integration +Hashicorp Vault has a secret backend for generating short lived Nomad tokens. As Vault has a number of +authentication backends, it could provide a workflow where a user or orchestration system authenticates +using an pre-existing identity service (LDAP, Okta, Amazon IAM, etc. ...) in order to obtain a short-lived +Nomad token. + +~> Hashicorp Vault is a standalone product with it's own set of deployment and configuration best +practices. Please review Vault's documentation before deploying it in production. + +For evaluation purposes, a Vault server in "dev" mode can be used. + +``` +$ vault server -dev +==> Vault server configuration: + + Cgo: disabled + Cluster Address: https://127.0.0.1:8201 + Listener 1: tcp (addr: "127.0.0.1:8200", cluster address: "127.0.0.1:8201", tls: "disabled") + Log Level: info + Mlock: supported: false, enabled: false + Redirect Address: http://127.0.0.1:8200 + Storage: inmem + Version: Vault v0.8.3 + Version Sha: a393b20cb6d96c73e52eb5af776c892b8107a45d + +==> WARNING: Dev mode is enabled! + +In this mode, Vault is completely in-memory and unsealed. +Vault is configured to only have a single unseal key. The root +token has already been authenticated with the CLI, so you can +immediately begin using the Vault CLI. + +The only step you need to take is to set the following +environment variables: + + export VAULT_ADDR='http://127.0.0.1:8200' + +The unseal key and root token are reproduced below in case you +want to seal/unseal the Vault or play with authentication. + +Unseal Key: YzFfPgnLl9R1f6bLU7tGqi/PIDhDaAV/tlNDMV5Rrq0= +Root Token: f84b587e-5882-bba1-a3f0-d1a3d90ca105 + +``` + +### Pre-requisites +- Nomad ACL system bootstrapped. +- A management token (the bootstrap token can be used, but for production systems it's recommended to +have a separate token) +- A set of policies created in Nomad +- An unsealed Vault server + +### Configuration +Mount the "nomad" secret backend in Vault + +``` +$ vault mount nomad +Successfully mounted 'nomad' at 'nomad'! +``` + +Configure access with the right address and management token +``` +$ vault write nomad/config/access \ + address=http://127.0.0.1:4646 \ + token=adf4238a-882b-9ddc-4a9d-5b6758e4159e +Success! Data written to: nomad/config/access +``` + +Vault secret backends have the concept of roles, configuration unit that group one or more policies +to a potential identity based on Vault's policy. The name of the role is specified on the path, while +the mapping to Nomad policies is done by naming them in a comma separated list, for example: + +``` +$ vault write nomad/roles/role-name policy=policyone,policytwo +Success! Data written to: nomad/roles/role-name +``` + +Alternatively, to create management tokens, or global tokens: + +``` +$ vault write nomad/roles/role-name token_type=management global=true +Success! Data written to: nomad/roles/role-name +``` + +A Vault policy is required to allow different identities to get tokens associated with a particular +role: + +``` +$ echo 'path "nomad/creds/role-name" { + capabilities = ["read"] +}' | vault policy-write nomad-user-policy - +Policy 'nomad-user-policy' written. +``` + +If you have an existing authentication backend (like LDAP), follow the relevant instructions to create +a role available on the [Authentication backends page](https://www.vaultproject.io/docs/auth/index.html). +Otherwise, for testing purposes, a token can be generated associated with the policy: + +``` +$ vault token-create -policy=nomad-user-policy +Key Value +--- ----- +token deedfa83-99b5-34a1-278d-e8fb76809a5b +token_accessor fd185371-7d80-8011-4f45-1bb3af2c2733 +token_duration 768h0m0s +token_renewable true +token_policies [nomad-user-policy] +``` + +Finally obtain a Nomad Token using the existing Vault Token: + +``` +$ vault read nomad/creds/role-name +Key Value +--- ----- +lease_id nomad/creds/test/6fb22e25-0cd1-b4c9-494e-aba330c317b9 +lease_duration 768h0m0s +lease_renewable true +accessor_id 10b8fb49-7024-2126-8683-ab355b581db2 +secret_id 8898d19c-e5b3-35e4-649e-4153d63fbea9 +``` + +Verify that the token is created correctly in Nomad, referring to it by its accessor: + + +``` +$ nomad acl token info 10b8fb49-7024-2126-8683-ab355b581db2 +Accessor ID = 10b8fb49-7024-2126-8683-ab355b581db2 +Secret ID = 8898d19c-e5b3-35e4-649e-4153d63fbea9 +Name = Vault test root 1507307164169530060 +Type = management +Global = true +Policies = n/a +Create Time = 2017-10-06 16:26:04.170633207 +0000 UTC +Create Index = 228 +Modify Index = 228 +``` From 2070aa1e1230ea43c1accc44fb17ecae64d5c1c3 Mon Sep 17 00:00:00 2001 From: Nicolas Corrarello Date: Fri, 6 Oct 2017 17:34:35 +0100 Subject: [PATCH 2/6] Minor cosmetic fix --- website/source/guides/acl.html.markdown | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/website/source/guides/acl.html.markdown b/website/source/guides/acl.html.markdown index d8dc18c06..c98b60e8e 100644 --- a/website/source/guides/acl.html.markdown +++ b/website/source/guides/acl.html.markdown @@ -400,14 +400,15 @@ have a separate token) - An unsealed Vault server ### Configuration -Mount the "nomad" secret backend in Vault +Mount the "nomad" secret backend in Vault: ``` $ vault mount nomad Successfully mounted 'nomad' at 'nomad'! ``` -Configure access with the right address and management token +Configure access with the right address and management token: + ``` $ vault write nomad/config/access \ address=http://127.0.0.1:4646 \ From 3a4b9abaf0f3d6020f9d903480b38a8d55c54d62 Mon Sep 17 00:00:00 2001 From: Nicolas Corrarello Date: Tue, 7 Nov 2017 15:11:41 +0000 Subject: [PATCH 3/6] Changed roles for role as the path changed in Vault --- website/source/guides/acl.html.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/source/guides/acl.html.markdown b/website/source/guides/acl.html.markdown index c98b60e8e..cf1fb69f9 100644 --- a/website/source/guides/acl.html.markdown +++ b/website/source/guides/acl.html.markdown @@ -421,14 +421,14 @@ to a potential identity based on Vault's policy. The name of the role is specifi the mapping to Nomad policies is done by naming them in a comma separated list, for example: ``` -$ vault write nomad/roles/role-name policy=policyone,policytwo +$ vault write nomad/role/role-name policy=policyone,policytwo Success! Data written to: nomad/roles/role-name ``` Alternatively, to create management tokens, or global tokens: ``` -$ vault write nomad/roles/role-name token_type=management global=true +$ vault write nomad/role/role-name token_type=management global=true Success! Data written to: nomad/roles/role-name ``` From d30bc34a2770ebbb265a82299227d1bc9f5d6687 Mon Sep 17 00:00:00 2001 From: Nicolas Corrarello Date: Tue, 23 Jan 2018 13:26:34 +0100 Subject: [PATCH 4/6] Introducing @schmichael suggestions --- website/source/guides/acl.html.markdown | 27 ++++++++++++++----------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/website/source/guides/acl.html.markdown b/website/source/guides/acl.html.markdown index fd3381e21..09c5cb3b4 100644 --- a/website/source/guides/acl.html.markdown +++ b/website/source/guides/acl.html.markdown @@ -377,7 +377,7 @@ using an pre-existing identity service (LDAP, Okta, Amazon IAM, etc. ...) in ord Nomad token. ~> Hashicorp Vault is a standalone product with it's own set of deployment and configuration best -practices. Please review Vault's documentation before deploying it in production. +practices. Please review [Vault's documentation](https://www.vaultproject.io/docs/index.html) before deploying it in production. For evaluation purposes, a Vault server in "dev" mode can be used. @@ -420,7 +420,7 @@ Root Token: f84b587e-5882-bba1-a3f0-d1a3d90ca105 - A management token (the bootstrap token can be used, but for production systems it's recommended to have a separate token) - A set of policies created in Nomad -- An unsealed Vault server +- An unsealed Vault server (Vault running in `dev` mode is unsealed automatically upon startup) ### Configuration Mount the "nomad" secret backend in Vault: @@ -439,23 +439,24 @@ $ vault write nomad/config/access \ Success! Data written to: nomad/config/access ``` -Vault secret backends have the concept of roles, configuration unit that group one or more policies -to a potential identity based on Vault's policy. The name of the role is specified on the path, while -the mapping to Nomad policies is done by naming them in a comma separated list, for example: +Vault secret backends have the concept of roles, which are configuration units that group one or more +Vault policies to a potential identity attribute, (Like an LDAP Group membership). The name of the role +is specified on the path, while the mapping to policies is done by naming them in a comma separated list, +for example: ``` $ vault write nomad/role/role-name policy=policyone,policytwo Success! Data written to: nomad/roles/role-name ``` -Alternatively, to create management tokens, or global tokens: +Similarly, to create management tokens, or global tokens: ``` -$ vault write nomad/role/role-name token_type=management global=true +$ vault write nomad/role/role-name type=management global=true Success! Data written to: nomad/roles/role-name ``` -A Vault policy is required to allow different identities to get tokens associated with a particular +Create a Vault policy to allow different identities to get tokens associated with a particular role: ``` @@ -467,7 +468,7 @@ Policy 'nomad-user-policy' written. If you have an existing authentication backend (like LDAP), follow the relevant instructions to create a role available on the [Authentication backends page](https://www.vaultproject.io/docs/auth/index.html). -Otherwise, for testing purposes, a token can be generated associated with the policy: +Otherwise, for testing purposes, a Vault token can be generated associated with the policy: ``` $ vault token-create -policy=nomad-user-policy @@ -477,7 +478,7 @@ token deedfa83-99b5-34a1-278d-e8fb76809a5b token_accessor fd185371-7d80-8011-4f45-1bb3af2c2733 token_duration 768h0m0s token_renewable true -token_policies [nomad-user-policy] +token_policies [default nomad-user-policy] ``` Finally obtain a Nomad Token using the existing Vault Token: @@ -493,8 +494,7 @@ accessor_id 10b8fb49-7024-2126-8683-ab355b581db2 secret_id 8898d19c-e5b3-35e4-649e-4153d63fbea9 ``` -Verify that the token is created correctly in Nomad, referring to it by its accessor: - +Verify that the token is created correctly in Nomad, looking it up by its accessor: ``` $ nomad acl token info 10b8fb49-7024-2126-8683-ab355b581db2 @@ -508,3 +508,6 @@ Create Time = 2017-10-06 16:26:04.170633207 +0000 UTC Create Index = 228 Modify Index = 228 ``` + +Any user or process with access to Vault can now obtain short lived Nomad Tokens in order to +carry out operations, thus centralising the access to Nomad tokens. From c946255459065fe15a373b42feeea74d7b9103ea Mon Sep 17 00:00:00 2001 From: Michael Schurter Date: Tue, 30 Jan 2018 11:14:05 -0800 Subject: [PATCH 5/6] Minor formatting/style updates --- website/source/guides/acl.html.markdown | 27 +++++++++++++++---------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/website/source/guides/acl.html.markdown b/website/source/guides/acl.html.markdown index 09c5cb3b4..9015313c4 100644 --- a/website/source/guides/acl.html.markdown +++ b/website/source/guides/acl.html.markdown @@ -371,13 +371,15 @@ This is because the reset file is in place, but with the incorrect index. The reset file can be deleted, but Nomad will not reset the bootstrap until the index is corrected. ## Vault Integration -Hashicorp Vault has a secret backend for generating short lived Nomad tokens. As Vault has a number of +Hashicorp Vault has a secret backend for generating short-lived Nomad tokens. As Vault has a number of authentication backends, it could provide a workflow where a user or orchestration system authenticates -using an pre-existing identity service (LDAP, Okta, Amazon IAM, etc. ...) in order to obtain a short-lived +using an pre-existing identity service (LDAP, Okta, Amazon IAM, etc.) in order to obtain a short-lived Nomad token. -~> Hashicorp Vault is a standalone product with it's own set of deployment and configuration best -practices. Please review [Vault's documentation](https://www.vaultproject.io/docs/index.html) before deploying it in production. +~> Hashicorp Vault is a standalone product with it's own set of deployment and + configuration best practices. Please review [Vault's + documentation](https://www.vaultproject.io/docs/index.html) before deploying it + in production. For evaluation purposes, a Vault server in "dev" mode can be used. @@ -412,25 +414,25 @@ want to seal/unseal the Vault or play with authentication. Unseal Key: YzFfPgnLl9R1f6bLU7tGqi/PIDhDaAV/tlNDMV5Rrq0= Root Token: f84b587e-5882-bba1-a3f0-d1a3d90ca105 - ``` ### Pre-requisites - Nomad ACL system bootstrapped. -- A management token (the bootstrap token can be used, but for production systems it's recommended to -have a separate token) +- A management token (the bootstrap token can be used, but for production + systems it's recommended to have a separate token) - A set of policies created in Nomad -- An unsealed Vault server (Vault running in `dev` mode is unsealed automatically upon startup) +- An unsealed Vault server (Vault running in `dev` mode is unsealed + automatically upon startup) ### Configuration -Mount the "nomad" secret backend in Vault: +Mount the [`nomad`][nomad_backend] secret backend in Vault: ``` $ vault mount nomad Successfully mounted 'nomad' at 'nomad'! ``` -Configure access with the right address and management token: +Configure access with Nomad's address and management token: ``` $ vault write nomad/config/access \ @@ -440,7 +442,7 @@ Success! Data written to: nomad/config/access ``` Vault secret backends have the concept of roles, which are configuration units that group one or more -Vault policies to a potential identity attribute, (Like an LDAP Group membership). The name of the role +Vault policies to a potential identity attribute, (e.g. LDAP Group membership). The name of the role is specified on the path, while the mapping to policies is done by naming them in a comma separated list, for example: @@ -511,3 +513,6 @@ Modify Index = 228 Any user or process with access to Vault can now obtain short lived Nomad Tokens in order to carry out operations, thus centralising the access to Nomad tokens. + + +[nomad_backend]: https://www.vaultproject.io/docs/secrets/nomad/index.html From 40b558e00d39d5c3f86b67491ff8a2115a5cb76f Mon Sep 17 00:00:00 2001 From: Michael Schurter Date: Tue, 30 Jan 2018 11:31:10 -0800 Subject: [PATCH 6/6] Mention minimum Vault version --- website/source/guides/acl.html.markdown | 1 + 1 file changed, 1 insertion(+) diff --git a/website/source/guides/acl.html.markdown b/website/source/guides/acl.html.markdown index 9015313c4..bd517c120 100644 --- a/website/source/guides/acl.html.markdown +++ b/website/source/guides/acl.html.markdown @@ -423,6 +423,7 @@ Root Token: f84b587e-5882-bba1-a3f0-d1a3d90ca105 - A set of policies created in Nomad - An unsealed Vault server (Vault running in `dev` mode is unsealed automatically upon startup) + - Vault must be version 0.9.3 or later to have the Nomad plugin ### Configuration Mount the [`nomad`][nomad_backend] secret backend in Vault: