Quico/vault-config
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request '3-add-example-for-periodic-orphan-token' (#4) from 3-add-example-for-periodic-orphan-token into master

Browse Source 
Reviewed-on: #4
This commit is contained in:
hygienic-books 2023-04-25 00:23:44 +00:00
commit 9f067d6fec
2 changed files with 203 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

295
README.md
View File

@ -32,144 +32,231 @@ Log out. Never again use the `root` token unless there's a good reason.
Get the Vault command-line client via [vaultproject.io/downloads](https://www.vaultproject.io/downloads). It'll install the Vault service itself along with the command-line client. Just ignore the service or keep it disabled via `systemctl disable --now vault.service`. You only need the `vault` binary.
* Authenticate against Vault:
```
export VAULT_ADDR='https://fully.qualified.domain.name/'
vault login
### Authenticate against Vault:
```
export VAULT_ADDR='https://fully.qualified.domain.name/'
vault login
# Which will prompt for:
Token (will be hidden):
```
Enter your personal alias' token, do not ever again use the `root` token.
# Which will prompt for:
Token (will be hidden):
```
Enter your personal alias' token, do not ever again use the `root` token.
* Enable audit file device (in non-Vault-speak "the audit log file"):
### Auditing
Enable audit file device (in non-Vault-speak "the audit log file"):
```
# Enable
vault audit enable file file_path=/vault/logs/audit.log
# Expected output:
Success! Enabled the file audit device at: file/
```
Confirm:
```
# Confirm
vault audit list
# Expected output
Path Type Description
---- ---- -----------
file/ file n/a
```
### Humans may change their own password
We're going to allow all human users to change their own `userpass` password. The policy to do so is at [policies/human/change-own-password.hcl](policies/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:
```
# Enable
vault audit enable file file_path=/vault/logs/audit.log
# 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/human/change-own-password.hcl](policies/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! Enabled the file audit device at: file/
Success! Data written to: identity/group/name/humans
```
Confirm:
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:
```
# Confirm
vault audit list
# Create group
vault write identity/group name="humans" policies="change-own-password" member_entity_ids="<uuid>,<uuid>,<uuid>"
# Expected output
Path Type Description
---- ---- -----------
file/ file n/a
# Expected output:
Success! Data written to: identity/group/name/humans
```
* We're going to allow all human users to change their own `userpass` password. The policy to do so is at [policies/human/change-own-password.hcl](policies/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:
Entity IDs are coming from `vault list identity/entity/id` and/or `vault read identity/entity/name/<name>`.
* 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
### Ready-only secrets access
# 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/human/change-own-password.hcl](policies/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.
Optionally [policies/cfgmgmt/cfgmgmt.hcl](policies/cfgmgmt/cfgmgmt.hcl) gets you started with read-only secrets access for example for a config management tool like Ansible.
* 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"
You'll want to create an Ansible entity and a `userpass` alias. Think of the alias as glue that ties an auth method to an entity. This in turn allows you to specify policy that applies to the entity, gets inherited by aliases and lastly inherited by auth methods.
# 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>"
In this simple use case create create a user in the `userpass` auth method, use the same name used from both the entity and its alias. Use that user to authenticate against Vault and retrieve a token. You'll likely want a distinct group where your Ansible entity becomes a member and which uses a policy such as the example at [policies/cfgmgmt/cfgmgmt.hcl](policies/cfgmgmt/cfgmgmt.hcl).
# 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>`.
From here on out it's just more of what you already did, feel free to make this fit your own approach.
* Optionally [policies/cfgmgmt/cfgmgmt.hcl](policies/cfgmgmt/cfgmgmt.hcl) gets you started with read-only secrets access for example for a config management tool like Ansible.
### Write-only access
You'll want to create an Ansible entity and a `userpass` alias. Think of the alias as glue that ties an auth method to an entity. This in turn allows you to specify policy that applies to the entity, gets inherited by aliases and lastly inherited by auth methods.
Optionally from [policies/kv-writer/kv-writer.hcl](policies/kv-writer/kv-writer.hcl) load a policy that allows affected entities to create `kv` secrets, create new versions for existing secrets and to traverse the UI directory structure of secrets. Entities with this policy will not be able to read secrets nor see if versions exist at a given location.
In this simple use case create create a user in the `userpass` auth method, use the same name used from both the entity and its alias. Use that user to authenticate against Vault and retrieve a token. You'll likely want a distinct group where your Ansible entity becomes a member and which uses a policy such as the example at [policies/cfgmgmt/cfgmgmt.hcl](policies/cfgmgmt/cfgmgmt.hcl).
Permission to also read/view secrets is commented out in the policy file in case you do need this feature.
From here on out it's just more of what you already did, feel free to make this fit your own approach.
Assign the policy to a group as needed.
* Optionally from [policies/kv-writer/kv-writer.hcl](policies/kv-writer/kv-writer.hcl) load a policy that allows affected entities to create `kv` secrets, create new versions for existing secrets and to traverse the UI directory structure of secrets. Entities with this policy will not be able to read secrets nor see if versions exist at a given location.
### Zabbix credentials storage
Permission to also read/view secrets is commented out in the policy file in case you do need this feature.
As a similar narrowly scoped use case consider a Zabbix monitoring instance that may need access to credentials, session IDs, tokens or other forms of authentication to monitor machines and services.
Assign the policy to a group as needed.
Here's one suggestion to set up the basics for Zabbix.
* As a similar narrowly scoped use case consider a Zabbix monitoring instance that may need access to credentials, session IDs, tokens or other forms of authentication to monitor machines and services.
In Vault with a user that has sufficient permissions:
* Create an entity `zabbix` without a policy.
* Add an alias of type `userpass` to the entity.
* Within the `userpass` auth method create a user (an account if you will) with the same name as the alias you just created so in this case `zabbix`, set a password for the account
Here's one suggestion to set up the basics for Zabbix.
Now tie it all together by creating a group named `rbacgroup_zabbix`. Add the `zabbix` entity to it and make it use the policy `zabbix`. At this point the policy does not yet exist which is fine, you can set a policy name and Vault will simply link your group to the policy `zabbix` which does not exist. You'll get to that in a minute.
In Vault with a user that has sufficient permissions:
* Create an entity `zabbix` without a policy.
* Add an alias of type `userpass` to the entity.
* Within the `userpass` auth method create a user (an account if you will) with the same name as the alias you just created so in this case `zabbix`, set a password for the account
Like so:
Now tie it all together by creating a group named `rbacgroup_zabbix`. Add the `zabbix` entity to it and make it use the policy `zabbix`. At this point the policy does not yet exist which is fine, you can set a policy name and Vault will offer to `Add new policy`, see screenshot below. Don't worry, this will not actually add a new policy - empty, broken or otherwise. Vault will simply link your group to the policy `zabbix` which does not exist. You'll get to that in a minute.
![Vault 1.12.0 Create Group menu](https://i.imgur.com/mTbyZjk.png)
Like so:
![Vault 1.11.3 Create Group menu](https://i.imgur.com/3Ni53BE.png)
#### Group ID replacement
Next up check out [policies/zabbix/zabbix.hcl](policies/zabbix/zabbix.hcl). Do some light replacement before importing it into Vault. The policy file contains a few occurrences of the string `GROUPID`, replace them with the group ID of `rbacgroup_zabbix`.
* Via Vault's UI you can get the group ID at `Access > Groups > rbacgroup_zabbix`.
* Via the `vault` command-line client you can do it like so where the `id` value is what you're after:
```
# Get 'rbacgroup_zabbix' group metadata
vault kv get /identity/group/name/rbacgroup_zabbix
# Expected output similar to:
== Metadata ==
========== Data ==========
Key Value
--- -----
alias map[]
creation_time 2022-09-22T21:47:57.720309362Z
id 88560da7-e180-3d2e-9053-dc0ee4ba7fbe
...
```
With your ID in hand and [policies/zabbix/zabbix.hcl](policies/zabbix/zabbix.hcl) updated import it as a new policy. You're going to want to save it with the same policy name you assigned earlier to `rbacgroup_zabbix` which was `zabbix`. This role will grant read-only access to secrets underneath a folder `for_rbacgroup_zabbix` which in our example lives inside a `kv` version 2 secrets engine mounted at its default location `kv`.
Now whenever your Zabbix instance needs access to something store secrets underneath `kv/for_rbacgroup_zabbix`. The policy will make sure only the group with correct ID will have access to secrets underneath that directory.
Log in to Vault with `userpass` and the `zabbix` account from above, get the account's token and lastly double-check that `zabbix` with its token can read a secret:
```
curl --silent --location --header 'X-Vault-Token: <token>' \
'https://f.q.d.n/v1/kv/data/for_rbacgroup_zabbix/some/secret' \
| jq '.data.data'
Next up check out [policies/zabbix/zabbix.hcl](policies/zabbix/zabbix.hcl). Do some light replacement before importing it into Vault. The policy file contains a few occurrences of the string `GROUPID`, replace them with the group ID of `rbacgroup_zabbix`.
* Via Vault's UI you can get the group ID at `Access > Groups > rbacgroup_zabbix`.
* Via the `vault` command-line client you can do it like so where the `id` value is what you're after:
```
# Get 'rbacgroup_zabbix' group metadata
vault kv get /identity/group/name/rbacgroup_zabbix
Configure Zabbix with its own Vault token and enjoy no longer having to store any secrets in Zabbix itself.
# Expected output similar to:
== Metadata ==
Side note, if your token regularly expires you may want to store the token itself in Vault and let Zabbix monitor token expiry via the Zabbix equivalent of:
========== Data ==========
Key Value
--- -----
alias map[]
creation_time 2022-09-22T21:47:57.720309362Z
id 88560da7-e180-3d2e-9053-dc0ee4ba7fbe
...
```
# Look up a token's own attributes
curl --silent --location --header 'X-Vault-Token: <token>' \
'https://f.q.d.n/v1/auth/token/lookup-self' \
| jq '.data.ttl'
With your ID in hand and [policies/zabbix/zabbix.hcl](policies/zabbix/zabbix.hcl) updated import it as a new policy. You're going to want to save it with the same policy name you assigned earlier to `rbacgroup_zabbix` which was `zabbix`. This role will grant read-only access to secrets underneath a folder `for_rbacgroup_zabbix` which in our example lives inside a `kv` version 2 secrets engine mounted at its default location `kv`.
# .data.ttl will show remaining validity in secs:
2754536
```
Now whenever your Zabbix instance needs access to something store secrets underneath `kv/for_rbacgroup_zabbix`. The policy will make sure only the group with correct ID will have access to secrets underneath that directory.
Users wishing to browse the `rbacgroup_zabbix` directory structure via Vault's UI will need to manually begin their browsing at `kv/list/for_rbacgroup_zabbix`. Users with higher privileges such as administrators will be able to list all directories underneath the root `kv` object in Vault's web UI. This will include not only `zabbix`-specific data but also directories intended for other users which is why `kv/list` access is not granted to `rbacgroup_zabbix`.
Log in to Vault with `userpass` and the `zabbix` account from above, get the account's token and lastly double-check that `zabbix` with its token can read a secret:
```
curl --silent --location --header 'X-Vault-Token: <token>' \
'https://f.q.d.n/v1/kv/data/for_rbacgroup_zabbix/some/secret' \
| jq '.data.data'
```
Their `list` permission only begins one lever deeper at `kv/list/for_rbacgroup_zabbix`. It may make sense to communicate an entrypoint link to end users that - in this case - will look like:
```
https://f.q.d.n/ui/vault/secrets/kv/list/for_rbacgroup_zabbix
```
Configure Zabbix with its own Vault token and enjoy no longer having to store any secrets in Zabbix itself.
Side note, if your token regularly expires you may want to store the token itself in Vault and let Zabbix monitor token expiry via the Zabbix equivalent of:
```
# Look up a token's own attributes
curl --silent --location --header 'X-Vault-Token: <token>' \
'https://f.q.d.n/v1/auth/token/lookup-self' \
| jq '.data.ttl'
# .data.ttl will show remaining validity in secs:
2754536
```
Users wishing to browse the `rbacgroup_zabbix` directory structure via Vault's UI will need to manually begin their browsing at `kv/list/for_rbacgroup_zabbix`. Users with higher privileges such as administrators will be able to list all directories underneath the root `kv` object in Vault's web UI. This will include not only `zabbix`-specific data but also directories intended for other users which is why `kv/list` access is not granted to `rbacgroup_zabbix`.
Their `list` permission only begins one lever deeper at `kv/list/for_rbacgroup_zabbix`. It may make sense to communicate an entrypoint link to end users that - in this case - will look like:
```
https://f.q.d.n/ui/vault/secrets/kv/list/for_rbacgroup_zabbix
```
### Permission to create orphan tokens
The next example will explain orphan tokens. If you've followed examples above your Vault instance will have an `administrators` group with an `administrator` policy assigned to it. Users in that group will already have `write` access to `auth/token/create-orphan` so you can just use one of your `administrators` entities to follow along.
### Periodic and orphan tokens
As an alternative to the Zabbix example above you may want a token that auto-renews itself as long as it gets regularly used and that can outlive its parent entity.
By default a token is associated with the entity that created it, as a consequence a token cannot outlive the maximum time to live configured for its parent entity. In order to decouple a token from its parent entity and for a token to live longer than its parent entity you can make it an _orphan_ token.
A token created with a `period` - a time value indicating its maximum time to live - is considered a _periodic_ token. Unless a token is also orphaned its time to live still remains limited to that of its parent entity.
The first few prep steps will sound familiar from the Zabbix paragraph above. For example's sake let's assume we want the `remco` file generator (see [github.com/HeavyHorst/remco](https://github.com/HeavyHorst/remco)) to have Vault access:
* Create an entity `remco` without a policy
* Add an alias of type `userpass` also named `remco` to the entity
* Within the `userpass` auth method create a user (an account if you will) with the same name as the alias you just created so in this case `remco`, set a password for the account
Create a group named `rbacgroup_remco`. Add the `remco` entity to it and make it use the policy `remco`. At this point the policy does not yet exist which is fine, you can set a policy name and Vault will simply link your group to the policy `remco` which does not exist. You'll get to that in a minute.
Next up we'll be working with [policies/remco/remco.hcl](policies/remco/remco.hcl). In that file replace `GROUPID` with the actual group ID of `rbacgroup_remco`, refer to paragraph [Group ID replacement](#group-id-replacement) for a how-to guide. Continue reading there until you reach the point talking about logging in to Vault as the newly created user then return here.
For our `remco` example application we want a periodic orphan token.
Log in to Vault with `userpass` and an account that has `write` access to `auth/token/create-orphan`, for example an administrator as detailed in [Permission to create orphan tokens](#permission-to-create-orphan-tokens) above. Get the account's token. Send the following API command to create a periodic orphan token:
```
curl --silent --location --header 'X-Vault-Token: <token>' \
--request POST \
--data '{"ttl":"768h","renewable":true,"display_name":"remco populates config files with secrets"}' \
'https://f.q.d.n/v1/auth/token/create-orphan'
```
We're choosing our `ttl` of 768 hours on purpose. This equals 32 days which is the default server setting in `max_lease_ttl` that any token created by a non-`root` user can have. Feel free to reconfigure this server-side on your end and to pick a longer `ttl` value as needed. For our use case 32 days is plenty of time.
Write down the generated `client_token`.
Lastly don't forget to create some key value pairs underneath `kv/rbacgroup_remco` that the token can access.
#### Token lifecycle management
Revoke an orphan token like so via Vault CLI client. See [Authenticate against Vault](#authenticate-against-vault) at the top for how to authenticate your Vault CLI client and then:
```
vault token revoke -accessor <token-accessor-here>.
```
Find all orphan tokens by their accessor like so. This requires `list` access to `auth/token/accessors`. Members of the `administrators` group outlined above have this.
```
vault list -format json auth/token/accessors |\
jq -r .[] |\
xargs -I '{}' vault token lookup -format json -accessor '{}' |\
jq -r 'select((.data.entity_id=="") and (.data.orphan==true) and (.data.path=="auth/token/create-orphan"))'
```
Output will for example look like:
```
{
"request_id": "170d8a93-7b61-9ec2-9df7-ad7a8ca0be88",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"accessor": "66IzIsoOpXycYqF33JmfIb8G",
...
"entity_id": "",
...
},
"warnings": null
}
```
Where the `accessor` ID (here `66IzIsoOpXycYqF33JmfIb8G`) is what you're going to want to use in your CLI command `vault token revoke`.
## Clean-up

12
policies/remco/remco.hcl Normal file
View File

@ -0,0 +1,12 @@
# Allow listing secret parent-child connections (as in UI hierarchy). Subdir
# underneath 'kv' secrets engine will remain hidden though, user has to
# manually open up
# ${VAULT_ADDR}/ui/vault/secrets/kv/list/for_{{identity.groups.ids.GROUPID.name}}
path "kv/metadata/for_{{identity.groups.ids.GROUPID.name}}/*" {
capabilities = ["list"]
}
# Grant read-only access to secrets
path "kv/data/for_{{identity.groups.ids.GROUPID.name}}/*" {
capabilities = ["read"]
}