Managing Vault Groups: Internal vs External Groups

Vault authentication happens per auth method, but authorization ultimately converges on Identity Entities and Groups. Groups are the central attachment point for policies, and choosing correctly between internal and external groups directly affects operational stability.

Based on the official documentation, this article walks through the differences between internal groups (type=internal) and external groups (type=external), how group-alias is used to import external IdP groups, and the evaluation flow and common pitfalls — all with an eye on exam preparation.

Vault Identity and Groups: The Basics

Vault Identity bundles login information from each auth method into an Entity (a person or application), connected via Aliases. Access permissions are the union of the policies attached to the Entity and its Groups.

Groups come in two flavors: internal (type=internal) and external (type=external). Internal groups manage their members inside Vault; external groups are read-mostly groups that map external groups (for example from an IdP) into Vault. External groups use a group-alias to map an external group name plus an auth method's mount_accessor to a Vault group.

• Entity: the identity of a user or machine. It consolidates logins from multiple auth methods.
• Entity Alias: binds an auth-method-specific ID to an Entity.
• Group: the unit of policy attachment. Can be nested.
• Group Alias: binds an external group name plus mount_accessor to a Vault Group.

Main API / CLI paths (excerpt)

identity/group               # Create / update / read a group
identity/group/id/<id>       # Read a group by ID
identity/group-alias         # Create a group alias
identity/group-alias/id/<id> # Read a group alias
identity/entity              # Create / read an entity

Internal vs External Groups (Comparison Table)

The main difference is where membership is managed. Internal groups hold members directly in Vault; external groups resolve membership from external information (such as an IdP) through a group-alias. Both group types can have policies attached, and at evaluation time the union of those policies is reflected on the token.

If you want to reuse existing IdP groups as-is, create external groups and attach group-aliases. If you want to build fine-grained subsets inside Vault, use internal groups and nest them. That is the basic rule of thumb.

• Exam tip: external groups do not manipulate member_entity_ids directly.
• Exam tip: a group-alias is uniquely resolved by three fields: name, mount_accessor, and canonical_id (the group ID).

Minimum creation command examples

# Internal group
vault write identity/group name=app-dev type=internal policies=kv-read

# External group (foundation for importing the IdP "engineers" group)
vault write identity/group name=oidc-engineers type=external policies=kv-read

Creation and Alias Binding Procedure (CLI / API)

In practice, first create the group itself (internal or external) and attach the required policies. For an external group, retrieve the auth method's mount_accessor, then create a group-alias using the IdP-side group name and the Vault group ID (canonical_id).

For internal groups you can directly add Entities or child groups as needed. External groups do not hold members directly; membership is resolved at login time from the group-alias and the IdP's claims.

• Retrieve the auth method's mount_accessor with vault auth list -format=json.
• Make sure the group-alias name (IdP group name), mount_accessor, and canonical_id (Vault group ID) all match.
• Policies can be attached to external groups too (a valid attachment point for permissions).
• Internal groups can compose permissions via nesting (member_group_ids).
• Make updates at the group level wherever possible, and minimize direct policy attachment to Entities.

Concrete examples of internal / external groups and group-alias

# 1) Create an internal group and attach policies
vault write identity/group \
  name=app-dev \
  type=internal \
  policies=kv-read,transit-sign

# 2) Add an existing Entity to the internal group (example: entity_id=1111-2222-3333)
vault write identity/group/id/<GROUP_ID_OF_app-dev> \
  member_entity_ids=1111-2222-3333

# 3) Create an external group (attach policies here)
vault write identity/group \
  name=oidc-engineers \
  type=external \
  policies=kv-read

# 4) Retrieve the mount_accessor (OIDC shown)
vault auth list -format=json | jq -r '."oidc/".accessor'
# Example output: auth_oidc_AbCdEf

# 5) Create the group-alias (binds the IdP-side group "engineers" to the Vault group)
vault write identity/group-alias \
  name=engineers \
  mount_accessor=auth_oidc_AbCdEf \
  canonical_id=<GROUP_ID_OF_oidc-engineers>

# 6) Equivalent alias creation via the HTTP API
curl -sS --header "X-Vault-Token: $VAULT_TOKEN" \
  --request POST \
  --data '{"name":"engineers","mount_accessor":"auth_oidc_AbCdEf","canonical_id":"<GROUP_ID>"}' \
  $VAULT_ADDR/v1/identity/group-alias

Login-Time Evaluation and Policy Inheritance (Flow Diagram)

When a user logs in via OIDC, LDAP, GitHub, etc., Vault resolves the Entity and reflects the union of policies — those attached to the Entity itself and those attached to the groups (internal, external, and nested) it belongs to — onto the resulting token.

Membership in external groups is determined by the group-alias and the auth method's claims (for example the OIDC groups claim), and is resolved fresh on every login. Internal groups are always in effect based on the Vault-side configuration.

• Group policies are unioned (note that deny takes precedence in the ACL).
• Nesting (member_group_ids) is expanded recursively.
• Reissuing the token or re-logging in reflects the latest external group membership.

Verifying the effective policies

# Policies attached to the current token
vault token lookup | jq -r .data.policies[]

# Cross-check an Entity against its groups (when the Entity ID is known)
vault read identity/entity/id/<ENTITY_ID> | sed -n '1,200p'

# Check permissions for a path against the current token
vault write sys/capabilities-self path=secret/data/app

Operational Best Practices and Pitfalls

The cardinal rule is: never edit external group members directly. Manage membership on the IdP side, and on the Vault side focus on the group-alias and policy attachment. If you need nesting, make the parent an internal group and pull the external group in as a child.

If you re-enable an auth method or change its mount, the mount_accessor changes and existing group-aliases will no longer match. Plan migrations so that you add and switch over to an alias that references the new accessor.

• Attach policies to groups whenever possible; keep direct attachment to Entities as an exception.
• When an external group name changes, follow up by updating (or creating a new) alias name.
• Explicitly review the OIDC groups_claim and the LDAP group search configuration to verify the expected group names appear in the claims.
• Keep nesting simple. Deep nesting makes troubleshooting hard.
• Validate changes in a staging environment with token lookup and capabilities-self before rolling out to production.

Maintenance command examples

# List / read existing groups
vault list identity/group/id
vault read identity/group/id/<GROUP_ID>

# Update a group's policies
vault write identity/group/id/<GROUP_ID> policies=kv-read,sys-audit

# List / read group aliases
vault list identity/group-alias/id
vault read identity/group-alias/id/<ALIAS_ID>

Troubleshooting and Migration Notes

If external-group-derived permissions are not attached after login, first verify that the group-alias name and mount_accessor are correct, and that the expected group name is present in the IdP claims. For OIDC, the role's groups_claim setting is the key.

When the accessor changes due to recreating an auth method or changing its path, existing group-aliases stop matching. Recreate or update the alias with the new accessor. During migration, you can mitigate impact by temporarily running both old and new aliases in parallel.

For LDAP, the group names retrieved and how nesting is resolved depend on server settings and search filters. First reconcile the configuration under ldap/ with actual query results, and verify that the group name reaching Vault matches the alias name.

• Check order: auth configuration -> mount_accessor -> IdP claims -> group-alias -> group policies.
• Use capabilities-self together with token lookup to isolate problems.
• Path or role-name changes have wide impact. Prepare exports and a rollback procedure in advance.

Verification commands

# Check auth methods and their accessors
vault auth list
vault auth list -format=json | jq

# Inspect a group-alias in detail (name, mount_accessor, canonical_id)
vault read identity/group-alias/id/<ALIAS_ID>

# Inspect the groups_claim configuration on an OIDC role
vault read auth/oidc/role/<ROLE_NAME>

Check Your Understanding

Frequently Asked Questions