Unit 5 — Identity, Policy and Governance

Blast radius of an identity. Vault is an identity-based secrets management solution, where access to a secret is based on the known and verified identity of a client. It is crucial that authenticating identities to Vault are identifiable and only have access to the secrets they are the users of. Secrets should never be proxied between Vault and the secret end-user and a client should never have access to secrets they are not the end-user of.

Duration of authentication. When Vault verifies an entity’s identity, Vault then provides that entity with a token. The client uses this token for all subsequent interactions, so this token should be both handled securely and have a limited lifetime. A token should only live for as long as access to the secrets it authorizes access to are needed.

“Never proxy secrets” is the principle most often violated in the field, usually by a CI system fetching secrets on an application’s behalf. Name the principle, not the symptom.

Phase 1 — authentication. Vault authenticates the external identity using a dedicated auth method, which may involve Vault making outbound calls to the external identity provider (for example, calling the Kubernetes API for TokenReview to validate the service account in real-time, or calling AWS STS). Upon successful verification, Vault issues a short-lived token tied directly to the identity. This token inherits Vault policies based on the authentication method’s role configuration, which includes bound constraints to validate the identity’s attributes. Additional policies may also inherit from internal or external identity group membership.

Phase 2 — authorization. Vault evaluates the token against its attached policies, which are deny-by-default rules written in HCL, to determine permissible actions within Vault. These path-based policies control access to specific endpoints, enforcing least privilege. Vault’s identity subsystem governs this mapping. It bridges verification to authorized actions but remains Vault-internal.

Phase 2b — Sentinel (optional, Enterprise / HCP Vault Dedicated Plus). Sentinel policies apply after access control list evaluation but before the request reaches the secrets engine backend, using policy-as-code to enforce dynamic rules based on request context, such as time, network origin, or parameters. Role Governing Policies (RGPs) tie to the identity for entity-specific checks, while Endpoint Governing Policies (EGPs) apply to paths for parameter validation. Sentinel is useful when you need additional logical context or conditions beyond static configurations in secret engine roles.

Example: an EGP could deny requests to a restricted AWS secrets engine role for elevated permissions if the client’s IP is not from a trusted CIDR range, providing dynamic network-based control to prevent unauthorized brokering from untrusted locations.

Phase 2c — control groups (optional, Enterprise). In scenarios requiring oversight for sensitive requests, control groups can enforce a quorum-based approval workflow, wrapping the request and requiring approvals from designated identities before proceeding. While less common for fully automated non-human workflows, it may be valuable for hybrid setups with elevated risks. Example: for a request to generate administrator-level PostgreSQL credentials, control groups could mandate two approvals.

Phase 3 — issuance. The token requests credentials from a secrets engine role. The engine uses its own administrator credentials or established trust relationship to interact with the external platform. The secrets engine role’s configuration entirely defines the mapping of permissions in the target system (for example, IAM policy ARNs/document or SQL grant statements), not Vault’s ACL policies. Leases assign TTL values to these credentials, enabling automatic expiration and central revocation.

That last point is the one architects get wrong. ACL policies control which role you may invoke. The role controls what the resulting credential can do in the target system. Two authorization surfaces, potentially two owning teams. Draw it on a whiteboard early.

Entities represent a human or workload and carry metadata. Aliases bind an entity to a specific credential in a specific auth mount. Groups collect entities and attach shared policies.

Pre-creating entities — Vault allows pre-defining entities with metadata that ACL policy templates can reference dynamically, associating a machine identity with a policy via Vault’s entity construct:

vault write -format=json identity/entity \
  name="my-app" \
  metadata=AppName="my-app" \
  metadata=BusinessUnitName="tenant-1" \
  metadata=TeamName="team-a" \
  metadata=EmailDistributionList="team-a@example.com" \
  metadata=TLSDomain="app.tenant-1.example.com" \
  | jq -r ".data.id" > /tmp/entity_id.txt

vault auth list -format=json | jq -r '.["aws/"].accessor' > /tmp/accessor_aws.txt

vault write identity/entity-alias \
  name="arn:aws:iam::123456789012:role/this-iam-role" \
  canonical_id=$(cat /tmp/entity_id.txt) \
  mount_accessor=$(cat /tmp/accessor_aws.txt)

External groups are Vault’s representation of a group outside its identity store. A group alias ties the Vault external group to a group in your identity provider. During authentication, Vault will attempt to match a provider group to an external group using the group claim. If a match is found, an entity is added as a member of the external group and a token is returned with the associated policy.

GROUP_ID=$(vault write -format=json identity/group \
  name="vault-operators" \
  type="external" \
  policies="operator" | jq -r ".data.id")

MOUNT_ACCESSOR=$(vault read -field=accessor sys/mounts/auth/oidc)

vault write identity/group-alias \
  name="vault-operators" \
  mount_accessor=$MOUNT_ACCESSOR \
  canonical_id=$GROUP_ID

Critical behavior: if a user is removed from the group in your OIDC provider, that change gets reflected in Vault only upon a subsequent login or token renewal operation.

This is general behavior, not a bug. It makes token_ttl the primary control over revocation latency for human access. A customer with a 24-hour deprovisioning SLA and a long token TTL cannot meet it regardless of how well their IdP integration works.

Policies are deny-by-default HCL granting capabilities on paths.

Path templating — use ACL policy path templating to dynamically assign access based on entity metadata. This approach reduces manual policy configuration overhead while maintaining strict role-based access controls.

path "pki/issue/{{identity.entity.metadata.TeamName}}" {
  capabilities = ["update"]
}

⚠ Vault 2.0.1 breaking change. Vault now returns a “permission denied” error if you include wildcards and globs in the rendered output for identity templates.

The template above is safe because TeamName renders to a literal. But if entity metadata contains a glob character — from a naming convention, an IdP-sourced attribute, or SCIM mapping — the rendered path contains a wildcard and the request is denied.

With SCIM driving entity metadata from an external IdP, those values are no longer under the Vault team’s control. Audit metadata values feeding templated policy paths for glob characters, and constrain them at the source.

Manage policies as code. Use a version-controlled repository to manage configurations and policies. Where possible, define these through Terraform to support auditability, repeatability, and safe change rollouts.

If your organization already has a user authentication system tied into the user lifecycle and Vault supports it (e.g. OIDC, LDAP), you should consider using this as an auth method. In this case, you only have one place to manage your users, and users are less likely to get stranded in Vault either in a group they have moved from or as a legacy user that no longer works in the organization.

“Stranded users” names the deprovisioning risk concretely. Use it.

OIDC

Workflow: user requests authentication → Vault launches a browser to the configured discovery URL → user submits credentials → the provider returns an OAuth token containing information about the user such as security groups that the user is a member of, which could map to an identity group within Vault → Vault maps the security group claims to pre-configured identity groups, which are attached to Vault policies → policies attached to a token → token returned.

vault auth enable oidc

vault write auth/oidc/config \
    oidc_discovery_url="https://sso.example.com" \
    oidc_client_id="vault" \
    oidc_client_secret="passw0rd" \
    oidc_discovery_ca_pem=@ca.pem \
    default_role="default"

Vault nodes need the ability to connect to the specified oidc_discovery_url typically over TCP port 443 to retrieve OIDC metadata. Set oidc_discovery_ca_pem to the CA validating that connection; if not set, the system certificates will be used. The role named in default_role does not have to exist at this stage.

OIDC could be enabled multiple times on different paths, for different OIDC providers or different environments, using -path.

vault write auth/oidc/role/default -<<EOF
{
 "user_claim": "email",
 "groups_claim": "groups",
 "allowed_redirect_uris": [ "https://vault.example.com:8200/ui/vault/auth/oidc/oidc/callback", "https://vault.example.com:8250/oidc/callback" ],
 "token_policies": "default",
 "token_ttl": "1h",
 "token_max_ttl": "1h"
}
EOF

• user_claim — the claim in the OAuth token used to uniquely identify the user. This will be used as the name for the identity entity alias created due to a successful login.
• groups_claim — the claim used to uniquely identify the set of groups to which the user belongs. Vault will attempt to match the value from this claim to an external group created within Vault.
• allowed_redirect_uris — the URI with port 8200 is for login via the UI whereas the URI with port 8250 is for login via the CLI. These URIs must match the configuration on the OIDC provider.
• token_ttl — always provide a token TTL value to override the default token TTL of 32 days (768 hours).
• token_max_ttl — the token cannot be renewed past the allowed max TTL.

Multiple roles can be created under a single auth method. The default role created is only used when the user does not specify a role during authentication.

Namespace behaviors to know:

• In order to access the org namespace, super administrators must first login via the root namespace. Once authenticated, the token granted can be used to operate on the org namespace.
• Users who are mapped in the tenant namespace can still login to the root namespace. However, their access is restricted by the default policy since there is no external group and policy mapping for these users in the root namespace.

In login output, token_policies and identity_policies are distinct, with policies as the union. Policies arriving via an external group appear in identity_policies. When debugging “why does this token have that permission,” check both.

LDAP

Vault must be able to communicate with the LDAP server over TCP and UDP port 389, or on port 636 for LDAPS. When an authentication request is made, Vault verifies the provided credentials with the backend LDAP server through a service account. LDAP groups can be directly mapped to Vault policies.

vault auth enable ldap

vault write auth/ldap/config \
 url="ldap://ldap.example.com" \
 userattr="sAMAccountName" \
 userdn="ou=Users,dc=example,dc=com" \
 groupdn="ou=Groups,dc=example,dc=com" \
 groupattr="cn" \
 binddn="cn=vault,ou=users,dc=example,dc=com" \
 bindpass="My$ecr3tP4ss" \
 certificate=@ldap_ca_cert.pem \
 insecure_tls=false \
 starttls=true \
 discoverdn=false \
 token_ttl=1h \
 token_max_ttl=8h

The scenario encoded: STARTTLS on the standard port; CA cert in a file; anonymous binds not allowed for user search, hence discoverdn=false; usernames map to sAMAccountName; group membership via the cn attribute.

vault write auth/ldap/groups/vault-operators policies=operator

Two types:

1. Login MFA — additional layers of security to login workflows.
2. Vault Enterprise “step up” MFA — an enhanced security layer to protect sensitive API endpoints.

Prefer the IdP. Many external identity providers like Okta or Ping Identity enable login MFA on their platforms, typically mandating MFA verification during the authentication process before granting access. This approach is preferred when the IDP supports MFA because it allows you to keep all human identity management, access control, and MFA configurations in one place. It also provides scalability as your organization grows.

LDAP and TOTP. While many OIDC-compliant IDPs support implementing MFA at the identity provider level, it is less common for LDAP providers to offer native MFA support. Where they don’t, Vault supports TOTP.

The scaling constraint: due to the enrollment process involving sharing a key between Vault and an end-user’s mobile device, the TOTP method is not suitable for enrolling large numbers of users. It is therefore recommended to implement TOTP with LDAP authentication on the relatively smaller number of highly privileged users (Super administrators and regular administrators) to protect their access to Vault.

That’s the answer to “can we just turn on Vault MFA for everyone?” — no. Either the IdP does MFA, or MFA covers privileged accounts only.

Configuration sequence (steps 3–4 repeat per user): enable LDAP; enable a Login MFA method and note the method_id; have the user log in and capture their entity_id; generate a PNG TOTP QR code using both, to be scanned with an authenticator app, then delete the QR Code image after scanning; capture the accessor value for the LDAP auth mount and create the enforcement by tying the MFA method_id to the accessor; test.

Algorithm constraint: consider the algorithms supported by your end-user authenticator application. Google Authenticator for Android supports only SHA1. The Vault MFA API defaults to the SHA1 algorithm if no value is supplied.

Step-up MFA requires a user to present an additional identity factor when issuing specific API requests, even if they have already successfully authenticated to Vault.

Where highly critical secrets are stored in Vault for human users to access, it is recommended to implement a step up MFA policy that provides additional security and identity assurance.

The worked example: a secret at secret/topsecret/data/foo gated so any authenticated user must complete an MFA workflow first. This provides additional assurance that the user accessing the path is the same user that originally authenticated, and that their Vault token has not been compromised.

That’s the security property to name — step-up MFA defends against token compromise, which ACLs and login MFA cannot.

Supported methods: TOTP, Okta push notification, Duo push notification, and PingID push notification.

HCP limitation: Enterprise “step up” MFA cannot be configured on HCP Vault; the sys/mfa/ path is only accessible from the root namespace, which is not available to the end user in HCP Vault.

Configuration mirrors login MFA for method setup, then: create a policy that gates access to a sensitive secret through the previously created MFA method, and test — when reading the secret, the mfa flag needs to be supplied containing the appropriate TOTP code, otherwise Vault will not grant access. Steps linking the MFA method to a Vault ACL policy remain the same for other MFA methods.