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

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"]
+# }