---
layout: docs
page_title: Resolve different-case entity alias duplicates
description: >-
  Fix duplicate identities for entity aliases due to case differences.
---

# 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**.


<Tip title="Assumptions">

- You are running Vault 1.19 or later.
- You have [deduplication **merge** targets in your system logs](/vault/docs/upgrading/identity-deduplication).
- You have admin permission on the relevant Vault server or cluster.

</Tip>


## 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`)

<CodeBlockConfig hideClipboard>

```text
[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
```

</CodeBlockConfig>

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.
1. 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

<Warning>

We strongly recommend resolving duplicates and moving away from case-sensitive
usernames as soon as possible to restore the security model supported by Vault.

Vault does not officially support case-sensitive names because it carries
significant security risks. And unresolved duplicates could merge at any time
due to unrelated changes in storage such as when deleting related entities or
groups.

</Warning>

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.

<Note>

We are not aware of specific integrations where changing mount or external
service behaviors is necessary and expect those situations to be rare. If you
determine your deployment requires changes to authN mounts or external services,
we encourage Vault Enterprise customers to work with HashiCorp support staff to
determine the best strategy and implementation.

</Note>

**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=`.

<Tabs>

<Tab heading="CLI" group="cli">

Use `vault delete` with the `/identity/entity-alias/id/{id}` path to delete the
duplicate identity:

```shell-session
$ vault delete /identity/entity-alias/id/<id>
```

For example, if one of the duplicate entity log entries includes
`id=df3568a4-3b65-4104-9481-1129ecbed72f`:

<CodeBlockConfig hideClipboard="true">

```shell-session
$ 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
```

</CodeBlockConfig>

</Tab>

<Tab heading="API" group="api">

Call the [`/identity/entity-alias/id/{id}`](/vault/api-docs/secret/identity/entity-alias#delete-entity-alias-by-id)
endpoint to delete the duplicate entry:

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

For example, if one of the duplicate entity log entries includes
`id=df3568a4-3b65-4104-9481-1129ecbed72f`:

<CodeBlockConfig hideClipboard="true">

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

</CodeBlockConfig>

</Tab>

</Tabs>

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

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

1. 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](/vault/docs/upgrading/deduplication#dedupe-flag).
