1. Identity Secrets Engine
Identity Secrets Engine is an internal component of Vault, automatically enabled and cannot be disabled. It manages identity — combining multiple auth method identities into a unified view.
Problem to be solved
A user can authenticate through many different auth methods:
Login with LDAP when using CLI
Login with OIDC when using Web UI
Service account of user using AppRole
Vault needs a way to recognize that this is the same person and apply policies consistently.
Identity Architecture
┌─────────────────────────────────────────────────┐
│ Entity │
│ (Đại diện cho 1 người/machine duy nhất) │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Alias 1 │ │ Alias 2 │ │ Alias 3 │ │
│ │ (LDAP) │ │ (OIDC) │ │(AppRole)│ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │
│ Policies: [team-lead, dev-admin] │
│ Metadata: {team: platform, level: senior} │
│ │
│ Groups: [platform-team, all-engineers] │
└─────────────────────────────────────────────────┘
2. Entities and Aliases
Create Entity
# Tạo entity thủ công
vault write identity/entity \
name="john-doe" \
policies="team-lead" \
metadata='{"team": "platform", "employee_id": "EMP001", "email": "[email protected]"}'
# Đọc entity
vault read identity/entity/name/john-doe
# Liệt kê entities
vault list identity/entity/name
Create Aliases
# Lấy mount accessor cho auth methods
vault auth list -format=json | jq -r '."ldap/".accessor'
# auth_ldap_abc123
vault auth list -format=json | jq -r '."oidc/".accessor'
# auth_oidc_def456
# Tạo alias cho LDAP
vault write identity/entity-alias \
name="john.doe" \
canonical_id="<entity-id>" \
mount_accessor="auth_ldap_abc123"
# Tạo alias cho OIDC
vault write identity/entity-alias \
name="[email protected]" \
canonical_id="<entity-id>" \
mount_accessor="auth_oidc_def456"
Now when john.doe logs in using LDAP or OIDC, Vault recognizes this as the same entity and applies entity policies + group policies.
Entity Metadata trong Policies
# Policy template sử dụng entity metadata
path "secret/data/teams/{{identity.entity.metadata.team}}/*" {
capabilities = ["create", "read", "update", "delete", "list"]
}
# Dựa trên entity name
path "secret/data/users/{{identity.entity.name}}/*" {
capabilities = ["create", "read", "update", "delete", "list"]
}
3. Groups
Internal Groups
Internal groups are fully managed inside Vault:
# Tạo internal group
vault write identity/group \
name="platform-team" \
type="internal" \
policies="platform-admin,kv-platform" \
member_entity_ids="entity-id-1,entity-id-2,entity-id-3" \
metadata='{"department": "engineering", "cost_center": "CC001"}'
# Thêm member vào group
vault write identity/group/name/platform-team \
member_entity_ids="entity-id-1,entity-id-2,entity-id-3,entity-id-4"
# Nested groups (sub-groups)
vault write identity/group \
name="all-engineers" \
type="internal" \
policies="engineer-base" \
member_group_ids="<platform-team-id>,<backend-team-id>,<frontend-team-id>"
External Groups
External groups map from LDAP/OIDC groups to Vault policies:
# Tạo external group
vault write identity/group \
name="ldap-devops" \
type="external" \
policies="devops-admin,kv-devops"
# Map đến LDAP group via group alias
vault write identity/group-alias \
name="CN=DevOps,OU=Groups,DC=company,DC=com" \
mount_accessor="auth_ldap_abc123" \
canonical_id="<external-group-id>"
# Map đến OIDC group
vault write identity/group-alias \
name="devops" \
mount_accessor="auth_oidc_def456" \
canonical_id="<external-group-id>"
4. Identity Tokens (OIDC Provider)
Vault can act as a OIDC Provider — issuing OIDC tokens based on identity entity:
# Tạo assignment (ai được phát token)
vault write identity/oidc/assignment/dev-team \
entity_ids="entity-id-1,entity-id-2" \
group_ids="group-id-1"
# Tạo key cho signing
vault write identity/oidc/key/app-key \
algorithm="RS256" \
allowed_client_ids="*" \
rotation_period="24h"
# Tạo OIDC client
vault write identity/oidc/client/my-webapp \
redirect_uris="https://myapp.company.com/callback" \
assignments="dev-team" \
key="app-key" \
id_token_ttl="30m" \
access_token_ttl="1h"
# Tạo OIDC provider
vault write identity/oidc/provider/company \
issuer="https://vault.company.com" \
allowed_client_ids="<client-id>" \
scopes_supported="openid,email,profile,groups"
5. Multi-Factor Authentication (MFA)
Vault supports MFA to add a second layer of authentication. There are two types of MFA:
| Type | Description | When required |
|---|---|---|
| Login MFA | MFA request on login | All login requests |
| Step-up MFA | MFA request for sensitive operations | Specific paths/operations |
TOTP MFA
# Tạo TOTP MFA method
vault write identity/mfa/method/totp \
method_name="company-totp" \
issuer="VaultCompany" \
period=30 \
key_size=20 \
digits=6 \
algorithm="SHA1" \
qr_size=200
# Lấy MFA method ID
vault read identity/mfa/method/totp
# Tạo Login MFA enforcement
vault write identity/mfa/login-enforcement/require-totp \
mfa_method_ids="<totp-method-id>" \
auth_method_types="userpass,ldap" \
identity_group_ids="<admin-group-id>"
MFA TOTP Self-enrollment (Vault 1.21)
New feature in Vault 1.21 allows users to self-register for MFA TOTP:
# Admin: enable self-enrollment
vault write identity/mfa/method/totp \
method_name="self-totp" \
issuer="CompanyVault" \
allow_self_enrollment=true
# User: login rồi enroll TOTP
# 1. Login
vault login -method=userpass username=john.doe
# 2. Generate TOTP secret (trả về QR code URL)
vault write identity/mfa/method/totp/admin-generate \
method_id="<totp-method-id>" \
entity_id="<my-entity-id>"
# 3. Quét QR code bằng app (Google Authenticator, Authy)
# 4. Login lần tiếp theo sẽ yêu cầu TOTP code
Duo MFA
# Cấu hình Duo MFA
vault write identity/mfa/method/duo \
method_name="company-duo" \
secret_key="<duo-secret-key>" \
integration_key="<duo-integration-key>" \
api_hostname="api-xxxxxxxx.duosecurity.com" \
push_info="Vault Login"
# Enforcement cho admin group
vault write identity/mfa/login-enforcement/admin-duo \
mfa_method_ids="<duo-method-id>" \
identity_group_ids="<admin-group-id>"
6. MFA Login Flow
┌──────────┐ 1. Login ┌──────────────┐
│ User │ ────────────────────▶ │ Vault │
│ │ │ │
│ │ 2. MFA Required │ │
│ │ (request_id) │ │
│ │ ◀──────────────────── │ │
│ │ │ │
│ │ 3. Submit MFA code │ │
│ │ + request_id │ │
│ │ ────────────────────▶ │ │
│ │ │ │
│ │ 4. Vault Token │ │
│ │ ◀──────────────────── │ │
└──────────┘ └──────────────┘
# Step 1: Login (trả về mfa_request_id nếu MFA required)
vault login -method=userpass username=john.doe
# Enter MFA code for method "company-totp":
# Step 2: Enter TOTP code
# 123456
# API flow
# Login → nhận mfa_request_id
curl -s --request POST \
--data '{"password": "p@ss"}' \
${VAULT_ADDR}/v1/auth/userpass/login/john.doe
# Validate MFA
curl -s --request POST \
--data '{
"mfa_request_id": "...",
"mfa_payload": {
"<totp-method-id>": ["123456"]
}
}' \
${VAULT_ADDR}/v1/sys/mfa/validate
7. Summary
Identity Engine — combine multiple auth identities into a single entity
Entities + Aliases — map users across LDAP, OIDC, AppRole
Groups — Internal (Vault-managed) and External (LDAP/OIDC groups)
Identity Tokens — Vault as OIDC Provider
MFA — TOTP, Duo, Login MFA and Step-up MFA
TOTP Self-enrollment (1.21) — users self-enroll MFA
The next section will go into advanced Secrets Engines — SSH, TOTP, Transform, KMIP and Custom Plugins.