layout | page_title | description |
---|---|---|
api |
/sys/policies/password - HTTP API |
The `/sys/policies/password` endpoints are used to manage password generation policies in Vault. |
The /sys/policies/password/
endpoints are used to manage password generation policies in Vault.
Not all secret engines utilize password policies, so check the documentation for the engine you
are using for compatibility.
~> Password policies are only available in Vault version 1.5+.
See Password Policies for details of how password policies work as well as the syntax of the policies themselves.
This endpoint adds a new or updates an existing password policy. Once a policy is updated, it takes effect immediately to all associated secret engines.
Prior to Vault saving the password policy, it will attempt to generate a number of passwords from the policy. This helps prevent creating password policies that are impossible to satisfy as well as prevent password policies that are overly restrictive which prevents both a poor security posture for the policy as well as preventing performance problems due to slow generation times.
Method | Path |
---|---|
POST |
/sys/policies/password/:name |
-
name
(string: <required>)
– Specifies the name of the password policy to create. This is specified as part of the request URL. -
policy
(string: <required>)
- Specifies the password policy document. This can be base64-encoded to avoid string escaping. See Password Policy Syntax for details on password policy definitions.
{
"policy": "length = 20\nrule \"charset\" { ..."
}
cURL:
$ cat payload.json
{
"policy": "length = 20\nrule \"charset\" {\n charset = \"abcde\"\n}\n"
}
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/sys/policies/password/my-policy
Vault CLI:
$ cat my-policy.hcl
length = 20
rule "charset" {
charset = "abcde"
}
$ vault write sys/policies/password/my-policy policy=@my-policy.hcl
This endpoints list the password policies.
Method | Path |
---|---|
LIST |
/sys/policies/password |
GET |
/sys/policies/password?list=true |
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/sys/policies/password
{
"request_id": "58e2540f-8c51-6390-46de-38e279e75468",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"keys": [
"my-policy"
]
},
"wrap_info": null,
"warnings": null,
"auth": null
}
This endpoint retrieves information about the named password policy.
Method | Path |
---|---|
GET |
/sys/policies/password/:name |
name
(string: <required>)
– Specifies the name of the password policy to retrieve. This is specified as part of the request URL.
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/sys/policies/password/my-policy
{
"policy": "length = 20\nrule \"charset\" { ..."
}
This endpoint deletes the password policy with the given name. This does not check if any secret engines are using it prior to deletion, so you should ensure that any engines that are utilizing this password policy are changed to a different policy (or to that engines' default behavior).
Method | Path |
---|---|
DELETE |
/sys/policies/password/:name |
name
(string: <required>)
– Specifies the name of the password policy to delete. This is specified as part of the request URL.
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE
http://127.0.0.1:8200/v1/sys/policies/password/my-policy
This endpoint generates a password from the specified existing password policy.
Method | Path |
---|---|
GET |
/sys/policies/password/:name/generate |
name
(string: <required>)
– Specifies the name of the password policy to generate a password from. This is specified as part of the request URL.
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/sys/policies/password/my-policy/generate
{
"password": "..."
}