Is production: true

HashiCorp Vault

Web Site

Vault Structure

HashiCorp Vault is designed around a core set of components that work together to manage secrets and identity. Understanding these building blocks is crucial for operating Vault effectively. It uses a component-based architecture to decouple identity from the secret data itself.

1. Authentication (Auth Methods)

Before anyone (user or machine) can interact with Vault, they must authenticate. Auth Methods are the components that perform this verification. Vault supports a wide variety of methods to suit different environments:

Key Concept: Authentication does not directly grant access to secrets. Instead, successful authentication returns a Token.

2. Tokens

The Token is the core unit of authentication within Vault. Once an Auth Method verifies an identity, Vault issues a token to that client.

3. Policies

Policies are the authorization layer (RBAC). They define what a token can do.

4. Secret Engines

This is where the actual secrets live. Secret engines are plugins that store, generate, or encrypt data.

Main Secret Engines:

Mounting: Secret engines are “mounted” at specific paths. You can mount the same engine multiple times at different paths (e.g., secret/ for general secrets and apps/ for application secrets).

5. Paths & Namespaces

Vault behaves like a virtual filesystem.

Putting It All Together (The Logic: Retrieving a Secret from KV Engine)

Diagram for retreiving the secret from KV engine

  1. Login: A client (e.g., a web server) sends credentials (like a RoleID and SecretID) to the AppRole Auth Method endpoint.
  2. Verification: Vault checks the credentials. If valid, it generates a Token.
  3. Policy Attachment: Vault looks up which policies are assigned to that AppRole and attaches them to the Token.
  4. Request: The client wants to read a secret (e.g., an API key or password). It sends a request to secret/data/myapp/config (for KV v2) including its Token.
  5. Authorization: Vault checks the Token’s policies. Does this token have read permission on secret/data/myapp/config?
  6. Action: If yes, the KV Secret Engine retrieves the stored secret data (e.g., username and password) from the specified path.
  7. Response: Vault returns the secret data to the client.

Start a Vault Instance

Command Line for dev mode

Vault Dev Server Docs

vault server -dev

Docker Compose

The startup requires docker for quick and easy initialization.
docker-compose.yaml and the config/config.hcl is mandatory requirements.

  1. Create docker compose file

  2. Create configuration file under config/

  3. Start the service docker compose up -d

  4. Setup the vault address

    export VAULT_ADDR=http://localhost:8200

  5. type vault operator init, the vault will init and generate [Vault Initialization Docs]

    1. the unseal keys for later on usage (remember keep it safe)
    2. the Initial Root Token (used for accessing the vault)
    vault operator init
# vault operator init -key-shares={number of keys} -key-threshold={number to unlock}

  6. type vault operator unseal <Unseal_Key> for unseal the vault

Login to the vault

There is only a one method that user can access to the vault server, providing a vault token (set up envrionment variable VAULT_TOKEN).

Command as export VAULT_TOKEN={token} in linux.

Command as set VAULT_TOKEN={token} in CMD Windows.

Root Token (life long token)

But there is multiple ways to acquire a vault token, the raw and easiest way is that when the vault is first time init throught vault operator init method, the unseal token and the root token is generated automaticall. officially, if user don’t do anything, the root token should be a powerful and life long vault session token, which mean the root token is never expired.

Other Token (token expires by default)

In vault server, there is a lot of authentication method for accessing the vault server.
User can user vault auth list to view the current enabled authentication method.

Approle

Approle is one of the main methodology for accessing the machines or application to access to the vault server.
Use vault auth enable approle to enable the approle in vault serve

Creation

Normally below script cover most of the setting on creating a approle.

vault write auth/approle/role/{role name} \
    policies="policy1,policy2" \
    secret_id_ttl="24h" \
    token_ttl="1h" \
    token_max_ttl="4h" \
    secret_id_num_uses=10 \
    token_num_uses=5 \
    enable_local_secret_ids=true

For simplicity, if you want an AppRole that works indefinitely, but each issued token is valid for only 10 minutes, you can define the AppRole as below:

vault write auth/approle/role/{role name} \
    policies="policy1,policy2" \
    token_ttl="10m"
Role ID

RoleID is the unique identifier for an AppRole in Vault. It acts as the first factor in AppRole authentication and is required (along with SecretID) to log in and obtain a token.

Set a custom RoleID: Vault allows you to set a custom RoleID when creating or updating an AppRole:

vault write auth/approle/role/{role name} role_id="{custom_role_id}"

This can be useful for integration with external systems or for easier management.

Retrieve a RoleID:

vault read auth/approle/role/{role name}/role-id
Secret ID

SecretID is a credential used in Vault’s AppRole authentication method. It acts as a second factor (along with RoleID) to authenticate machines or applications securely.

Generate a SecretID:

vault write -f auth/approle/role/{role name}/secret-id

This command returns a new SecretID for the specified AppRole.

Important: SecretIDs cannot be set manually—they can only be generated by Vault. This ensures that no one can predict or predefine the next SecretID, enhancing security.

This command returns a new, unpredictable SecretID for the specified AppRole.

Login to get a Token

To log in to Vault using AppRole, use the following command with your RoleID and SecretID:

vault write auth/approle/login role_id="{role_id}" secret_id="{secret_id}" # token will return by this command

This will return a Vault token that you can use to access secrets according to the policies attached to the AppRole.

KV Secret Engine

KV Secret Engine: Usage and Operations

The KV (Key-Value) secret engine is the most common way to store static secrets in Vault. Below are the typical operations:

1. Enable a KV secret mount: You can enable a KV engine at a specific path (e.g., “mysecrets”):

vault secrets enable -path=mysecrets kv

For KV v2 (with versioning):

vault secrets enable -path=mysecrets kv-v2

2. List all secret mounts: To see all enabled secret engines:

vault secrets list

3. List secret paths under a given secret mount: To list keys (secret paths) under a mount (e.g., “mysecrets”) for both KV v1 and KV v2, use:

vault kv list mysecrets/

The CLI handles the versioning and path details internally for KV v2.

4. Store (put) secret data at a secret path: To store secret data at a path:

vault kv put mysecrets/myapp username="admin" password="s3cr3t"

This command writes the key-value pairs to the specified path.

5. Get the secret payload from a secret path: To retrieve the secret data stored at a path:

vault kv get mysecrets/myapp

The CLI handles the versioning and path details internally for KV v2.

Basic

Check Vault Status

vault status

Related articles:

Hashicorp Vault Migration Scripts
March 18, 2026 by Xeth [~1 mins]

#vault