docs(config): Document how to allow human operators to change their userpass password

README.md

@@ -21,10 +21,10 @@ Refer to [config/vault.hcl](config/vault.hcl) for content.
 Once Vault's initialized and with your `root` token in hand log in via the `token` auth method, make the following changes:
 * Add policies from [policies](policies) subdirectory into Vault
 * Create group `administrators`
-* Assign policies `administrator` and `auditor`
+* Assign policies `administrator` and `auditor` to that group
 * Create one entity to represent yourself as an administrator
-* Create on alias assigned to that entity for you to use as a username
-* Enable auth menthod `userpass`
+* Create one alias assigned to that entity for you to use as a username
+* Enable auth method `userpass`
 * Create one `userpass` username named like your alias, define your own password
 * Add your own entity to group `administrators`
 
@@ -60,7 +60,52 @@ Get the Vault command-line client via [vaultproject.io/downloads](https://www.va
     ----     ----    -----------
     file/    file    n/a
     ```
+* We're going to allow all human users to change their own `userpass` password. The policy to do so is at [policies/role-human/change-own-password.hcl](policies/role-human/change-own-password.hcl). For a hands-on example of an actual password change via HTTP API see [Hands-on](#hands-on) but first:
+
+    * Before you can load the policy into Vault you need to replace the string `ACCESSOR` in it with _your_ particular `userpass` accessor. Get it like so:
+        ```
+        # List auth methods
+        vault auth list
+
+        # Expected result similar to:
+        Path         Type        Accessor                  Description
+        ----         ----        --------                  -----------
+        token/       token       auth_token_d3aad127       token based credentials
+        userpass/    userpass    auth_userpass_6671d643    n/a
+        ```
+        Over in [policies/role-human/change-own-password.hcl](policies/role-human/change-own-password.hcl) replace `ACCESSOR` with what you're seeing here in the Accessor column. Feel free to read up on [templated policies](https://www.vaultproject.io/docs/concepts/policies#templated-policies) for more info.
+
+    * Load the policy
+    * Create a group for humans and assign the policy `change-own-password` to it.
+        ```
+        # Create group
+        vault write identity/group name="humans" policies="change-own-password"
+
+        # Expected output:
+        Success! Data written to: identity/group/name/humans
+        ```
+        Adding member entities to your group may be best done via Vault's UI. If we're just talking about a few member entities then the CLI does it like so:
+        ```
+        # Create group
+        vault write identity/group name="humans" policies="change-own-password" member_entity_ids="<uuid>,<uuid>,<uuid>"
+
+        # Expected output:
+        Success! Data written to: identity/group/name/humans
+        ```
+        Entity IDs are coming from `vault list identity/entity/id` and/or `vault read identity/entity/name/<name>`.
 
 ## Clean-up
 
 If during any of the above steps you've used the Vault command-line client to authenticate against Vault with your `root` token make sure that client's `~/.vault-token` file is deleted. It contains the verbatim `root` token.
+
+## Hands-on
+
+How to change a password via API call, see [docs at vaultproject.io](https://www.vaultproject.io/api-docs/auth/userpass#update-password-on-user):
+```
+curl \ 
+    --header 'X-Vault-Token: '"${vaultToken}" \ 
+    --request POST \ 
+    --data '{"password": "'"${newPassword}"'"}' \ 
+    'https://f.q.d.n/v1/auth/userpass/users/'"${username}"'/password'
+```
+If successful Vault will not return data. You may want to make response headers visible via `curl --include`. A successful password change results in an HTTP status code 204.

policies/role-administrator/administrator.hcl

@@ -57,3 +57,27 @@ path "sys/mounts"
 {
   capabilities = ["read"]
 }
+
+# Allow creation of groups
+path "identity/group"
+{
+  capabilities = ["update"]
+}
+
+# Allow renaming of groups
+path "identity/group/+/+"
+{
+  capabilities = ["update"]
+}
+
+# Allow listing and reading of groups and group attributes
+path "identity/groups/+/+"
+{
+  capabilities = ["list", "read"]
+}
+
+# Allow listing and reading of entities and entity attributes
+path "identity/entity/+/+"
+{
+  capabilities = ["list", "read"]
+}

policies/role-human/change-own-password.hcl

@@ -0,0 +1,26 @@
+# https://www.vaultproject.io/api-docs/auth/userpass#update-password-on-user:
+# Allow humans to change their own password. Per HashiCorp's Jeff Mitchell at
+# https://github.com/hashicorp/vault/issues/6590#issuecomment-531620507 we're
+# not using an 'allowed_parameters' limitation. Instead we directly use the
+# '/password' endpoint. This permits users to change their password via API and
+# Vault CLI client but not via UI.
+path "auth/userpass/users/{{identity.entity.aliases.ACCESSOR.name}}/password" {
+  capabilities = [ "update" ]
+}
+
+# The following policies extend permissions to also change password via UI. Note
+# that this (the second one below) grants permission to /see/ all existing
+# userpass usernames. If password changes via UI are important enough you may
+# want to live with this limitation. By default below policies remain commented
+# out.
+# path "sys/auth" {
+#   capabilities = ["read"]
+# }
+# 
+# path "auth/userpass/users/*" {
+#   capabilities = ["list"]
+# 
+# }
+# path "auth/userpass/users/{{identity.entity.aliases.ACCESSOR.name}}" {
+#   capabilities = ["read"]
+# }