diff --git a/website/source/assets/images/vault-approle-workflow.png b/website/source/assets/images/vault-approle-workflow.png index 5f377455c..f21e0535f 100644 --- a/website/source/assets/images/vault-approle-workflow.png +++ b/website/source/assets/images/vault-approle-workflow.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:278d15ee12965e203b68245ffa9ffb1ab65ac52f7d5629e9882ccf9e7545accb -size 59048 +oid sha256:60730388cbc37128b32d2bc997181446466f6591de28eb12f04f12de0bce470d +size 49660 diff --git a/website/source/guides/cubbyhole.html.md b/website/source/guides/cubbyhole.html.md index 6825dc012..c1eb4c342 100644 --- a/website/source/guides/cubbyhole.html.md +++ b/website/source/guides/cubbyhole.html.md @@ -30,6 +30,13 @@ long as its policy allows it. 10 minutes +## Personas + +The end-to-end scenario described in this guide involves two personas: + +- **`admin`** with privileged permissions to create tokens and policies +- **`app`** is the receiving client of a wrapped response + ## Challenge In order to tightly manage the secrets, you set the scope of who can do what @@ -50,39 +57,95 @@ like any other tokens so that the risk of unauthorized access can be minimized. 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). +### Policy requirements + +To perform all tasks demonstrated in this guide, you need to be able to +authenticate with Vault as an [**`admin`** user](#personas). + +-> **NOTE:** For the purpose of this guide, you can use **`root`** token to work +with Vault. However, it is recommended that root tokens are only used for just +enough initial setup or in emergencies. As a best practice, use tokens with +appropriate set of policies based on your role in the organization. + +The `admin` policy must include the following permissions: + +```shell +# Manage tokens +path "sys/auth/token/*" { + capabilities = [ "create", "read", "update", "delete" ] +} + +# Write ACL policies +path "sys/policy/*" { + capabilities = [ "create", "read", "update", "delete", "list" ] +} + +# Access cubbyhole backend +path "cubbyhole/private/*" { + capabilities = ["create", "read", "update", "delete", "list"] +} +``` ## Steps To distribute the initial token to an app using cubbyhole response wrapping, you perform the following tasks: -1. Create and wrap a token -2. Unwrap the secret +1. [Create and wrap a token](#step1) +2. [Unwrap the secret](#step2) -### Step 1: Create and wrap a token +### Step 1: Create and wrap a token +(**Persona:** admin) When the response to `vault token-create` request is wrapped, Vault inserts the generated token it into the cubbyhole of a single-use token, returning that single-use wrapping token. Retrieving the secret requires an unwrap operation against this wrapping token. -#### CLI command +In this scenario, an [admin user](#personas) creates a token using response wrapping. To perform the steps in this guide, first create a policy for the app. + +`app-policy.hcl`: ```shell -vault token-create -policy= -wrap-ttl= +# Unwrap the token +path "sys/wrapping/unwrap" { + capabilities = [ "create", "read" ] +} + +# For testing, read-only on secret/dev path +path "secret/dev" { + capabilities = [ "read" ] +} +``` + +#### CLI command + +First create an `apps` policy: + +```shell +$ vault policy-write apps apps-policy.hcl +Policy 'apps' written. +``` + +To create a token using response wrapping: + +```shell +$ vault token-create -policy= -wrap-ttl= ``` Where the `` is a numeric string indicating the TTL of the response. **Example:** +Generate a token for `app` persona using response wrapping with TTL of 60 +seconds. + ```shell -vault token-create -policy=app-policy -wrap-ttl=60s +$ vault token-create -policy=apps -wrap-ttl=60s Key Value --- ----- @@ -93,19 +156,22 @@ wrapping_token_creation_path: auth/token/create wrapped_accessor: 195763a9-3f26-1fcf-6a1a-ee0a11e76cb1 ``` +The response is the wrapping token; therefore, the admin user does not even see +the generated token from the `token-create` command. + #### API call using cURL -Before begin, create the following environment variables for your convenience: +First create an `apps` policy: -- **VAULT_ADDR** is set to your Vault server address -- **VAULT_TOKEN** is set to your Vault token +```shell +$ curl --header "X-Vault-Token: ..." --request PUT \ + --data @payload.json \ + https://vault.rocks/v1/sys/policy/apps -**Example:** - -```plaintext -$ export VAULT_ADDR=http://127.0.0.1:8201 - -$ export VAULT_TOKEN=0c4d13ba-9f5b-475e-faf2-8f39b28263a5 +$ cat payload.json +{ + "policy": "path \"sys/wrapping/unwrap\" { capabilities = [ \"create\", \"read\" ] ... }" +} ``` Response wrapping is per-request and is triggered by providing to Vault the @@ -113,12 +179,27 @@ desired TTL for a response-wrapping token for that request. This is set using the **`X-Vault-Wrap-TTL`** header in the request and can be either an integer number of seconds or a string duration. +```shell +$ curl --header "X-Vault-Wrap-TTL: " \ + --header "X-Vault-Token: " \ + --request \ + --data '' \ + /v1/ +``` + +Where `` can be either an integer number of seconds or a string duration of +seconds (15s), minutes (20m), or hours (25h). + **Example:** -```text -curl -X POST -H "X-Vault-Token: $VAULT_TOKEN" -H "X-Vault-Wrap-TTL: 60s" \ - -d '{"policies":["app-policy"]}' $VAULT_ADDR/v1/auth/token/create | jq +To wrap the response of token-create request: +```shell +$ curl --header "X-Vault-Wrap-TTL: 60s" \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data '{"policies":["apps"]}' \ + https://vault.rocks/v1/auth/token/create | jq { "request_id": "", "lease_id": "", @@ -137,25 +218,32 @@ curl -X POST -H "X-Vault-Token: $VAULT_TOKEN" -H "X-Vault-Wrap-TTL: 60s" \ } ``` -### Step 2: Unwrap the secret +Generate a token for `app` persona using response wrapping with TTL of 60 +seconds. The admin user does not even see the generated token. -The client uses the wrapping token to unwrap the secret. -**NOTE:** -If a client has been expecting delivery of a response-wrapping token and none -arrives, this may be due to an attacker intercepting the token and then -preventing it from traveling further. This should cause an alert to trigger an -immediate investigation. +### Step 2: Unwrap the secret +(**Persona:** app) + +The response is wrapped by a wrapping token, and retrieving it requires an +unwrap operation against this token. + +-> **NOTE:** If a client has been expecting delivery of a response-wrapping +token and none arrives, this may be due to an attacker intercepting the token +and then preventing it from traveling further. This should cause an alert to +trigger an immediate investigation. #### CLI command -```text -vault unwrap +To unwrap the secret: + +```shell +$ vault unwrap ``` Or -```text -VAULT_TOKEN= vault unwrap +```shell +$ VAULT_TOKEN= vault unwrap ``` In this scenario, the wrapped secret is a Vault token. Therefore, it probably @@ -172,16 +260,34 @@ token 7bb915b2-8a44-48b0-a71d-72b590252016 token_accessor 195763a9-3f26-1fcf-6a1a-ee0a11e76cb1 token_duration 768h0m0s token_renewable true -token_policies [app-policy default] +token_policies [apps default] +``` + +Once the client acquired the token, future requests can be made using this +token. + +```shell +$ vault auth 7bb915b2-8a44-48b0-a71d-72b590252016 + +$ vault read secret/dev ``` #### API call using cURL -To enable the AppRole auth backend via API: +To unwrap the secret, use `/sys/wrapping/unwrap` endpoint: -```text -curl -X POST -H "X-Vault-Token: $WRAPPING_TOKEN" $VAULT_ADDR/v1/sys/wrapping/unwrap | jq +```shell +$ curl --header "X-Vault-Token: " \ + --request POST \ + /v1/sys/wrapping/unwrap +``` +**Example:** + +```shell +$ curl --header "X-Vault-Token: e095129f-123a-4fef-c007-1f6a487cfa78" \ + --request POST \ + https://vault.rocks/v1/sys/wrapping/unwrap | jq { "request_id": "d704435d-c1cf-b8a3-52f6-ec50bc8246c4", "lease_id": "", @@ -194,7 +300,7 @@ curl -X POST -H "X-Vault-Token: $WRAPPING_TOKEN" $VAULT_ADDR/v1/sys/wrapping/unw "client_token": "af5f7682-aa55-fa37-5039-ee116df56600", "accessor": "19b5407e-b304-7cde-e946-54942325d3c1", "policies": [ - "app-policy", + "apps", "default" ], "metadata": null, @@ -204,6 +310,17 @@ curl -X POST -H "X-Vault-Token: $WRAPPING_TOKEN" $VAULT_ADDR/v1/sys/wrapping/unw } ``` +Once the client acquired the token, future requests can be made using this +token. + +```plaintext +$ curl --header "X-Vault-Token: af5f7682-aa55-fa37-5039-ee116df56600" \ + --request GET \ + https://vault.rocks/v1/secret/dev | jq +{ + "errors": [] +} +``` ## Additional Discussion @@ -215,7 +332,7 @@ To test the cubbyhole secret backend, perform the following steps. First, create `tester` policy which grants permissions on the path under `cubbyhole/private/` prefix. -```text +```shell $ vault policy-write tester tester.hcl $ cat tester.hcl @@ -227,7 +344,7 @@ path "cubbyhole/private/*" { Create a token attached to the `tester` policy, and then authenticate using the token. -```text +```shell $ vault token-create -policy=tester Key Value --- ----- @@ -249,7 +366,7 @@ token_policies: [default tester] You should be able to write secrets under `cubbyhole/private/` path, and read it back. -```text +```shell $ vault write cubbyhole/private/access-token token="123456789abcdefg87654321" Success! Data written to: cubbyhole/private/access-token @@ -262,8 +379,8 @@ token 123456789abcdefg87654321 Now, try to access the secret using the root token, you shouldn't be able to read. -```text -VAULT_TOKEN= vault read cubbyhole/private/access-token +```shell +$ VAULT_TOKEN= vault read cubbyhole/private/access-token No value found at cubbyhole/private/access-token ``` diff --git a/website/source/guides/lease.html.md b/website/source/guides/lease.html.md index 875b9d819..ec11cdad7 100644 --- a/website/source/guides/lease.html.md +++ b/website/source/guides/lease.html.md @@ -57,25 +57,24 @@ renewal and revocation Consider the following scenarios: - Currently, there is no **break glass** procedure available -- Credentials for externals systems (e.g. AWS, MySQL) are shared +- Credentials for external systems (e.g. AWS, MySQL) are shared - Need a temporal access to database in a specific scenario ## Solution Vault has built-in support for secret revocation. Vault can revoke not only single secret, but also a tree of secrets. For example, Vault can revoke all -secrets read by a specific user or all secrets of a specific type. Revocation -assists in key rolling as well as locking down systems in the case of an -intrusion. This also allows for organizations to plan and train for various +secrets read by a specific **user** or all secrets of a specific **type**. +Revocation assists in key rolling as well as locking down systems in the case of +an intrusion. This also allows for organizations to plan and train for various "break glass" procedures. ## Prerequisites 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). ## Steps @@ -100,7 +99,7 @@ When you create leases with no specific TTL values, the default value applies to the lease. ```shell -vault auth -methods +$ vault auth -methods Path Type Accessor Default TTL Max TTL Replication Behavior Description approle/ approle auth_approle_53f0fb08 system system replicated @@ -115,15 +114,17 @@ shorter in Vault's configuration file. Another option is to tune the mount configuration to override the system defaults by calling the **`/sys/mounts//tune`** endpoint (e.g. `/sys/mounts/database/tune`). For the auth backend system configuration, call -**`/sys/auth//tune`** endpoint. See the [Reference Content](#reference) -for more detail. +**`/sys/auth//tune`** endpoint. + +NOTE: Refer to the [Advanced Features](#advanced-features) section for tuning +the backend system configuration. #### CLI command Read the default TTL settings for **token** auth backend: ```shell -vault read sys/auth/token/tune +$ vault read sys/auth/token/tune Key Value --- ----- @@ -134,23 +135,23 @@ max_lease_ttl 2764800 #### API call using cURL -Before begin, create the following environment variables for your convenience: +Use `/sys/mounts` endpoint to read the default TTL settings for **token** auth +backend: -- **VAULT_ADDR** is set to your Vault server address -- **VAULT_TOKEN** is set to your Vault token +```shell +$ curl --header "X-Vault-Token: " \ + --request GET \ + /v1/sys/auth/token/tune +``` + +Where `` is your valid token with read permission on the +`sys/auth/token/tune` path. **Example:** -```plaintext -$ export VAULT_ADDR=http://127.0.0.1:8201 - -$ export VAULT_TOKEN=0c4d13ba-9f5b-475e-faf2-8f39b28263a5 -``` - -Read the default TTL settings for **token** auth backend: - -```plaintext -$ curl -X GET -H "X-Vault-Token: $VAULT_TOKEN" $VAULT_ADDR/v1/sys/auth/token/tune | jq +```shell +$ curl --header "X-Vault-Token: ..." --request GET \ + https://vault.rocks/v1/sys/auth/token/tune | jq { "default_lease_ttl": 2764800, "max_lease_ttl": 2764800, @@ -179,15 +180,17 @@ Create a new token with TTL of 30 seconds. #### CLI command ```shell +# Create a token with TTL of 30 seconds $ vault token-create -ttl=30s Key Value --- ----- -token 7544266f-3ec9-81a6-d504-e258b89de862 +token 7544266f-3ec9-81a6--data504-e258b89de862 token_accessor 59aae2f1-2e97-6ebb-f925-8a97cf5a9942 token_duration 30s token_renewable true token_policies [root] +# Test the new token $ VAULT_TOKEN=3b2b1285-844b-4b40-6afa-623f39c1b738 vault token-lookup Key Value --- ----- @@ -220,13 +223,13 @@ token usage. You can **renew** the token's TTL as long as the token has not expired, yet. ```shell -vault token-renew +$ vault token-renew ``` If you want to renew and extend the token's TTL, pass the desired extension: ```shell -vault token-renew +$ vault token-renew ``` The extension value can be an integer number of seconds (e.g. 3600) or a string @@ -235,10 +238,11 @@ duration (e.g. "1h"). #### API call using cURL -```plaintext -curl -X POST -H "X-Vault-Token: $VAULT_TOKEN" -d '{"ttl": "30s"}' \ - $VAULT_ADDR/v1/auth/token/create | jq - +```shell +# Create a new token with TTl of 30 seconds +$ curl --header "X-Vault-Token: ..." --request POST \ + --data '{"ttl": "30s"}' \ + https://vault.rocks/v1/auth/token/create | jq { ... "auth": { @@ -252,18 +256,15 @@ curl -X POST -H "X-Vault-Token: $VAULT_TOKEN" -d '{"ttl": "30s"}' \ "renewable": true } } -``` - -#### Verification - -```plaintext -curl -X GET -H "X-Vault-Token: f7d88963-1aba-64d7-11a0-9282ae7681d0" \ - $VAULT_ADDR/v1/auth/token/lookup-self | jq +# Pass the returned token (`client_token`) in the `X-Vault-Token` header to test +$ curl --header "X-Vault-Token: f7d88963-1aba-64d7-11a0-9282ae7681d0" \ + --request GET \ + https://vault.rocks/v1/auth/token/lookup-self | jq { ... "data": { - "accessor": "a54fea3f-6c09-d288-ede5-53288569f988", + "accessor": "a54fea3f-6c09--data288-ede5-53288569f988", "creation_time": 1515702669, "creation_ttl": 30, ... @@ -281,11 +282,14 @@ token usage. #### Renew the token: -```plaintext -$ curl -X POST -H "X-Vault-Token: $VAULT_TOKEN" $VAULT_ADDR/v1/auth/token/renew/ | jq +```shell +$ curl --header "X-Vault-Token: ..." --request POST \ + https://vault.rocks/v1/auth/token/renew/ | jq -$ curl -X POST -H "X-Vault-Token: $VAULT_TOKEN" -d '{"increment": "3600"}' \ - $VAULT_ADDR/v1/auth/token/renew/ | jq +# Renew token with 1 hour extension +$ curl --header "X-Vault-Token: ..." --request POST \ + --data '{"increment": "3600"}' \ + https://vault.rocks/v1/auth/token/renew/ | jq ``` -> **NOTE:** Tokens can be renewed as long as its life hasn't reached its max @@ -312,12 +316,12 @@ Create a token with `-use-limit` property argument. **Example:** ```shell -vault token-create -policy=default -use-limit=2 +$ vault token-create -policy=default -use-limit=2 Key Value --- ----- token bd39178e-176e-cc91-3930-94f7b0194de5 -token_accessor a230f5ab-b59f-db0b-855d-36ea4319b58e +token_accessor a230f5ab-b59f--datab0b-855d-36ea4319b58e token_duration 768h0m0s token_renewable true token_policies [default] @@ -332,7 +336,7 @@ $ VAULT_TOKEN=bd39178e-176e-cc91-3930-94f7b0194de5 vault token-lookup Key Value --- ----- -accessor a230f5ab-b59f-db0b-855d-36ea4319b58e +accessor a230f5ab-b59f--datab0b-855d-36ea4319b58e creation_time 1515710251 creation_ttl 2764800 display_name token @@ -373,10 +377,10 @@ the attempt to read the secret from cubbyhole failed. Set the `num_uses` property in the request payload. -```plaintext -curl -X POST -H "X-Vault-Token: $VAULT_TOKEN" -d '{ "policies": ["default"], "num_uses":2 }' \ - $VAULT_ADDR/v1/auth/token/create | jq - +```shell +$ curl --header "X-Vault-Token: ..." --request POST \ + --data '{ "policies": ["default"], "num_uses":2 }' \ + https://vault.rocks/v1/auth/token/create | jq { "request_id": "0e98ff80-2825-7f50-6522-b6f95d596ef4", "lease_id": "", @@ -402,9 +406,10 @@ This creates a token with _default_ policy with use limit of 2. #### Verification -```plaintext -$ curl -X GET -H "X-Vault-Token: d9c2f2e5-6b8a-4021-476c-ebd3f166d668" \ - $VAULT_ADDR/v1/auth/token/lookup-self | jq +```text +$ curl --header "X-Vault-Token: d9c2f2e5-6b8a-4021-476c-ebd3f166d668" \ + --request GET \ + https://vault.rocks/v1/auth/token/lookup-self | jq { "request_id": "77be1321-c0ca-e099-6f92-4ad87133b044", "lease_id": "", @@ -424,12 +429,15 @@ $ curl -X GET -H "X-Vault-Token: d9c2f2e5-6b8a-4021-476c-ebd3f166d668" \ ... } -$ curl -X POST -H "X-Vault-Token: d9c2f2e5-6b8a-4021-476c-ebd3f166d668" \ - -d '{ "value": "d9c2f2e5-6b8a-4021-476c-ebd3f166d668" }' $VAULT_ADDR/v1/cubbyhole/token +$ curl --header "X-Vault-Token: d9c2f2e5-6b8a-4021-476c-ebd3f166d668" \ + --request POST \ + --data '{ "value": "d9c2f2e5-6b8a-4021-476c-ebd3f166d668" }' \ + https://vault.rocks/v1/cubbyhole/token -$ curl -X GET -H "X-Vault-Token: d9c2f2e5-6b8a-4021-476c-ebd3f166d668" $VAULT_ADDR/v1/cubbyhole/token | jq - +$ curl --header "X-Vault-Token: d9c2f2e5-6b8a-4021-476c-ebd3f166d668" \ + --request GET \ + https://vault.rocks/v1/cubbyhole/token | jq { "errors": [ "permission denied" @@ -458,24 +466,24 @@ token renewal period. This value can be an integer value in seconds (e.g. 2764800) or a string duration (e.g. 72h). ```shell -vault write auth/token/roles/ allowed_policies="" period= +$ vault write auth/token/roles/ allowed_policies="" period= ``` **Example:** ```shell -vault write auth/token/roles/zabbix allowed_policies="zabbix-pol, default" period="24h" +$ vault write auth/token/roles/zabbix allowed_policies="zabbix-pol, default" period="24h" ``` Now, generate a token: ```shell -vault token-create -role=zabbix +$ vault token-create -role=zabbix Key Value --- ----- token de91ebba-20ad-18ba-fa43-08e1932de301 -token_accessor 1f8abad0-c1db-9399-15ee-dd4b6230386c +token_accessor 1f8abad0-c1db-9399-15ee--datad4b6230386c token_duration 24h0m0s token_renewable true token_policies [default zabbix-pol] @@ -492,11 +500,11 @@ token renewal period. This value can be an integer value in seconds (e.g. **Example:** ```plaintext -$ curl -X POST -H "X-Vault-Token: $VAULT_TOKEN" -d @token-role.json \ - $VAULT_ADDR/v1/auth/token/roles/zabbix +$ curl --header "X-Vault-Token: ..." --request POST \ + --data @token-role.json \ + https://vault.rocks/v1/auth/token/roles/zabbix $ cat token-role.json - { "allowed_policies": [ "default", @@ -511,9 +519,9 @@ policies attached. Also, its renewal period is set to 24 hours. Now, generate a token: -```plaintext -curl -X POST -H "X-Vault-Token: $VAULT_TOKEN" $VAULT_ADDR/v1/auth/token/create/zabbix | jq - +```shell +$ curl --header "X-Vault-Token: ..." --request POST \ + https://$ vault.rocks/v1/auth/token/create/zabbix | jq { ... "auth": { @@ -545,14 +553,15 @@ indefinitely. To create AppRole periodic tokens, create your AppRole role with **Example:** ```plaintext -vault write auth/approle/role/jenkins policies="dev-pol,devops-pol" period="72h" +$ vault write auth/approle/role/jenkins policies="dev-pol,devops-pol" period="72h" ``` Or ```plaintext -$ curl -X POST -H "X-Vault-Token:$VAULT_TOKEN" -d @payload.json \ - $VAULT_ADDR/v1/auth/approle/role/jenkins +$ curl --header "X-Vault-Token:..." --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/approle/role/jenkins $ cat payload.json { @@ -564,7 +573,7 @@ $ cat payload.json } ``` -For more details about AppRole, refer to [Authentication - AppRole guide](/guides/authentication.html). +For more details about AppRole, refer to [AppRole Pull Authentication](/guides/authentication.html). @@ -579,14 +588,15 @@ parent does. #### CLI command ```shell -vault token-create -orphan +$ vault token-create -orphan ``` #### API call using cURL -```plaintext -$ curl -X POST -H "X-Vault-Token:$VAULT_TOKEN" -d '{ "no_parent": true }' \ - $VAULT_ADDR/v1/auth/token/create-orphan | jq +```shell +$ curl --header "X-Vault-Token:..." --request POST \ + --data '{ "no_parent": true }' \ + https://vault.rocks/v1/auth/token/create-orphan | jq ``` @@ -599,13 +609,13 @@ Revoking a token and all its children. To revoke a specific token: ```shell -vault token-revoke +$ vault token-revoke ``` To revoke all tokens under a specific path: ```shell -vault token-revoke -prefix +$ vault token-revoke -prefix ``` **Example:** @@ -630,16 +640,18 @@ To revoke a specific token, call `/auth/token/revoke` endpoint. If you want to **Example:** ```shell - # Revoke a specific token -$ curl -X POST -H "X-Vault-Token:$VAULT_TOKEN" -d '{ "token": "eeaf890e-4b0f-a687-4190-c75b1d6d70bc" }' \ - $VAULT_ADDR/v1/auth/token/revoke +$ curl --header "X-Vault-Token:..." --request POST \ + --data '{ "token": "eeaf890e-4b0f-a687-4190-c75b1d6d70bc" }' \ + https://vault.rocks/v1/auth/token/revoke # Revoke all secrets for database auth backend -$ curl -X POST -H "X-Vault-Token:$VAULT_TOKEN" $VAULT_ADDR/v1/sys/leases/revoke-prefix/database/creds +$ curl --header "X-Vault-Token:..." --request POST \ + https://vault.rocks/v1/sys/leases/revoke-prefix/database/creds # Revoke all tokens -$ curl -X POST -H "X-Vault-Token:$VAULT_TOKEN" $VAULT_ADDR/v1/sys/leases/revoke-prefix/auth/token/create +$ curl --header "X-Vault-Token:..." --request POST \ + https://vault.rocks/v1/sys/leases/revoke-prefix/auth/token/create ``` @@ -678,8 +690,9 @@ $ vault write sys/mounts/database/tune default_lease_ttl="8640" Or ```plaintext -$ curl -X POST -H "X-Vault-Token:$VAULT_TOKEN" -d `{ "max_lease_ttl": 129600}`\ - $VAULT_ADDR/v1/sys/mounts/database/tune +$ curl --header "X-Vault-Token:..." --request POST \ + --data `{ "max_lease_ttl": 129600}`\ + https://vault.rocks/v1/sys/mounts/database/tune ``` #### 3. Check the role specific TTLs @@ -703,9 +716,4 @@ renewable true ``` - - - - - ## Next steps diff --git a/website/source/guides/static-secrets.html.md b/website/source/guides/static-secrets.html.md index 460efe4b5..a5fbe9a78 100644 --- a/website/source/guides/static-secrets.html.md +++ b/website/source/guides/static-secrets.html.md @@ -55,9 +55,8 @@ storage isn't enough to access your secrets. 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). @@ -87,10 +86,17 @@ You will perform the following: ### Step 1: Store the Google API key +If the secret path convention is **`secret//apikey/`**, store the +Google API key in `secret/eng/apikey/Googl`. If you have an API key for New Relic +owned by the DevOps team, the path may look like +`secret/devops/apikey/New_Relic`. + #### CLI command +To create key/value secrets: + ```shell -vault write secret/ =VALUE> +$ vault write secret/ =VALUE> ``` The `` can be anything you want it to be, and your organization should @@ -99,48 +105,46 @@ decide on the naming convention that makes most sense. **Example:** ```shell -vault write secret/eng/apikey/Google key=AAaaBBccDDeeOTXzSMT1234BB_Z8JzG7JkSVxI +$ vault write secret/eng/apikey/Google key=AAaaBBccDDeeOTXzSMT1234BB_Z8JzG7JkSVxI Success! Data written to: secret/eng/apikey/Google ``` -> In this example, the path -> convention is **`secret//apikey/`**. Therefore, `secret/eng/apikey/Googl`. -> The key is "key" and its value is "AAaaBBccDDeeOTXzSMT1234BB_Z8JzG7JkSVxI". -> If you have an API key for New Relic owned by the DevOps team, the path may -> look like `secret/devops/apikey/New_Relic`. +The secret key is "key" and its value is "AAaaBBccDDeeOTXzSMT1234BB_Z8JzG7JkSVxI" in +this example. #### API call using cURL -Before begin, create the following environment variables for your convenience: +Use `/secret/` endpoint to create secrets: -- **VAULT_ADDR** is set to your Vault server address -- **VAULT_TOKEN** is set to your Vault token - -**Example:** - -```plaintext -$ export VAULT_ADDR=http://127.0.0.1:8201 - -$ export VAULT_TOKEN=0c4d13ba-9f5b-475e-faf2-8f39b28263a5 +```shell +$ curl --header "X-Vault-Token: " \ + --request POST \ + --data \ + /v1/secret/ ``` -To perform the same task using the Vault API, pass the token in the request header. +Where `` is your valid token, `` is the key-value pair(s) of your +secrets, and `secret/` is the path to your secrets. **Example:** ```shell -curl $VAULT_ADDR/v1/secret/eng/apikey/Google -X POST \ - -H "X-Vault-Token: $VAULT_TOKEN" --data '{"key": "AAaaBBccDDeeOTXzSMT1234BB_Z8JzG7JkSVxI"}' +$ curl --header "X-Vault-Token: ..." --request POST \ + --data '{"key": "AAaaBBccDDeeOTXzSMT1234BB_Z8JzG7JkSVxI"}' \ + https://vault.rocks/v1/secret/eng/apikey/Google ``` +The secret key is "key" and its value is +"AAaaBBccDDeeOTXzSMT1234BB_Z8JzG7JkSVxI" in this example. ### Step 2: Store the root certificate for MySQL -For the purpose of this guide, generate a new self-sign certificate using [OpenSSL](https://www.openssl.org/source/). +For the purpose of this guide, generate a new self-sign certificate using +[OpenSSL](https://www.openssl.org/source/). ```shell -openssl req -x509 -sha256 -nodes -newkey rsa:2048 -keyout selfsigned.key -out cert.pem +$ openssl req --request509 -sha256 -nodes -newkey rsa:2048 -keyout selfsigned.key -out cert.pem ``` Generated `cert.pem` file: @@ -174,23 +178,19 @@ save it as `cert.pem`. #### CLI command -The command is basically the same as the Google API key example. +The command is basically the same as the Google API key example. Now, the path +convention is **`secret//cert/`**. To store the root certificate +for production MySQL, the path becomes `secret/staging/cert/postgres`. **Example:** ```shell -vault write secret/prod/cert/mysql cert=@cert.pem +$ vault write secret/prod/cert/mysql cert=@cert.pem ``` -**NOTE:** Any value begins with "@" is loaded from a file. - This example reads the root certificate from a PEM file from the disk, and store it under `secret/prod/cert/mysql` path. - -> The path convention here is **`secret//cert/`**. This path -> has an environment flag (`prod`) to indicate that this is a root certificate -> for MySQL in production. If there is a root certificate for a PostgreSQL -> running in staging, you may store it in `secret/staging/cert/postgres`. +> **NOTE:** Any value begins with "@" is loaded from a file. #### API call using cURL @@ -200,10 +200,12 @@ To perform the same task using the Vault API, pass the token in the request head **Example:** ```shell -curl $VAULT_ADDR/v1/secret/eng/apikey/Google -X POST \ - -H "X-Vault-Token: $VAULT_TOKEN" --data @cert.pem +$ curl --header "X-Vault-Token: ..." \ + --request POST \ + --data @cert.pem \ + https://vault.rocks/v1/secret/prod/cert/mysql ``` - +> **NOTE:** Any value begins with "@" is loaded from a file. ### Step 3: Retrieve the secrets @@ -213,13 +215,13 @@ Retrieving the secret from Vault is simple. #### CLI command ```shell -vault read secret/ +$ vault read secret/ ``` **Example:** ```shell -vault read secret/eng/apikey/Google +$ vault read secret/eng/apikey/Google Key Value --- ----- refresh_interval 768h0m0s @@ -229,14 +231,14 @@ key AAaaBBccDDeeOTXzSMT1234BB_Z8JzG7JkSVxI To return the key value alone, pass `-field=key` as an argument. ```shell -vault read -field=key secret/eng/apikey/Google +$ vault read -field=key secret/eng/apikey/Google AAaaBBccDDeeOTXzSMT1234BB_Z8JzG7JkSVxI ``` #### Root certificate example: ```shell -vault read -field=cert secret/prod/cert/mysql +$ vault read -field=cert secret/prod/cert/mysql -----BEGIN RSA PRIVATE KEY----- MIIEowIBAAKCAQEA6E2Uq0XqreZISgVMUu9pnoMsq+OoK1PI54rsA9vtDE6wiRk0GWhf5vD4DGf1 ... @@ -247,8 +249,8 @@ MIIEowIBAAKCAQEA6E2Uq0XqreZISgVMUu9pnoMsq+OoK1PI54rsA9vtDE6wiRk0GWhf5vD4DGf1 **Example:** ```shell -curl $VAULT_ADDR/v1/secret/eng/apikey/Google -X GET -H "X-Vault-Token: $VAULT_TOKEN" | jq - +$ curl --header "X-Vault-Token: ..." --request GET \ + https://vault.rocks/v1/secret/eng/apikey/Google | jq { "request_id": "5a2005ac-1149-2275-cab3-76cee71bf524", "lease_id": "", @@ -268,15 +270,15 @@ curl $VAULT_ADDR/v1/secret/eng/apikey/Google -X GET -H "X-Vault-Token: $VAULT_TO Retrieve the key value with `jq`: ```shell -curl $VAULT_ADDR/v1/secret/eng/apikey/Google -X GET \ - -H "X-Vault-Token: $VAULT_TOKEN" | jq ".data.key" +$ curl --header "X-Vault-Token: ..." --request GET \ + https://vault.rocks/v1/secret/eng/apikey/Google | jq ".data.key" ``` #### Root certificate example: ```shell -curl $VAULT_ADDR/v1/secret/prod/cert/mysql -X GET \ - -H "X-Vault-Token: $VAULT_TOKEN" | jq ".data.cert" +$ curl --header "X-Vault-Token: ..." --request GET \ + https://vault.rocks/v1/secret/prod/cert/mysql | jq ".data.cert" ``` ## Additional Discussion @@ -294,7 +296,7 @@ enter the secret in a new line. After entering the secret, press **`Ctrl+d`** to end the pipe and write the secret to the Vault. ```shell -vault write secret/eng/apikey/Google key=- +$ vault write secret/eng/apikey/Google key=- AAaaBBccDDeeOTXzSMT1234BB_Z8JzG7JkSVxI @@ -313,7 +315,7 @@ Using the Google API key example, you can create a file containing the key (apik The CLI command would look like: ```shell -vault write secret/eng/apikey/Google @apikey.txt +$ vault write secret/eng/apikey/Google @apikey.txt ``` #### Option 3: Disable all vault command history @@ -326,7 +328,7 @@ in history. In bash: ```shell -export HISTIGNORE="&:vault" +$ export HISTIGNORE="&:vault" ``` **NOTE:** This prevents the use of the Up arrow key for command history as well. @@ -337,7 +339,7 @@ export HISTIGNORE="&:vault" The two examples introduced in this guide only had a single key-value pair. You can pass multiple values in the command. ```shell -vault write secret/dev/config/mongodb url=foo.example.com:35533 db_name=users \ +$ vault write secret/dev/config/mongodb url=foo.example.com:35533 db_name=users \ username=admin password=pa$$w0rd ```