xDev Asia

Identity Secrets Engine, Entities và Aliases, Entity policies, Internal Groups vs External Groups, Group aliases, Identity Tokens (OIDC provider), MFA — TOTP, Duo, Okta, PingID, MFA TOTP self-enrollment (1.21).

HashiCorp Vault từ Cơ bản đến Nâng cao

Phần 3: Auth Methods - Xác thực và Ủy quyền

xdev.asia

1. Identity Secrets Engine

Identity Secrets Engine là thành phần nội bộ của Vault, tự động được enable và không thể disable. Nó quản lý identity — kết hợp nhiều auth method identities thành một view thống nhất.

Vấn đề cần giải quyết

Một user có thể xác thực qua nhiều auth methods khác nhau:

Login bằng LDAP khi dùng CLI
Login bằng OIDC khi dùng Web UI
Service account của user dùng AppRole

Vault cần cách để nhận biết đây là cùng một người và áp dụng policies nhất quán.

Kiến trúc Identity

┌─────────────────────────────────────────────────┐
│                   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 và Aliases

Tạo 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

Tạo 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"

Bây giờ khi john.doe login bằng LDAP hoặc OIDC, Vault nhận biết đây là cùng entity và áp dụng 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 được quản lý hoàn toàn bên trong 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 từ LDAP/OIDC groups vào 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 có thể hoạt động như một OIDC Provider — phát hành OIDC tokens dựa trên 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 hỗ trợ MFA để thêm lớp xác thực thứ hai. Có hai loại MFA:

Loại	Mô tả	Khi nào yêu cầu
Login MFA	Yêu cầu MFA khi login	Mọi login request
Step-up MFA	Yêu cầu MFA cho operations nhạy cảm	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)

Tính năng mới trong Vault 1.21 cho phép users tự đăng ký 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>"

┌──────────┐   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. Tổng kết

Identity Engine — kết hợp nhiều auth identities thành một entity duy nhất
Entities + Aliases — map users across LDAP, OIDC, AppRole
Groups — Internal (Vault-managed) và External (LDAP/OIDC groups)
Identity Tokens — Vault như OIDC Provider
MFA — TOTP, Duo, Login MFA và Step-up MFA
TOTP Self-enrollment (1.21) — users tự đăng ký MFA

Phần tiếp theo sẽ đi vào Secrets Engines nâng cao — SSH, TOTP, Transform, KMIP và Custom Plugins.

Bài 15: Identity Secrets Engine, Entities và MFA