Onboarding - Getting Started with Vault#

Hashicorp Vault is built around three main components: secrets engines, auth methods, and policies. Secrets engines are responsible for generating, storing, and managing secrets such as API keys, passwords, and certificates. Auth methods handle authentication, assigning identities and policies to users and applications. Policies are used to control access within Vault, defining what actions users and applications can perform on specific paths, ensuring secure and granular access management. Together, these components exist within a Vault namespace for each CESI unit or subteam.

graph LR;
    subgraph Vault Namespace
        direction LR;
        A[Auth Methods] --> B[Policies];
        B --> C[Secrets Engines];
    end

Accessing Vault as a User#

Note

Membership in a CESI unit's vault grouper groups is necessary to access vault. See this article for information on how to get access.

The Secrets Management team has pre-provisioned all onboarded teams with the auth method (SAML), policies, and basic kv-v2 secrets engine secret/ needed to access vault as a user. Once you are in the appropriate grouper group, you can use the Vault GUI or Vault CLI to login.

Accessing Vault as a Machine/Application#

Due to the varied nature of how teams may want their applications to interact with Vault, each team will be responsible for configuring the auth method and policies for their application to integrate with Vault. See the integration examples instructions for various patterns.

Quickstart Example#

Here is a quick start guide to login to Vault, write a sample secret, create a policy for an application to access Vault, and create an approle for the application to authenticate to Vault.

Install the vault CLI

Export the required environmental variables

Bash Session

export VAULT_ADDR=https://hcp-vault-private-vault-fc507e0d.5d5b1f21.z1.hashicorp.cloud:8200
export VAULT_NAMESPACE=admin/<CESI>

Login to Vault as a user

Command:

Bash Session

vault login --method=saml --namespace=admin

Example Response:

Bash Session

Complete the login via your SAML provider. Launching browser to:

Waiting for SAML authentication to complete...
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.

Key                  Value
---                  -----
token                <TOKEN>
token_accessor       <TOKEN ACCESSOR>
token_duration       1h
token_renewable      true
token_policies       ["default"]
identity_policies    ["default"]
policies             ["default"]
token_meta_role      saml_role

Write a sample secret (each secret can have one to many key=value pairs with the secret)

Command:

Bash Session

vault kv put --mount=secret first-secret username=admin password=s3cr3t

Example Response:

Bash Session

====== Secret Path ======
secret/data/first-secret

======= Metadata =======
Key                Value
---                -----
created_time       2025-04-17T19:26:40.479874266Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            2

Retrieve the sample secret

Command:

Bash Session

vault kv get --mount=secret first-secret

Example Response:

Bash Session

====== Secret Path ======
secret/data/first-secret

======= Metadata =======
Key                Value
---                -----
created_time       2025-04-17T19:26:40.479874266Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            2

====== Data ======
Key         Value
---         -----
password    s3cr3t
username    admin

Write a policy so that an application can read first-secret

Command:

Bash Session

vault policy write first-policy - <<EOF
path "secret/data/first-secret" {
        capabilities = ["read"]
}
EOF

Example Response:

Bash Session

Success! Uploaded policy: first-policy

Create an approle using the first-policy that can read first-secret. The maximum secret_id_ttl is 365 days per UIS policy.

Command:
Bash Session
```
vault write auth/approle/role/first-approle policies=first-policy secret_id_ttl="365d"
```
Example Response:
Bash Session
```
Success! Data written to: auth/approle/role/first-approle
```

Retrieve the role-id (alpha numberic username) and secret-id (password) for your role. Pay attention to the secret_id_ttl as you will need to create a new secret_id before it expires. You can have multiple secret_id's per role-id.

Commands:

Bash Session

vault read -field=role_id auth/approle/role/first-approle/role-id
vault write -force auth/approle/role/first-approle/secret-id

Example Responses:

Bash Session

<ROLE ID>
Key                   Value
---                   -----
secret_id             <SECRET ID>
secret_id_accessor    <SECRET ID ACCESSOR>
secret_id_num_uses    0
secret_id_ttl         8760h

Retrieve a vault token with the secret-id and role-id created in the last step to emulate connecting to vault as an application or machine and then login with that toke.

Commands:

Bash Session

vault write auth/approle/login role_id=<ROLE ID> secret_id=<SECRET ID>
vault login <TOKEN FROM PREVIOUS COMMAND (start with hvs.)>

Example Responses:

Bash Session

Key                     Value
---                     -----
token                   <TOKEN>
token_accessor          <TOKEN ACCESSOR>
token_duration          1h
token_renewable         true
token_policies          ["default" "first-policy"]
identity_policies       []
policies                ["default" "first-policy"]
token_meta_role_name    first-approle

Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.

Key                     Value
---                     -----
token                   <TOKEN>
token_accessor          <TOKEN ACCESSOR>
token_duration          59m22s
token_renewable         true
token_policies          ["default" "first-policy"]
identity_policies       []
policies                ["default" "first-policy"]
token_meta_role_name    first-approle

Retrieve the first-secret created in step 4.

Command:

Bash Session

vault kv get --mount=secret first-secret

Example Response:

Bash Session

====== Secret Path ======
secret/data/first-secret

======= Metadata =======
Key                Value
---                -----
created_time       2025-04-17T19:26:40.479874266Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            2

====== Data ======
Key         Value
---         -----
password    s3cr3t
username    admin

Log back in as yourself and clean up (delete secret, policy and approle)

Commands:

Bash Session

vault login --method=saml --namespace=admin
vault kv delete secret/data/first-secret
vault policy delete first-policy
vault delete auth/approle/role/first-approle

Example Responses:

Bash Session

    Complete the login via your SAML provider. Launching browser to:

Waiting for SAML authentication to complete...
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.

Key                  Value
---                  -----
token                <TOKEN>
token_accessor       <TOKEN ACCESSOR>
token_duration       1h
token_renewable      true
token_policies       ["default"]
identity_policies    ["default"]
policies             ["default"]
token_meta_role      saml_role

Success! Data deleted (if it existed) at: secret/data/data/first-secret

Success! Deleted policy: first-policy

Success! Data deleted (if it existed) at: auth/approle/role/first-approle

Migrating from Azure Keyvault to Vault#

See this article