diff --git a/docs/Identity.md b/docs/Identity.md new file mode 100644 index 0000000..a709c6f --- /dev/null +++ b/docs/Identity.md @@ -0,0 +1,98 @@ +# Identity and Authentication + +## Token Authentication + +Setup `VAULT_ADDR` and `VAULT_TOKEN` environment variables to authenticate with Vault using a token. + +Store the root token in 1Password and retrieve it when needed using CLI commands. + +```bash +export OP_VAULT_TOKEN="op://Private/root Vault Koszewscy/password" +export VAULT_ADDR="https://vault.koszewscy.waw.pl" VAULT_TOKEN="${OP_VAULT_TOKEN}" +``` + +Then, run the vault using: + +```bash +op run -- vault login $VAULT_TOKEN +``` + +1Password CLI will fetch the token from the specified path in your 1Password vault and replace the secret reference with the actual token value when executing the command. However, that method adds a delay due to the `op run` command. + +Alternatively, you can directly set the `VAULT_TOKEN` environment variable by reading the token from 1Password: + +```bash +export VAULT_TOKEN=$(op read "op://Private/root Vault Koszewscy/password") +``` + +With VAULT_TOKEN set, `vault` authenticates directly. + +## Userpass Authentication Method + +### Login with Userpass + +Userpass authentication allows users to log in with a username and password. + +```bash +vault login -method=userpass username="your-username" +``` + +The token is stored in a file located at `~/.vault-token` by default. Although, the token file is secured with file permissions, it contains a plaintext token. Change the token time-to-live (TTL) to limit its validity period. + +```bash +vault write auth/userpass/users/your-username max_token_ttl="12h" token_ttl="1h" +``` + +Limit the token's usage to known IP addresses for added security. + +```bash +vault write auth/userpass/users/your-username token_bound_cidrs="192.168.2.0/24" +``` + +You can also set VAULT_TOKEN with the following command: + +```bash +export VAULT_TOKEN=$(vault login -token-only -method=userpass username="your-username") +``` + +> **Note:** The `-token-only` is an equivalent of `-field=token -no-store` options. + +You can also use the following command to set VAULT_TOKEN and TOKEN_ACCESSOR: + +```bash +export $(vault token lookup -format=json | jq -r '.data | "TOKEN_ACCESSOR=\(.accessor) VAULT_TOKEN=\(.id)"') +``` + +You can then use the `TOKEN_ACCESSOR` to look up token details without exposing the actual token. + +```bash +vault token lookup -accessor $TOKEN_ACCESSOR +``` + +Use the `vault token renew` command to renew the token before it expires. + +```bash +vault token renew +``` + +### User Management + +List all users: + +```bash +vault list auth/userpass/users +``` + +Create a new user: + +```bash +vault write auth/userpass/users/new-username password="new-password" policies="default" +``` + +> **Note:** key="value" pairs may contain scalars or lists (comma-separated values). + +Read user details: + +```bash +vault read auth/userpass/users/username +```