More detailed descriptions were added
This commit is contained in:
Yoko Hyakuna
parent
358f95553c
commit
9df839e446
BIN
website/source/assets/images/vault-approle-workflow.png
(Stored with Git LFS)
BIN
website/source/assets/images/vault-approle-workflow.png
(Stored with Git LFS)
Binary file not shown.
BIN
website/source/assets/images/vault-policy-workflow.png
(Stored with Git LFS)
Normal file
BIN
website/source/assets/images/vault-policy-workflow.png
(Stored with Git LFS)
Normal file
Binary file not shown.
|
|
@ -133,8 +133,9 @@ The basic workflow is:
|
|||
|
||||
|
||||
> For the purpose of introducing the basics of AppRole, this guide walks you
|
||||
> through a very simple scenario involving only two personas. Please refer to
|
||||
> the [Advanced Features](#advanced-features) section for further discussions.
|
||||
> through a very simple scenario involving only two personas (admin and app).
|
||||
> Please refer to the [Advanced Features](#advanced-features) section for
|
||||
> further discussions after completing the following steps.
|
||||
|
||||
In this guide, you are going to perform the following steps:
|
||||
|
||||
|
|
@ -155,13 +156,15 @@ Like many other auth backends, AppRole must be enabled before it can be used.
|
|||
|
||||
#### CLI command
|
||||
|
||||
Enable `approle` auth backend by executing the following command:
|
||||
|
||||
```shell
|
||||
$ vault auth-enable approle
|
||||
```
|
||||
|
||||
#### API call using cURL
|
||||
|
||||
Enable `approle` auth backend using `/sys/auth` endpoint:
|
||||
Enable `approle` auth backend by mounting its endpoint at `/sys/auth/approle`:
|
||||
|
||||
```shell
|
||||
$ curl --header "X-Vault-Token: <TOKEN>" \
|
||||
|
|
@ -191,7 +194,7 @@ at the `sys/auth/approle` endpoint.
|
|||
|
||||
When you enabled AppRole auth backend, it gets mounted at the
|
||||
**`/auth/approle`** path. In this example, you are going to create a role for
|
||||
**`app`** persona (Jenkins) .
|
||||
**`app`** persona (`jenkins` in our scenario).
|
||||
|
||||
The scenario in this guide requires the `app` to have the
|
||||
following policy (`jenkins-pol.hcl`):
|
||||
|
|
@ -219,12 +222,17 @@ $ vault policy-write jenkins jenkins-pol.hcl
|
|||
The command to create a new AppRole:
|
||||
|
||||
```shell
|
||||
$ vault write auth/approle/role/<ROLE_NAME> [args]
|
||||
$ vault write auth/approle/role/<ROLE_NAME> [parameters]
|
||||
```
|
||||
|
||||
There are a number of [parameters](/api/auth/approle/index.html) that you can
|
||||
set. Most importantly, you want to specify the policies when you create a role.
|
||||
|
||||
> There are a number of
|
||||
> [parameters](/api/auth/approle/index.html#create-new-approle) that you can set
|
||||
> on a role. If you want to limit the use of the generated secret ID, set
|
||||
> `secret_id_num_uses` or `secret_id_ttl` parameter values. Similarly, you can
|
||||
> specify `token_num_uses` and `token_ttl`. You may never want the app token to
|
||||
> expire. In such a case, specify the `period` so that the token generated by
|
||||
> this AppRole is a periodic token. To learn more about periodic token, refer to
|
||||
> the [Tokens and Leases](/guifes/lease.html#step4) guide.
|
||||
|
||||
**Example:**
|
||||
|
||||
|
|
@ -272,11 +280,7 @@ $ cat payload.json
|
|||
}
|
||||
```
|
||||
|
||||
There are a number of [parameters](/api/auth/approle/index.html) that you can
|
||||
set. Most importantly, you want to specify the policies when you create a role.
|
||||
|
||||
You are going to create a role operates in [**pull** mode](/docs/auth/approle.html)
|
||||
in this example.
|
||||
Now, you are ready to create a role.
|
||||
|
||||
**Example:**
|
||||
|
||||
|
|
@ -288,9 +292,31 @@ mode](/docs/auth/approle.html).)
|
|||
$ curl --header "X-Vault-Token: ..." --request POST \
|
||||
--data '{"policies":"jenkins"}' \
|
||||
https://vault.rocks/v1/auth/approle/role/jenkins
|
||||
```
|
||||
|
||||
> There are a number of
|
||||
> [parameters](/api/auth/approle/index.html#create-new-approle) that you can set
|
||||
> on a role. If you want to limit the use of the generated secret ID, set
|
||||
> `secret_id_num_uses` or `secret_id_ttl` parameter values. Similarly, you can
|
||||
> specify `token_num_uses` and `token_ttl`. You may never want the app token to
|
||||
> expire. In such a case, specify the `period` so that the token generated by
|
||||
> this AppRole is a periodic token. To learn more about periodic token, refer to
|
||||
> the [Tokens and Leases](/guifes/lease.html#step4) guide.
|
||||
|
||||
|
||||
# Read the jenkins role
|
||||
**NOTE:** To attach multiple policies, pass the policy names as a comma
|
||||
separated string.
|
||||
|
||||
```shell
|
||||
$ curl --header "X-Vault-Token:..."
|
||||
--request POST \
|
||||
--data '{"policies":"jenkins,anotherpolicy"}' \
|
||||
https://vault.rocks/v1/auth/approle/role/jenkins
|
||||
````
|
||||
|
||||
To read the jenkins role you just created:
|
||||
|
||||
```shell
|
||||
$ curl --header "X-Vault-Token: ..." --request GET \
|
||||
https://vault.rocks/v1/auth/approle/role/jenkins | jq
|
||||
{
|
||||
|
|
@ -317,44 +343,37 @@ $ curl --header "X-Vault-Token: ..." --request GET \
|
|||
}
|
||||
```
|
||||
|
||||
**NOTE:** To attach multiple policies, pass the policy names as a comma
|
||||
separated string.
|
||||
|
||||
```shell
|
||||
$ curl --header "X-Vault-Token:..."
|
||||
--request POST \
|
||||
--data '{"policies":"jenkins,anotherpolicy"}' \
|
||||
https://vault.rocks/v1/auth/approle/role/jenkins
|
||||
````
|
||||
|
||||
### <a name="step3"></a>Step 3: Get Role ID and Secret ID
|
||||
(**Persona:** admin)
|
||||
|
||||
Think of **Role ID** and **Secret ID** as the username and password which apps
|
||||
use to authenticate with Vault.
|
||||
**Role ID** and **Secret ID** are like username and password which a machine or
|
||||
app uses to authenticate.
|
||||
|
||||
Since the example created a `jenkins` role which operates in pull mode, Vault
|
||||
will generate the Secret ID. Similarly to tokens, you can set properties such as
|
||||
usage-limit, TTLs, and expirations on the secret IDs.
|
||||
will generate the Secret ID. You can set properties such as usage-limit, TTLs,
|
||||
and expirations on the secret IDs to control its lifecycle.
|
||||
|
||||
#### CLI command
|
||||
|
||||
Now, you need to fetch the Role ID and Secret ID of a role.
|
||||
|
||||
To read role ID:
|
||||
To read the Role ID:
|
||||
|
||||
```shell
|
||||
$ vault read auth/approle/role/<ROLE_NAME>/role-id
|
||||
```
|
||||
|
||||
To generate a new secret ID:
|
||||
To generate a new Secret ID:
|
||||
|
||||
```shell
|
||||
$ vault write -f auth/approle/role/<ROLE_NAME>/secret-id
|
||||
```
|
||||
|
||||
The `write` operation is equivalent to `POST` or `PUT` HTTP verbs. The `-f` flag
|
||||
forces the `write` operation to continue without any data values specified.
|
||||
NOTE: The `-f` flag forces the `write` operation to continue without any data
|
||||
values specified. Alternatively, you can set
|
||||
[parameters](/api/auth/approle/index.html#generate-new-secret-id) such as
|
||||
`cidr_list`.
|
||||
|
||||
**Example:**
|
||||
|
||||
|
|
@ -371,10 +390,13 @@ $ vault write -f auth/approle/role/jenkins/secret-id
|
|||
secret_id_accessor a240a31f-270a-4765-64bd-94ba1f65703c
|
||||
```
|
||||
|
||||
If you specified `secret_id_ttl`, `secret_id_num_uses`, or `bound_cidr_list` on
|
||||
the role in [Step 2](#step2), the generated secret ID carries out the conditions.
|
||||
|
||||
|
||||
#### API call using cURL
|
||||
|
||||
To read role ID:
|
||||
To read the Role ID:
|
||||
|
||||
```shell
|
||||
$ curl --header "X-Vault-Token:..." \
|
||||
|
|
@ -382,14 +404,19 @@ $ curl --header "X-Vault-Token:..." \
|
|||
<VAULT_ADDRESS>/v1/auth/approle/role/<ROLE_NAME>/role-id
|
||||
```
|
||||
|
||||
To generate a new secret ID:
|
||||
To generate a new Secret ID:
|
||||
|
||||
```shell
|
||||
$ curl --header "X-Vault-Token:..." \
|
||||
--request POST \
|
||||
--data <PARAMETERS>
|
||||
<VAULT_ADDRESS>/v1/auth/approle/role/<ROLE_NAME>/secret-id
|
||||
```
|
||||
|
||||
You can pass
|
||||
[parameters](/api/auth/approle/index.html#generate-new-secret-id) in the request
|
||||
payload, or invoke the API with empty payload.
|
||||
|
||||
**Example:**
|
||||
|
||||
```shell
|
||||
|
|
@ -400,16 +427,16 @@ $ curl --header "X-Vault-Token:..." --request POST \
|
|||
https://vault.rocks/v1/auth/approle/role/jenkins/secret-id | jq
|
||||
```
|
||||
|
||||
The above example to generate a new Secret ID does not have any payload.
|
||||
Optionally, you can pass
|
||||
[parameters](/api/auth/approle/index.html#generate-new-secret-id) in the request
|
||||
payload.
|
||||
If you specified `secret_id_ttl`, `secret_id_num_uses`, or `bound_cidr_list` on
|
||||
the role in [Step 2](#step2), the generated secret ID carries out the conditions.
|
||||
|
||||
|
||||
|
||||
### <a name="step4"></a>Step 4: Login with Role ID & Secret ID
|
||||
(**Persona:** app)
|
||||
|
||||
The client (in this case, Jenkins) uses the role ID and secret ID to
|
||||
authenticate with Vault. If the expecting client did not receive the role ID and
|
||||
The client (in this case, Jenkins) uses the role ID and secret ID passed by the
|
||||
admin to authenticate with Vault. If Jenkins did not receive the role ID and/or
|
||||
secret ID, the admin needs to investigate.
|
||||
|
||||
-> Refer to the [Advanced Features](#advanced-features) section for further
|
||||
|
|
@ -436,7 +463,7 @@ $ vault write auth/approle/login role_id="675a50e7-cfe0-be76-e35f-49ec009731ea"
|
|||
token_meta_role_name "jenkins"
|
||||
```
|
||||
|
||||
Now you have a client token with `default` and `jenkins` policies attached.
|
||||
Now you have a **client token** with `default` and `jenkins` policies attached.
|
||||
|
||||
|
||||
#### API call using cURL
|
||||
|
|
@ -447,13 +474,13 @@ in the request payload.
|
|||
**Example:**
|
||||
|
||||
```plaintext
|
||||
$ cat jenkins.json
|
||||
$ cat payload.json
|
||||
{
|
||||
"role_id": "675a50e7-cfe0-be76-e35f-49ec009731ea",
|
||||
"secret_id": "ed0a642f-2acf-c2da-232f-1b21300d5f29"
|
||||
}
|
||||
|
||||
$ curl --request POST --data @jenkins.json https://vault.rocks/v1/auth/approle/login | jq
|
||||
$ curl --request POST --data @payload.json https://vault.rocks/v1/auth/approle/login | jq
|
||||
{
|
||||
"request_id": "fccae32b-1e6a-9a9c-7666-f5cb07805c1e",
|
||||
"lease_id": "",
|
||||
|
|
@ -479,14 +506,14 @@ $ curl --request POST --data @jenkins.json https://vault.rocks/v1/auth/approle/l
|
|||
}
|
||||
```
|
||||
|
||||
Now you have a client token with `default` and `jenkins` policies attached.
|
||||
Now you have a **client token** with `default` and `jenkins` policies attached.
|
||||
|
||||
|
||||
### <a name="step5"></a>Step 5: Read secrets using the AppRole token
|
||||
(**Persona:** app)
|
||||
|
||||
Once the client acquired the token, the future requests can be made using
|
||||
that token.
|
||||
Once receiving a token from Vault, the client can make future requests using
|
||||
this token.
|
||||
|
||||
#### CLI command
|
||||
|
||||
|
|
@ -576,23 +603,22 @@ This time, it should return the values you just created.
|
|||
## Advanced Features
|
||||
|
||||
The Role ID is equivalent to a username, and Secret ID is the corresponding
|
||||
password. The app needs both to login with Vault. Naturally, the next question
|
||||
password. The app needs both to log in with Vault. Naturally, the next question
|
||||
becomes how to deliver those values to the expecting client.
|
||||
|
||||
Common solution involves **three personas** instead of two: `admin`, `app`, and
|
||||
`trusted entity`. Furthermore, the Role ID and Secret ID are delivered to the
|
||||
client separately by the `trusted entity`.
|
||||
|
||||
|
||||
A common solution involves **three personas** instead of two: `admin`, `app`, and
|
||||
`trusted entity`. The `trusted entity` delivers the Role ID and Secret ID to the
|
||||
client by separate means.
|
||||
|
||||
For example, Terraform injects the Role ID onto the virtual machine. When the
|
||||
app runs on the virtual machine, the Role ID already exists on the virtual
|
||||
machine.
|
||||
|
||||
|
||||
|
||||
Secret ID is like a password. To keep the Secret ID confidential, use
|
||||
[**response wrapping**](/docs/concepts/response-wrapping.html) so that the only
|
||||
expected client can unwrap the Secret ID. The `admin` user don't even see the
|
||||
generated token.
|
||||
expected client can unwrap the Secret ID.
|
||||
|
||||
In [Step 3](#step3), you executed the following command to retrieve the Secret
|
||||
ID:
|
||||
|
|
@ -627,7 +653,7 @@ secret_id 575f23e4-01ad-25f7-2661-9c9bdbb1cf81
|
|||
secret_id_accessor 7d8a40b7-a6fd-a634-579b-b7d673ff86fb
|
||||
```
|
||||
|
||||
To retrieve the Secret ID alone, you can use `jq` as follow:
|
||||
NOTE: To retrieve the Secret ID alone, you can use `jq` as follow:
|
||||
|
||||
```shell
|
||||
$ VAULT_TOKEN=2577044d-cf86-a065-e28f-e2a14ea6eaf7 vault unwrap -format=json | jq -r ".data.secret_id"
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ you through the generation of dynamic AWS credentials.
|
|||
The end-to-end scenario described in this guide involves two personas:
|
||||
|
||||
- **`admin`** with privileged permissions to configure secret backends
|
||||
- **`app`** is the requester of credentials
|
||||
- **`apps`** reads the secrets from Vault
|
||||
|
||||
## Challenge
|
||||
|
||||
|
|
@ -147,10 +147,21 @@ must be mounted.
|
|||
|
||||
#### CLI command
|
||||
|
||||
To mount a database backend:
|
||||
|
||||
```shell
|
||||
vault mount database
|
||||
$ vault mount <PATH>
|
||||
```
|
||||
|
||||
**Example:**
|
||||
|
||||
```shell
|
||||
$ vault mount database
|
||||
```
|
||||
|
||||
**NOTE:** In this guide, the database backend is mounted at the `/database path` in
|
||||
Vault. However, it is possible to mount your secret backends at any location.
|
||||
|
||||
#### API call using cURL
|
||||
|
||||
Mount `database` secret backend using `/sys/mounts` endpoint:
|
||||
|
|
@ -159,7 +170,7 @@ Mount `database` secret backend using `/sys/mounts` endpoint:
|
|||
$ curl --header "X-Vault-Token: <TOKEN>" \
|
||||
--request POST \
|
||||
--data <PARAMETERS> \
|
||||
<VAULT_ADDRESS>/v1/sys/mounts/database
|
||||
<VAULT_ADDRESS>/v1/sys/mounts/<PATH>
|
||||
```
|
||||
|
||||
Where `<TOKEN>` is your valid token, and `<PARAMETERS>` holds [configuration
|
||||
|
|
@ -177,6 +188,8 @@ $ curl --header "X-Vault-Token: ..." \
|
|||
https://$ vault.rocks/v1/sys/mounts/database
|
||||
```
|
||||
|
||||
**NOTE:** It is possible to mount your database secret backends at any location.
|
||||
|
||||
|
||||
### <a name="step1"></a>Step 2: Configure PostgreSQL backend
|
||||
(**Persona:** admin)
|
||||
|
|
@ -212,10 +225,10 @@ $ vault write database/config/postgresql plugin_name=postgresql-database-plugin
|
|||
**Example:**
|
||||
|
||||
```shell
|
||||
$ curl --header "X-Vault-Token: ..." --request POST --data @postgres-config.json \
|
||||
$ curl --header "X-Vault-Token: ..." --request POST --data @payload.json \
|
||||
https://vault.rocks/v1/database/config/postgresql
|
||||
|
||||
$ cat postgres-config.json
|
||||
$ cat payload.json
|
||||
{
|
||||
"plugin_name": "postgresql-database-plugin",
|
||||
"allowed_roles": "readonly",
|
||||
|
|
@ -249,7 +262,7 @@ if Vault is offline or unable to communicate with it.
|
|||
|
||||
**Example:**
|
||||
|
||||
```plaintext
|
||||
```shell
|
||||
$ vault write database/roles/readonly db_name=postgresql creation_statements=@readonly.sql \
|
||||
default_ttl=1h max_ttl=24h
|
||||
```
|
||||
|
|
@ -263,10 +276,10 @@ statement is passed as the role creation statement.
|
|||
**Example:**
|
||||
|
||||
```shell
|
||||
$ curl --header "X-Vault-Token: ..." --request POST --data @role-payload.json \
|
||||
$ curl --header "X-Vault-Token: ..." --request POST --data @payload.json \
|
||||
https://vault.rocks/v1/database/roles/readonly
|
||||
|
||||
$ cat role-payload.json
|
||||
$ cat payload.json
|
||||
{
|
||||
"db_name": "postgres",
|
||||
"creation_statements": "CREATE ROLE '{{name}}' WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}';
|
||||
|
|
@ -281,9 +294,9 @@ the `role-payload.json`.
|
|||
|
||||
|
||||
### <a name="step4"></a>Step 4: Request PostgreSQL credentials
|
||||
(**Persona:** app)
|
||||
(**Persona:** apps)
|
||||
|
||||
Now, you are switching to [`app` persona](#personas). To get a new set of
|
||||
Now, you are switching to [`apps` persona](#personas). To get a new set of
|
||||
PostgreSQL credentials, the client app needs to be able to **read** from the
|
||||
`readonly` role endpoint. Therefore, the app's token must have a policy granting
|
||||
the read permission.
|
||||
|
|
@ -300,14 +313,16 @@ path "database/creds/readonly" {
|
|||
#### CLI command
|
||||
|
||||
First create an `apps` policy, and generate a token so that you can authenticate
|
||||
as an `app` persona.
|
||||
as an `apps` persona.
|
||||
|
||||
**Example:**
|
||||
|
||||
```shell
|
||||
# Create "apps" policy
|
||||
$ vault policy-write apps apps-policy.hcl
|
||||
Policy 'apps' written.
|
||||
|
||||
# Create a new token with app policy
|
||||
$ vault token-create -policy="apps"
|
||||
Key Value
|
||||
--- -----
|
||||
|
|
@ -324,12 +339,14 @@ Use the returned token to perform the remaining.
|
|||
demonstrates more sophisticated way of generating a token for your apps.
|
||||
|
||||
```shell
|
||||
# Authenticate with Vault using the generated token first
|
||||
$ vault auth e4bdf7dc-cbbf-1bb1-c06c-6a4f9a826cf2
|
||||
Successfully authenticated! You are now logged in.
|
||||
token: e4bdf7dc-cbbf-1bb1-c06c-6a4f9a826cf2
|
||||
token_duration: 2764277
|
||||
token_policies: [apps default]
|
||||
|
||||
# Invoke the vault command
|
||||
$ vault read database/creds/readonly
|
||||
|
||||
Key Value
|
||||
|
|
@ -352,15 +369,18 @@ First create an `apps` policy, and generate a token so that you can authenticate
|
|||
as an `app` persona.
|
||||
|
||||
```shell
|
||||
$ curl --header "X-Vault-Token: ..." --request PUT \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/policy/apps
|
||||
|
||||
# Payload to pass in the API call
|
||||
$ cat payload.json
|
||||
{
|
||||
"policy": "path \"database/creds/readonly\" {capabilities = [ \"read\" ]}"
|
||||
}
|
||||
|
||||
# Create "apps" policy
|
||||
$ curl --header "X-Vault-Token: ..." --request PUT \
|
||||
--data @payload.json \
|
||||
https://vault.rocks/v1/sys/policy/apps
|
||||
|
||||
# Generate a new token with apps policy
|
||||
$ curl --header "X-Vault-Token: ..." --request POST \
|
||||
--data '{"policies": ["apps"]}' \
|
||||
https://vault.rocks/v1/auth/token/create | jq
|
||||
|
|
|
|||
|
|
@ -8,8 +8,8 @@ description: |-
|
|||
|
||||
# Policies
|
||||
|
||||
Use policy to govern the behavior of clients by specifying the access privilege
|
||||
(_authorization_).
|
||||
In Vault, use policies to govern the behavior of clients by specifying the
|
||||
access privilege (_authorization_).
|
||||
|
||||
When you first initialize Vault, the
|
||||
[**`root`**](/docs/concepts/policies.html#root-policy) policy gets created by
|
||||
|
|
@ -47,11 +47,22 @@ valid input.
|
|||
|
||||
10 minutes
|
||||
|
||||
## Personas
|
||||
|
||||
The scenario described in this guide introduces the following personas:
|
||||
|
||||
- **`root`** sets up initial policies for `admin`
|
||||
- **`admin`** is empowered with managing a Vault infrastructure for a team or
|
||||
organizations
|
||||
- **`provisioner`** configures secret backends as well as creating policies for
|
||||
client apps
|
||||
|
||||
|
||||
## Challenge
|
||||
|
||||
Since Vault centrally secure, store, and access control secrets across distributed
|
||||
infrastructure and applications, it is critical to control permissions before
|
||||
any user or machine can gain access.
|
||||
Since Vault centrally secure, store, and access control secrets across
|
||||
distributed infrastructure and applications, it is critical to control
|
||||
permissions before any user or machine can gain access.
|
||||
|
||||
|
||||
## Solution
|
||||
|
|
@ -68,26 +79,64 @@ Vault.
|
|||
|
||||
To perform the tasks described in this guide, you need to have a Vault
|
||||
environment. Refer to the [Getting
|
||||
Started](/intro/getting-started/install.html) guide to install Vault.
|
||||
|
||||
Make sure that your Vault server has been [initialized and
|
||||
Started](/intro/getting-started/install.html) guide to install Vault. Make sure
|
||||
that your Vault server has been [initialized and
|
||||
unsealed](/intro/getting-started/deploy.html).
|
||||
|
||||
### <a name="policy"></a>Policy requirements
|
||||
|
||||
Since this guide demonstrates the creation of an **`admin`** policy, log in with
|
||||
**`root`** token if possible. Otherwise, make sure that you have the following
|
||||
permissions:
|
||||
|
||||
```shell
|
||||
# To perform Step 2 & 3
|
||||
path "sys/policy/*"
|
||||
{
|
||||
capabilities = ["create", "read", "update", "delete", "list"]
|
||||
}
|
||||
|
||||
# To perform Step 4
|
||||
path "auth/token/create"
|
||||
{
|
||||
capabilities = ["create", "update"]
|
||||
}
|
||||
|
||||
# To perform Step 4
|
||||
path "sys/capabilities"
|
||||
{
|
||||
capabilities = ["create", "update"]
|
||||
}
|
||||
|
||||
# To perform Step 4
|
||||
path "sys/capabilities-self"
|
||||
{
|
||||
capabilities = ["create", "update"]
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Steps
|
||||
|
||||
The basic workflow of creating policies is:
|
||||
|
||||
|
||||
|
||||
This guide demonstrates basic policy authoring and management tasks.
|
||||
|
||||
1. [Write ACL policies](#step1)
|
||||
2. [View existing policies](#step2)
|
||||
3. [Check capabilities of a token](#step3)
|
||||
1. [Write ACL policies in HCL format](#step1)
|
||||
2. [Create policies](#step2)
|
||||
3. [View existing policies](#step3)
|
||||
4. [Check capabilities of a token](#step4)
|
||||
|
||||
|
||||
### <a name="step1"></a>Step 1: Write ACL policies
|
||||
### <a name="step1"></a>Step 1: Write ACL policies in HCL format
|
||||
|
||||
ACL policies are defined for each path:
|
||||
Remember, empty policy grants **no permission** in the system. Therefore, ACL
|
||||
policies are defined for each path.
|
||||
|
||||
```plaintext
|
||||
path "<PAHT>" {
|
||||
```shell
|
||||
path "<PATH>" {
|
||||
capabilities = [ "<LIST_OF_CAPABILITIES>" ]
|
||||
}
|
||||
```
|
||||
|
|
@ -96,7 +145,7 @@ path "<PAHT>" {
|
|||
namespacing. For example, "`secret/training_*`" grants permissions on any
|
||||
path starts with "`secret/training_`" (e.g. `secret/training_vault`).
|
||||
|
||||
Define one or more capabilities on each path to control operations that are
|
||||
Define one or more [capabilities](/docs/concepts/policies.html#capabilities) on each path to control operations that are
|
||||
permitted.
|
||||
|
||||
| Capability | Associated HTTP verbs |
|
||||
|
|
@ -110,73 +159,127 @@ permitted.
|
|||
|
||||
#### Policy requirements
|
||||
|
||||
First step in writing policies is to gather policy requirements. As an exercise,
|
||||
assume that the following are the policy requirements defined for `developers`
|
||||
and `devops`.
|
||||
First step in creating policies is to **gather policy requirements**.
|
||||
|
||||
Developers must be able to:
|
||||
**Example:**
|
||||
|
||||
- Perform all operations on `secret/apps/*` path
|
||||
- Obtain AWS credentials for `devops` role
|
||||
- Obtain database credentials for `devops` role
|
||||
**`admin`** is a type of user empowered with managing a Vault infrastructure for
|
||||
a team or organizations. Empowered with sudo, the Administrator is focused on
|
||||
configuring and maintaining the health of Vault cluster(s) as well as
|
||||
providing bespoke support to Vault users.
|
||||
|
||||
DevOps must be able to:
|
||||
`admin` must be able to:
|
||||
|
||||
- View and manage leases
|
||||
- Mount and manage auth backends broadly across Vault
|
||||
- Mount and manage secret backends broadly across Vault
|
||||
- Create and manage ACL policies broadly across Vault
|
||||
- Read system health check
|
||||
|
||||
**`provisioner`** is a type of user or service that will be used by an automated
|
||||
tool (e.g. Terraform) to provision and configure a namespace within a Vault
|
||||
secret backend for a new Vault user to access and write secrets.
|
||||
|
||||
`provisioner` must be able to:
|
||||
|
||||
- Mount and manage auth backends
|
||||
- Mount and manage secret backends
|
||||
- Create and manage ACL policies
|
||||
|
||||
#### Example policy for Developers
|
||||
|
||||
`dev-pol.hcl`
|
||||
Now, you are ready to author policies to fulfill the requirements.
|
||||
|
||||
#### Example policy for admin
|
||||
|
||||
`admin-policy.hcl`
|
||||
|
||||
```shell
|
||||
# Full permissions on secret/apps/* path
|
||||
path "secret/apps/*" {
|
||||
capabilities = ["create", "read", "update", "delete", "list"]
|
||||
# Manage auth backends broadly across Vault
|
||||
path "auth/*"
|
||||
{
|
||||
capabilities = ["create", "read", "update", "delete", "list", "sudo"]
|
||||
}
|
||||
|
||||
# Read new credentials from aws secret backend
|
||||
path "aws/creds/devops" {
|
||||
capabilities = ["read"]
|
||||
# List, create, update, and delete auth backends
|
||||
path "sys/auth/*"
|
||||
{
|
||||
capabilities = ["create", "read", "update", "delete", "sudo"]
|
||||
}
|
||||
|
||||
# Read new credentials from database secret backend
|
||||
path "database/creds/devops" {
|
||||
capabilities = ["read"]
|
||||
# Create and manage ACL policies broadly across Vault
|
||||
path "sys/policy/*"
|
||||
{
|
||||
capabilities = ["create", "read", "update", "delete", "list", "sudo"]
|
||||
}
|
||||
|
||||
# List, create, update, and delete key/value secrets
|
||||
path "secret/*"
|
||||
{
|
||||
capabilities = ["create", "read", "update", "delete", "list", "sudo"]
|
||||
}
|
||||
|
||||
# Manage and manage secret backends broadly across Vault.
|
||||
path "sys/mounts/*"
|
||||
{
|
||||
capabilities = ["create", "read", "update", "delete", "list", "sudo"]
|
||||
}
|
||||
|
||||
# Read health checks
|
||||
path "sys/health"
|
||||
{
|
||||
capabilities = ["read", "sudo"]
|
||||
}
|
||||
```
|
||||
|
||||
#### Example policy for DevOps
|
||||
#### Example policy for provisioner
|
||||
|
||||
`devops-pol.hcl`
|
||||
`provisioner-policy.hcl`
|
||||
|
||||
```shell
|
||||
# Permissions to manage leases
|
||||
path "sys/leases/*" {
|
||||
# Manage auth backends broadly across Vault
|
||||
path "auth/*"
|
||||
{
|
||||
capabilities = ["create", "read", "update", "delete", "list"]
|
||||
}
|
||||
|
||||
# Permissions to create and manage secret backends
|
||||
path "sys/mounts/*" {
|
||||
# List, create, update, and delete auth backends
|
||||
path "sys/auth/*"
|
||||
{
|
||||
capabilities = ["create", "read", "update", "delete"]
|
||||
}
|
||||
|
||||
# Create and manage ACL policies
|
||||
path "sys/policy/*"
|
||||
{
|
||||
capabilities = ["create", "read", "update", "delete", "list"]
|
||||
}
|
||||
|
||||
# Move already mounted backend to a new endpoint
|
||||
path "sys/remount/*" {
|
||||
capabilities = ["create", "update"]
|
||||
# List, create, update, and delete key/value secrets
|
||||
path "secret/*"
|
||||
{
|
||||
capabilities = ["create", "read", "update", "delete", "list"]
|
||||
}
|
||||
```
|
||||
|
||||
Once the ACL policies are written, create policies.
|
||||
### <a name="step2"></a>Step 2: Create policies
|
||||
|
||||
Now, create `admin` and `provisioner` policies in Vault.
|
||||
|
||||
#### CLI command
|
||||
|
||||
Create new ACL policies:
|
||||
To create policies:
|
||||
|
||||
```shell
|
||||
$ vault write dev-pol dev-pol.hcl
|
||||
$ vault policy-write <POLICY_NAME> <POLICY_FILE>
|
||||
```
|
||||
|
||||
$ vault write devops-pol devops-pol.hcl
|
||||
**Example:**
|
||||
|
||||
```shell
|
||||
# Create admin policy
|
||||
$ vault write admin admin-policy.hcl
|
||||
|
||||
# Create provisioner policy
|
||||
$ vault write provisioner provisioner-policy.hcl
|
||||
```
|
||||
|
||||
**NOTE:** To update an existing policy, simply re-run the same command by
|
||||
|
|
@ -184,122 +287,125 @@ passing your modified policy (`*.hcl`).
|
|||
|
||||
#### API call using cURL
|
||||
|
||||
Before begin, create the following environment variables for your convenience:
|
||||
To create a policy, use `/sys/policy` endpoint:
|
||||
|
||||
- **VAULT_ADDR** is set to your Vault server address
|
||||
- **VAULT_TOKEN** is set to your Vault token
|
||||
```shell
|
||||
$ curl --header "X-Vault-Token: <TOKEN>" \
|
||||
--request PUT \
|
||||
--data <PAYLOAD> \
|
||||
<VAULT_ADDRESS>/v1/sys/policy/<POLICY_NAME>
|
||||
```
|
||||
|
||||
Where `<TOKEN>` is your valid token, and `<PAYLOAD>` includes policy name and
|
||||
stringfied policy.
|
||||
|
||||
**Example:**
|
||||
|
||||
```plaintext
|
||||
$ export VAULT_ADDR=http://127.0.0.1:8201
|
||||
|
||||
$ export VAULT_TOKEN=0c4d13ba-9f5b-475e-faf2-8f39b28263a5
|
||||
```
|
||||
|
||||
Now, create new ACL policies using API:
|
||||
Now, create `admin` and `provisioner` policies:
|
||||
|
||||
```shell
|
||||
# Create dev-pol policy
|
||||
$ curl -X PUT -H "X-Vault-Token: $VAULT_TOKEN" -d @dev-payload.json \
|
||||
$VAULT_ADDR/v1/sys/policies/acl/dev-pol
|
||||
# Create admin policy
|
||||
$ curl --request PUT --header "X-Vault-Token: ..." --data @admin-payload.json \
|
||||
https://vault.rocks/v1/sys/policy/admin
|
||||
|
||||
$ cat dev-payload.json
|
||||
$ cat admin-payload.json
|
||||
{
|
||||
"policy": "path \"secret/apps/*\" { capabilities = [\"create\", \"read\", \"update\" ... }"
|
||||
"policy": "path \"auth/*\" { capabilities = [\"create\", \"read\", \"update\", ... }"
|
||||
}
|
||||
|
||||
# Create devops-pol policy
|
||||
$ curl -X PUT -H "X-Vault-Token: $VAULT_TOKEN" -d @devops-payload.json \
|
||||
$VAULT_ADDR/v1/sys/policies/acl/devops-pol
|
||||
# Create provisioner policy
|
||||
$ curl --request PUT --header "X-Vault-Token: ..." --data @provisioner-payload.json \
|
||||
https://vault.rocks/v1/sys/policy/provisioner
|
||||
|
||||
$ cat devops-payload.json
|
||||
$ cat provisioner-payload.json
|
||||
{
|
||||
"policy": "path \"sys/leases/*\" { capabilities = [\"create\", \"read\", \"update\" ... }"
|
||||
"policy": "path \"auth/*\" { capabilities = [\"create\", \"read\", \"update\", ... }"
|
||||
}
|
||||
```
|
||||
|
||||
**NOTE:** To update an existing policy, simply re-run the same command by
|
||||
passing your modified policy in the request payload (`*.json`).
|
||||
|
||||
|
||||
|
||||
### <a name="step2"></a>Step 2: View existing policies
|
||||
|
||||
Make sure that you see the policies you created in [Step 1](#step1).
|
||||
|
||||
#### CLI command
|
||||
|
||||
The following command lists existing policies:
|
||||
|
||||
```shell
|
||||
vault policies
|
||||
```
|
||||
|
||||
To view a specific policy:
|
||||
|
||||
```shell
|
||||
vault read sys/policy/<POLICY_NAME>
|
||||
```
|
||||
|
||||
**Example:**
|
||||
|
||||
```shell
|
||||
vault read sys/policy/default
|
||||
|
||||
Key Value
|
||||
--- -----
|
||||
name default
|
||||
rules # Allow tokens to look up their own properties
|
||||
path "auth/token/lookup-self" {
|
||||
capabilities = ["read"]
|
||||
}
|
||||
|
||||
# Allow tokens to renew themselves
|
||||
path "auth/token/renew-self" {
|
||||
capabilities = ["update"]
|
||||
}
|
||||
|
||||
# Allow tokens to revoke themselves
|
||||
path "auth/token/revoke-self" {
|
||||
capabilities = ["update"]
|
||||
}
|
||||
...
|
||||
```
|
||||
|
||||
|
||||
#### API call using cURL
|
||||
|
||||
To list existing ACL policies, use the `/sys/policy` endpoint.
|
||||
|
||||
```plaintext
|
||||
curl -X LIST -H "X-Vault-Token: $VAULT_TOKEN" $VAULT_ADDR/v1/sys/policy | jq
|
||||
```
|
||||
|
||||
-> NOTE: You can also use `/sys/policies` endpoint which is used to manage
|
||||
ACL, RGP, and EGP policies in Vault (RGP and EGP policies are enterprise-only
|
||||
features). To list policies, invoke `/sys/policies/acl` endpoint.
|
||||
|
||||
**NOTE:** To update an existing policy, simply re-run the same command by
|
||||
passing your modified policy in the request payload (`*.json`).
|
||||
|
||||
|
||||
|
||||
### <a name="step3"></a>Step 3: View existing policies
|
||||
|
||||
Make sure that you see the policies you created in [Step 2](#step2).
|
||||
|
||||
#### CLI command
|
||||
|
||||
The following command lists existing policies:
|
||||
|
||||
```shell
|
||||
$ vault policies
|
||||
```
|
||||
|
||||
To view a specific policy:
|
||||
|
||||
```shell
|
||||
$ vault read sys/policy/<POLICY_NAME>
|
||||
```
|
||||
|
||||
**Example:**
|
||||
|
||||
```shell
|
||||
# Read admin policy
|
||||
$ vault read sys/policy/admin
|
||||
Key Value
|
||||
--- -----
|
||||
name admin
|
||||
rules # Mount and manage auth backends broadly across Vault
|
||||
path "auth/*"
|
||||
{
|
||||
capabilities = ["create", "read", "update", "delete", "list", "sudo"]
|
||||
}
|
||||
|
||||
path "sys/auth/*"
|
||||
{
|
||||
capabilities = ["create", "read", "update", "delete", "sudo"]
|
||||
}
|
||||
|
||||
# Create and manage ACL policies broadly across Vault
|
||||
path "sys/policy/*"
|
||||
{
|
||||
capabilities = ["create", "read", "update", "delete", "list", "sudo"]
|
||||
}
|
||||
...
|
||||
```
|
||||
|
||||
#### API call using cURL
|
||||
|
||||
To list existing ACL policies, use the `/sys/policy` endpoint.
|
||||
|
||||
```shell
|
||||
$ curl --request LIST --header "X-Vault-Token: ..." https://vault.rocks/v1/sys/policy | jq
|
||||
```
|
||||
|
||||
To read a specific policy, the endpoint path should be
|
||||
`/sys/policy/<POLICY_NAME>`.
|
||||
|
||||
**Example:**
|
||||
|
||||
```plaintext
|
||||
curl -X GET -H "X-Vault-Token: $VAULT_TOKEN" $VAULT_ADDR/v1/sys/policy/default | jq
|
||||
Read the admin policy:
|
||||
|
||||
```plaintext
|
||||
$ curl --request GET --header "X-Vault-Token: ..." https://vault.rocks/v1/sys/policy/admin | jq
|
||||
{
|
||||
"name": "default",
|
||||
"rules": "\n# Allow tokens to look up their own properties\npath \"auth/token/lookup-self\" ...",
|
||||
"request_id": "1379d18d-e5e3-dbd2-8f3a-0e446c016a23",
|
||||
"name": "admin",
|
||||
"rules": "# Mount and manage auth backends broadly across Vault\npath \"auth/*\"\n{\n ...",
|
||||
"request_id": "e8151bf3-8136-fef9-428b-1506042350cf",
|
||||
"lease_id": "",
|
||||
"renewable": false,
|
||||
"lease_duration": 0,
|
||||
"data": {
|
||||
...
|
||||
```
|
||||
|
||||
|
||||
### <a name="step3"></a>Step 3: Check capabilities of a token
|
||||
### <a name="step4"></a>Step 4: Check capabilities of a token
|
||||
|
||||
Use the `/sys/capabilities` endpoint to fetch the capabilities of a token on a
|
||||
given path. This helps to verify what operations are granted based on the
|
||||
|
|
@ -310,22 +416,42 @@ policies attached to the token.
|
|||
The command is:
|
||||
|
||||
```shell
|
||||
vault capabilities <TOKEN> <PATH>
|
||||
$ vault capabilities <TOKEN> <PATH>
|
||||
```
|
||||
|
||||
**Example:**
|
||||
|
||||
```plaintext
|
||||
vault capabilities a59c0d41-8df7-ba8e-477e-9bfb394f28a0 secret/apps
|
||||
First, create a token attached to `admin` policy:
|
||||
|
||||
Capabilities: [create delete list read update]
|
||||
```shell
|
||||
$ vault token-create -policy="admin"
|
||||
Key Value
|
||||
--- -----
|
||||
token 79ecdd41-9bac-1ac7-1ee4-99fbce796221
|
||||
token_accessor 39b5e8b5-7bbf-6c6d-c536-ba79d3a80dd5
|
||||
token_duration 768h0m0s
|
||||
token_renewable true
|
||||
token_policies [admin default]
|
||||
```
|
||||
|
||||
Now, fetch the capabilities of this token on `sys/auth/approle` path.
|
||||
|
||||
```plaintext
|
||||
$ vault capabilities 79ecdd41-9bac-1ac7-1ee4-99fbce796221 sys/auth/approle
|
||||
Capabilities: [create delete read sudo update]
|
||||
```
|
||||
|
||||
The result should match the policy rule you wrote on `sys/auth/*` path. You can
|
||||
repeat the steps to generate a token for `provisioner` and check its
|
||||
capabilities on paths.
|
||||
|
||||
|
||||
In the absence of token, it returns capabilities of current token invoking this
|
||||
command.
|
||||
|
||||
```shell
|
||||
vault capabilities secret/apps
|
||||
$ vault capabilities sys/auth/approle
|
||||
Capabilities: [root]
|
||||
```
|
||||
|
||||
#### API call using cURL
|
||||
|
|
@ -334,27 +460,85 @@ Use the `sys/capabilities` endpoint.
|
|||
|
||||
**Example:**
|
||||
|
||||
```plaintext
|
||||
$ curl -X POST -H "X-Vault-Token: $VAULT_TOKEN" -d @payload.json \
|
||||
$VAULT_ADDR/v1/sys/capabilities
|
||||
First, create a token attached to `admin` policy:
|
||||
|
||||
$ cat payload.json
|
||||
```shell
|
||||
$ curl --request POST --header "X-Vault-Token: ..." --data '{ "policies":"admin" }' \
|
||||
https://vault.rocks/v1/auth/token/create
|
||||
{
|
||||
"token": "a59c0d41-8df7-ba8e-477e-9bfb394f28a0",
|
||||
"path": "secret/apps"
|
||||
"request_id": "870ef38c-1401-7beb-633c-ff09cca3db68",
|
||||
"lease_id": "",
|
||||
"renewable": false,
|
||||
"lease_duration": 0,
|
||||
"data": null,
|
||||
"wrap_info": null,
|
||||
"warnings": null,
|
||||
"auth": {
|
||||
"client_token": "9f3a9fbb-4e1a-87c3-9d4d-ee4d96d40af1",
|
||||
"accessor": "f8a269c0-153a-c1ea-ae97-e7e964814392",
|
||||
"policies": [
|
||||
"root"
|
||||
],
|
||||
"metadata": null,
|
||||
"lease_duration": 0,
|
||||
"renewable": false,
|
||||
"entity_id": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Now, fetch the capabilities of this token on `sys/auth/approle` path.
|
||||
|
||||
```shell
|
||||
# Request payload
|
||||
$ cat payload.json
|
||||
{
|
||||
"token": "9f3a9fbb-4e1a-87c3-9d4d-ee4d96d40af1",
|
||||
"path": "sys/auth/approle"
|
||||
}
|
||||
|
||||
$ curl --request POST --header "X-Vault-Token: ..." --data @payload.json \
|
||||
https://vault.rocks/v1/sys/capabilities
|
||||
{
|
||||
"capabilities": [
|
||||
"create",
|
||||
"delete",
|
||||
"read",
|
||||
"sudo",
|
||||
"update"
|
||||
],
|
||||
"request_id": "03f9d5e2-7e8a-4cd3-b9e9-034c058d3d06",
|
||||
"lease_id": "",
|
||||
"renewable": false,
|
||||
"lease_duration": 0,
|
||||
"data": {
|
||||
"capabilities": [
|
||||
"create",
|
||||
"delete",
|
||||
"read",
|
||||
"sudo",
|
||||
"update"
|
||||
]
|
||||
},
|
||||
"wrap_info": null,
|
||||
"warnings": null,
|
||||
"auth": null
|
||||
}
|
||||
```
|
||||
|
||||
The result should match the policy rule you wrote on `sys/auth/*` path. You can
|
||||
repeat the steps to generate a token for `provisioner` and check its
|
||||
capabilities on paths.
|
||||
|
||||
To check current token's capabilities permitted on a path, use
|
||||
`sys/capabilities-self` endpoint.
|
||||
|
||||
```plaintext
|
||||
curl -X POST -H "X-Vault-Token: $VAULT_TOKEN" -d '{"path":"secret/apps"}' \
|
||||
$VAULT_ADDR/v1/sys/capabilities-self
|
||||
$ curl --request POST --header "X-Vault-Token: ..." --data '{"path":"sys/auth/approle"}' \
|
||||
https://vault.rocks/v1/sys/capabilities-self
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Next steps
|
||||
|
||||
In this guide, you learned how to write policies based on given policy
|
||||
|
|
|
|||
Loading…
Reference in a new issue