feat(docs): Explain setup for and creation of orphan tokens (#3)

README.md

@@ -189,6 +189,41 @@ 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
+
+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.
+
 ## Clean-up
 
 If during any of the above steps you've used the Vault command-line client to authenticate against Vault with your `root` token make sure that client's `~/.vault-token` file is deleted. It contains the verbatim `root` token.