162 lines
4.3 KiB
Plaintext
162 lines
4.3 KiB
Plaintext
---
|
||
layout: api
|
||
page_title: /sys/policies/password - HTTP API
|
||
description: >-
|
||
The `/sys/policies/password` endpoints are used to manage password generation policies in Vault.
|
||
---
|
||
|
||
# `/sys/policies/password/`
|
||
|
||
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](/docs/concepts/password-policies) for details of how password policies work
|
||
as well as the syntax of the policies themselves.
|
||
|
||
## Create/Update Password Policy
|
||
|
||
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 |
|
||
| :----- | :----------------------------- |
|
||
| `PUT` | `/sys/policies/password/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `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](/docs/concepts/password-policies#password-policy-syntax)
|
||
for details on password policy definitions.
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"policy": "length = 20\nrule \"charset\" { ..."
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
**cURL:**
|
||
|
||
```shell
|
||
$ cat payload.json
|
||
{
|
||
"policy": "length = 20\nrule \"charset\" {\n charset = \"abcde\"\n}\n"
|
||
}
|
||
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request PUT \
|
||
--data @payload.json \
|
||
http://127.0.0.1:8200/v1/sys/policies/password/my-policy
|
||
```
|
||
|
||
**Vault CLI:**
|
||
|
||
```shell
|
||
$ cat my-policy.hcl
|
||
length = 20
|
||
rule "charset" {
|
||
charset = "abcde"
|
||
}
|
||
|
||
$ vault write sys/policies/password/my-policy policy=@my-policy.hcl
|
||
```
|
||
|
||
## Read Password Policy
|
||
|
||
This endpoint retrieves information about the named password policy.
|
||
|
||
| Method | Path |
|
||
| :----- | :----------------------------- |
|
||
| `GET` | `/sys/policies/password/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` – Specifies the name of the password policy to retrieve.
|
||
This is specified as part of the request URL.
|
||
|
||
### Sample Request
|
||
|
||
```shell
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/sys/policies/password/my-policy
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"policy": "length = 20\nrule \"charset\" { ..."
|
||
}
|
||
```
|
||
|
||
## Delete Password Policy
|
||
|
||
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` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` – Specifies the name of the password policy to delete.
|
||
This is specified as part of the request URL.
|
||
|
||
### Sample Request
|
||
|
||
```shell
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request DELETE
|
||
http://127.0.0.1:8200/v1/sys/policies/password/my-policy
|
||
```
|
||
|
||
## Generate Password from Password Policy
|
||
|
||
This endpoint generates a password from the specified existing password policy.
|
||
|
||
| Method | Path |
|
||
| :----- | :-------------------------------------- |
|
||
| `GET` | `/sys/policies/password/:name/generate` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` – Specifies the name of the password policy to generate
|
||
a password from. This is specified as part of the request URL.
|
||
|
||
### Sample Request
|
||
|
||
```shell
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/sys/policies/password/my-policy/generate
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"password": "..."
|
||
}
|
||
```
|