Fix different-case entity alias duplicates

Fix duplicate identities for entity aliases due to case differences.

You must review different-case entity alias duplicates before enabling forced identity deduplication due to the potential security risk of incorrectly merging distinct aliases.

Why duplicates happen

Historical bugs in Vault allowed authN mounts to create duplicate entries of the same entity alias if the aliases used difference cases. For example, if an external LDAP system returns unnormalized usernames or changes the normalization scheme over time. By default, Vault uses case-insensitive matching for the usernames and considers username and uSeRnAmE to be the same alias. But, past bugs have left some users with different-case duplicates in storage.

To avoid the security impact of incorrectly merging identities that do not represent the same user, Vault tries to honor past behavior by switching the identity engine to use case-sensitive matching mode. But case-sensitive matching is poorly supported, deviates from the foundational security assumptions Vault makes, and can lead to unexpected behavior.

Example server log

The Vault system log provides warnings about duplicate aliases, including:

• the alias string
• the associated mount path (mount accessor)
• the alias ID (id)
• the ID for the entity linked to the alias (canonical_id)

[WARN]  identity: 2 different-case entity alias duplicates found (potential security risk)
[WARN]  identity: entity-alias "alias-case" with mount accessor "auth_userpass_34aca7ec" duplicates 1 others: id=df3568a4-3b65-4104-9481-1129ecbed72f canonical_id=5f013d99-a6c7-9a00-6ad5-4ad724b14f60 force_deduplication="would merge into entity 7da76b0d-fe9b-a125-3362-2a8ff055dcf8"
[WARN]  identity: entity-alias "alias-cAsE" with mount accessor "auth_userpass_34aca7ec" duplicates 1 others: id=2992253b-1e99-4e47-b6f9-afb0c7cedf7a canonical_id=7da76b0d-fe9b-a125-3362-2a8ff055dcf8 force_deduplication="would merge others into this entity"
[WARN]  identity: entity-alias "alias-case" with mount accessor "auth_userpass_a555989a" duplicates 1 others: id=0e4bd46e-a868-4dd4-a34a-cb73f097e3a5 canonical_id=1ce06951-e2fd-0923-8ae0-a0e2c6c2378b force_deduplication="would merge into entity 37f41fcf-5e15-f13f-248d-9fa8405b1ecd"
[WARN]  identity: entity-alias "alias-cAsE" with mount accessor "auth_userpass_a555989a" duplicates 1 others: id=6cafe546-665c-4bd0-a4fd-5e699ba413c1 canonical_id=37f41fcf-5e15-f13f-248d-9fa8405b1ecd force_deduplication="would merge others into this entity"
[WARN]  identity: end of different-case entity-alias duplicates

When reviewing system logs for duplicate resolution, always consider the authN mount and namespace when grouping potential duplicates. For example, despite having identical, case-insensitive names in the example logs, the four aliases represent two distinct identities because they come from different authN mounts:

• alias-case and alias-cAsE are duplicates in the mount auth_userpass_34aca7ec and will merge under the alias with canonical ID 7da76b0d-fe9b-a125-3362-2a8ff055dcf8 during deduplication.
• alias-case and alias-cAsE are duplicates in the mount auth_userpass_a555989a and will merge with the alias with canonical ID 37f41fcf-5e15-f13f-248d-9fa8405b1ecd during deduplication.

To resolve different-case duplicates, you must determine if the case difference is a mergeable duplicate or unmergeable duplicate:

• For mergeable duplicates, the case difference is unintentional and the duplicate entries represent the same logical entity. You can ignore mergeable duplicates and let Vault force-merge them for you to establish and enforce default identity matching behavior.

• For unmergeable duplicates, the case difference is deliberate and the source identity provider intended to distinguish between different entities using case. For example, Alice and alice are different entities that correspond to different humans with distinct permission sets. You must resolve unmergeable duplicates before activating the deduplication flag.

Case 1: Resolving mergeable duplicates

Vault will force-merge duplicates once you enable forced identity deduplication with the force-identity-deduplication flag. Vault also merges any policies attached to the duplicates so the final entry has the union of all permissions granted to the duplicates.

We recommend confirming the expected merge behavior before enabling deduplication by reviewing the force_deduplication label in the log line to:

1. confirm the identified duplicates are all mergeable.
2. confirm permissions granted by the unified policy are appropriate for the identity.

After deduplication, users can continue to log in using any case combination of their username, but those logins will map to a single entity gated by the same policies per the expected, default Vault behavior.

Case 2: Resolving unmergeable duplicates

When different-case variations of an alias name actually represent different logical users or entities in an external system, investigate each alias before resolving duplicates. You must resolve the duplicates on each mount before enabling forced identity deduplication.

If you confirm you need to keep the duplicated aliases, you will need to reconfigure the authN mount or external service to stop creating case-sensitive aliases. For example, if the authN plugin allows it, you could update the plugin configuration to append unique IDs to alias names to differentiate between similar usernames.

Regardless of how you choose to address unmergeable duplicates, be mindful of how the modified behavior may disrupt users as you roll out the change.

If you can confirm you do not need the duplicated alias, or the entire auth mount, delete all but one of the entity aliases on each mount using the ID noted in the log line with id=.

$ vault delete /identity/entity-alias/id/<id>

$ vault delete /identity/entity-alias/id/df3568a4-3b65-4104-9481-1129ecbed72f

Success! Data deleted (if it existed) at: identity/entity-alias/id/df3568a4-3b65-4104-9481-1129ecbed72f

$ curl                                      \
   --request DELETE                         \
   --header "X-Vault-Token: ${VAULT_TOKEN}" \
   ${VAULT_ADDR}/v1/identity/entity-alias/id/<id>

$ curl                                      \
   --request DELETE                         \
   --header "X-Vault-Token: ${VAULT_TOKEN}" \
   ${VAULT_ADDR}/v1/identity/entity-alias/id/df3568a4-3b65-4104-9481-1129ecbed72f | jq

After you resolve the duplicates by deleting them or reconfiguring the relevant services:

1. If the node is a standby, restart the node manually.

2. Recheck the system logs for the current node to confirm the duplicates no longer appear in the log during unseal.

Next steps

Once you confirm any remaining duplicates can be force-merged safely, you can enable forced identity deduplication.