From 1980dceb73c45f1d622e93c8c1d82d7ba5a3ab8c Mon Sep 17 00:00:00 2001
From: hygienic-books <hygienic-books@tentic.net>
Date: Sat, 5 Oct 2024 23:17:24 +0200
Subject: [PATCH 1/2] fix(docs): Correctly explain periodic tokens (#5)
---
.gitignore | 1 +
README.md | 12 ++++++------
2 files changed, 7 insertions(+), 6 deletions(-)
create mode 100644 .gitignore
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..723ef36
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+.idea
\ No newline at end of file
diff --git a/README.md b/README.md
index e87a04b..ba7b168 100644
--- a/README.md
+++ b/README.md
@@ -189,15 +189,15 @@ https://f.q.d.n/ui/vault/secrets/kv/list/for_rbacgroup_zabbix
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
+### Periodic 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.
+As an alternative to the Zabbix example above you may want a token you can renew indefinitely which implies that it 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.
+A token created with a `period` on the other hand - 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:
+For services that cannot handle renewal natively you will want both at the same time: a periodic orphan token. 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
@@ -214,11 +214,11 @@ Log in to Vault with `userpass` and an account that has `write` access to `auth/
```
curl --silent --location --header 'X-Vault-Token: <token>' \
--request POST \
- --data '{"policies":["remco"],"renewable":true,"ttl":"768h","display_name":"remco populates config files with secrets"}' \
+ --data '{"policies":["remco"],"period":"768h","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.
+Note that we do not specify `"renewable":true` as periodic tokens are implicitly renewable. We also don't specify `"ttl":"768h"` or similar values as the period in our periodic token will override a time-to-live value anyway rendering the time-to-live irrelevant. We can get our desired token by simply specifying for example `"period":"768h"`.
Write down the generated `client_token`.
--
2.47.2
From 8d3ff2683a3164f6707f5cd273a94954f4696865 Mon Sep 17 00:00:00 2001
From: hygienic-books <hygienic-books@tentic.net>
Date: Sat, 5 Oct 2024 23:20:52 +0200
Subject: [PATCH 2/2] feat(docs): Explain token renewal (#5)
---
README.md | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/README.md b/README.md
index ba7b168..eabed5f 100644
--- a/README.md
+++ b/README.md
@@ -222,6 +222,15 @@ Note that we do not specify `"renewable":true` as periodic tokens are implicitly
Write down the generated `client_token`.
+Token renewal works like so via the `/auth/token/renew-self` endpoint:
+
+```
+curl --silent --location --header 'X-Vault-Token: <token>' \
+ --request POST \
+ --data '{"token":"<token>"}' \
+ 'https://f.q.d.n/v1/auth/token/renew-self'
+```
+
Lastly don't forget to create some key value pairs underneath `kv/for_rbacgroup_remco` that the token can access.
#### Token lifecycle management
--
2.47.2