> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/administration-guide/identities/resolve-orphan-accounts.md).

# Resolve orphan accounts

Triage the orphan accounts a reconciliation found on a managed system — link them to a user, convert them to a new user, or delete them deliberately.

## What this is, and when you need it

An **orphan account** — an account that exists on a managed system with no OpenIAM user behind it — is what many control frameworks call a **rogue account** or an unowned account. OpenIAM's own term is orphan, and that is the word every screen and audit action on this page uses.

An **orphan** is an account found on a managed system that corresponds to no identity in OpenIAM. Reconciliation and synchronization create them; you resolve them, one decision at a time — this person already exists, this person does not, this is somebody's second account, this should not exist at all.

Orphans have no database table. They live only in the `orphan` OpenSearch index, which changes how you diagnose everything on this page.

## At a glance

|                          |                                                                                                   |
| ------------------------ | ------------------------------------------------------------------------------------------------- |
| **You will end up with** | Every orphan on the managed system linked, converted, or deliberately deleted                     |
| **Where**                | **User Admin → Orphan Management**, `/webconsole/orphan-management`                               |
| **You need first**       | The `ORPHAN_MANAGEMENT` menu grant, and a managed system that has been reconciled or synchronized |
| **Takes**                | Minutes for a handful; a large estate is a scheduled piece of work                                |
| **Reversible**           | Partly — a link can be undone, but a delete with the target option is not reversible from OpenIAM |

## Triage the orphans

A reconciliation against `<MANAGED_SYSTEM_ID>` has reported orphans. Work them in this order.

{% stepper %}
{% step %}

### List them, scoped to the one managed system

Open `/webconsole/orphan-management`. The screen is a three-step wizard — **Select** (find orphan accounts), **Link** (map to an identity), **Review** (confirm changes) — and step 1 is a grid with a filter row above it.

Set the managed-system picker in the filter row to your managed system before you do anything else. The other filters are **Identity**, **Name**, **Email Address**, **Employee ID** and **Date**, and the grid columns are **Orphan Managed System**, **Orphan Identity**, **Existing Identity**, **First Name**, **Last Name**, **Email Address**, **Employee ID** and **Created Date**.

{% hint style="warning" %}
**An unfiltered orphan list is every orphan in the index, not an empty one.** Unlike user search, which returns nothing for a blank form, the orphan screen lists the whole index when no filter is set. On a large estate that is a very long grid that looks as though it matched something. If a count surprises you, check the managed-system picker is actually set before you conclude the reconciliation found more than you expected.
{% endhint %}
{% endstep %}

{% step %}

### Discard the ones showing `N/A` for their managed system

A managed system name of `N/A` means OpenIAM could not resolve the managed system the orphan points at — usually the residue of a managed system that has been deleted. Delete these with the target option **off**: there is nothing to delete on a system OpenIAM cannot identify.
{% endstep %}

{% step %}

### Link the ones that match a person you already have

Tick the orphans in step 1's grid, move to step 2 and pick the user — **Select a user...** — then check the mapping in step 3, **Review the identity-to-orphan mapping below, then confirm**, and press **Update Identities**.

**Every orphan you tick is linked to the one user you pick.** That is the shape of the screen: one user per pass. If you have ticked orphans belonging to two different people, clear the selection and do them in two passes — the screen will not stop you, and everything you ticked goes to the user selected in step 2.

{% hint style="danger" %}
**Linking replaces an existing identity rather than adding to it.** If the user has no identity on that managed system, the orphan's identity is added — the case you almost always intend. If the user *already* has one, its login value is **overwritten** with the orphan's. Nothing warns you beyond the confirmation text, and the value you overwrote is not recorded anywhere you can read it back. Write the previous value down before you link.

Linking also saves asynchronously: **Update Identities** reports success once the change is queued, not once the identity is stored. Verify by reopening the user's identities, not by reading the message on screen.
{% endhint %}

Linking cleans up after itself: for each orphan it removes any duplicates with the same identity on the same managed system — the residue of several reconciliation runs.
{% endstep %}

{% step %}

### Convert the ones that are a person OpenIAM does not know

Select **one** orphan — the screen refuses more than one with `Please select a single orphan account to continue` — and press **Create New User from Orphan**. A dialog of the same name opens, pre-filled from the orphan.

**Set the user type before you save.** Leave it empty and the user is created with no user type at all, and page templates keyed on user type will not apply to them. Nothing warns you.

What carries across to the new user: the first name, last name and employee ID; the orphan's identity on its managed system, as an active identity; the email address, when present, as a primary email; and a user attribute named `Creation source` holding `Orphan record`, so orphan-derived users stay identifiable by attribute rather than by inference.

{% hint style="info" %}
Nothing in this flow deletes the orphan document. The user is created and the orphan remains listed until the next reconciliation no longer reports it, or until you delete it. Expect the orphan to still be there immediately afterwards — that is not a failure.
{% endhint %}
{% endstep %}

{% step %}

### Model the second accounts as related accounts, not as second identities

An orphan that is a privileged second account for somebody you already have should become its own user record plus a related-account link of type `PRIVILEGED_ACCOUNT` — not a second identity crammed onto the person's record, which is exactly what produces the "User already has an identity for this managed system" failure. See [Manage related accounts](/administration-guide/identities/related-accounts.md).
{% endstep %}

{% step %}

### Delete what is left, deliberately

Only once you have decided, per orphan, whether the account should exist on the target at all.

{% hint style="danger" %}
**Deleting from the managed system is not reversible from OpenIAM.** **Delete selected from managed system** sends a delete straight to the connector, bypassing the entitlement model entirely, because there is no OpenIAM user to reason about. There is no request to cancel, no end-dated grant to restore, and no OpenIAM record of what the account contained.

**Delete selected from IDM** removes only OpenIAM's knowledge of the account. The account stays on the managed system and the next reconciliation reports it again — so an orphan that keeps coming back is a correct outcome of this choice, not a failure. It is right when you have decided the account is legitimate and out of scope; it is wrong when you meant to remove the account.

The `REMOVE_ORPHAN` audit event is the only place your choice is preserved: its info line reads "Deleting orphan: … including delete in target system? -yes" or "-no". Read it after the first deletion you perform, before you do forty.
{% endhint %}
{% endstep %}
{% endstepper %}

## Verification

| What you did                  | Evidence                                                                                                                                                                  |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Linked an orphan              | A `LINK_ORPHAN` parent event with an `UPDATE_PRINCIPAL` child per orphan; then the new identity on the user; then the orphan gone from the orphan screen                  |
| Created a user from an orphan | A `CREATE_NEW_USER_FROM_ORPHAN` event; the new user carries the attribute `Creation source` = `Orphan record`; the orphan is *still* listed until the next reconciliation |
| Deleted an orphan             | A `REMOVE_ORPHAN` event whose info line states whether the target delete was requested; then the account's absence — or presence — in the target                          |
| Unlinked an identity          | A `UNLINK_IDENTITY_TO_ORPHAN` event, the identity gone from the user, and a new orphan document                                                                           |

Reconciliation-generated orphans audit as `SYNCHRONIZATION_ORPHAN`, which is how you tell an orphan the product found from one you created by unlinking.

### The screen strings worth searching a ticket for

| Verbatim string                                                                              | When                                                                                                                  |
| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `Please select both orphan accounts and a user before proceeding`                            | **Update Identities** was pressed with only one side of the link selected                                             |
| `Are you sure you want to link the selected items? Existing identities will be overwritten.` | The link confirmation. That is the overwrite case above, stated on the button — read it as a warning, not boilerplate |
| `Logins were successfully updated or added to the user`                                      | The queue accepted the save. Not a confirmation that the identity is stored                                           |
| `Please select a single orphan account to continue`                                          | **Create New User from Orphan** was pressed with more than one orphan selected                                        |

## When it goes wrong

| Symptom                                                                                                        | Cause                                                                                                                             | Fix                                                                                                      |
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| The orphan screen is empty after a reconciliation that reported orphans                                        | The `orphan` index is not populated. Orphans have no table, so there is no fallback to query                                      | [Rebuild a search index](/administration-guide/operations/rebuild-a-search-index.md) for `orphan`        |
| The orphan list is far longer than the reconciliation reported                                                 | No managed-system filter is set, and an unfiltered list is the whole index                                                        | Set the managed-system picker in the filter row                                                          |
| An orphan shows managed system `N/A`                                                                           | The managed system it points at no longer exists                                                                                  | Delete it without the target option                                                                      |
| Link fails with "Login already exists"                                                                         | A **different** user already holds that login on that managed system. Two users cannot share one identity                         | Find the other holder and decide which record is correct before linking                                  |
| Link fails with "User already has an identity for this managed system"                                         | The user you are linking to already has one there                                                                                 | Either correct the existing identity, or model the orphan as a separate user with a related-account link |
| Link reported success but the identity is not on the user                                                      | The save is queued, not immediate                                                                                                 | Reopen the user's identities. If it is still absent, check the message bus                               |
| Linking overwrote a correct identity                                                                           | Linking replaces whenever the user already has an identity on that managed system                                                 | Restore the login value by editing the identity; prefer a related account for second accounts            |
| Linking *any* orphan to one particular user throws before doing anything                                       | That user has no identity on the default managed system, and linking reads it while building its audit trail                      | Restore that user's OpenIAM identity first — see below                                                   |
| A user created from an orphan has no user type                                                                 | The user type was left empty in the **Create New User from Orphan** dialog                                                        | Set the user type on the record, and set it in the dialog next time                                      |
| Deleted orphans reappear at the next reconciliation                                                            | Deleted without the target option; the account still exists on the managed system                                                 | Either delete it there, or exclude it from the reconciliation scope                                      |
| `Cannot invoke "…LoginLockMarkerEnum.toString()" because the return value of "…Login.getLockMarker()" is null` | See [When creating a user from an orphan fails on the lock marker](#when-creating-a-user-from-an-orphan-fails-on-the-lock-marker) | Create the user first, then link the orphan                                                              |
| **Update Identities** reports `Please select both orphan accounts and a user before proceeding`                | Only one side of the link is selected                                                                                             | Tick at least one orphan in step 1 **and** pick a user in step 2                                         |

## Never unlink the OpenIAM identity

Unlinking turns an identity back into an orphan. It is the same operation whichever identity you point it at, **including the OpenIAM identity itself**, and the product does not stop you: all that is checked is that the identity exists.

{% hint style="danger" %}
**The OpenIAM identity is the identity every other account is correlated through. Do not unlink it.** Remove it and the user has no principal to sign in with and provisioning has nothing to correlate against.

Recovery is worse than it looks. Linking reads the user's primary principal on the default managed system while setting up its audit trail, before doing any work, and without checking that one exists. A user whose OpenIAM identity has been unlinked has no such principal, so linking **any** orphan back onto that user fails before it reaches the link logic — including the orphan that *is* their unlinked OpenIAM identity. Restore the identity from the user's identities screen first, then use **Update Identities** for the managed-system orphans.
{% endhint %}

## When creating a user from an orphan fails on the lock marker

This is the failure to expect from **Create New User from Orphan**, and the audit log records it verbatim:

{% code overflow="wrap" %}

```
EXCEPTION: Cannot invoke "org.openiam.idm.srvc.auth.dto.LoginLockMarkerEnum.toString()" because the return value of "org.openiam.dto.Login.getLockMarker()" is null
```

{% endcode %}

It is not a data problem on the orphan and not a permissions problem. On this one path the identity is built without a lock marker, and the change comparison that runs on every user save then reads that missing value and fails. The comparison tolerates a missing *previous* value and not a missing new one, which is why this happens only when creating a user from an orphan and never when you link one.

**There is nothing you can configure to avoid it**, and nothing on any screen would have warned you — the exception text above in the audit log is the only observable.

{% hint style="warning" %}
**This is not a schema problem, and altering the column does not fix it.** `LOGIN.LOCK_MARKER` has shipped as `VARCHAR(20) DEFAULT 'NOT_LOCKED' NOT NULL`, identically on MySQL, SQL Server, PostgreSQL and Oracle, since 4.2.1.5. The null never reaches the database; the comparison fails first. Field guidance for this symptom sometimes suggests an `ALTER TABLE … NOT NULL`; on a schema built by the shipped migrations there is nothing to alter.

**Break-glass check, read-only.** If the schema was ever built or patched by hand, the column's default is worth confirming — but treat it as a separate question from this failure, not as its cause:

{% code overflow="wrap" %}

```sql
SELECT COLUMN_NAME, IS_NULLABLE, COLUMN_DEFAULT
  FROM INFORMATION_SCHEMA.COLUMNS
 WHERE TABLE_NAME = 'LOGIN' AND COLUMN_NAME = 'LOCK_MARKER';
```

{% endcode %}

This reads the schema catalogue directly rather than anything the Webconsole exposes. It is read-only, so it risks nothing, and it will **not** fix the failure whatever it returns. Do not add a `NOT NULL` constraint in response to this symptom: the value is rejected in the application before any statement is issued, so the constraint changes nothing and you have made an unsupported schema change for no effect.

**The route that works** is to create the user first from **User Admin → Create New User**, then resolve the orphan onto that user with **Update Identities**. That path builds the identity with the `NOT_LOCKED` default intact, so the comparison has something to read. Raise the **Create New User from Orphan** failure with support rather than working around it in the database.
{% endhint %}

## When the orphan list and the reconciliation disagree

Because orphans have no table, **there is no SQL cleanup for orphans** — a script that deletes rows cannot touch a document index — and the only wholesale operation on that index is a rebuild.

{% hint style="warning" %}
A rebuild of the orphan index is not a targeted delete and it is not scoped to one managed system or to the orphans you selected. It is the blunt instrument, it runs against a shared index, and it competes with live search while it runs.

For anything you can enumerate, delete the specific orphans without the target option instead: that is scoped to the documents you send, it is audited per orphan as `REMOVE_ORPHAN`, and it touches nothing else in the index. Reach for the rebuild only when the index and the reconciliation output disagree and you have exhausted the scoped route — then follow [Rebuild a search index](/administration-guide/operations/rebuild-a-search-index.md) and pick the `orphan` entity.
{% endhint %}

The rebuild reports `Entity reindex initiated. This operation may take several minutes if there are many records.` on success and `Unable to reindex the selected entity` on failure. **The success text is an acknowledgement, not a completion.** The way you confirm a rebuild finished is that the orphan list matches the reconciliation output again, not that the message appeared.

Older releases named the orphan document type differently, so a runbook or support thread may quote a name that no longer appears in the list. Take the entry the screen offers; they refer to the same index.

## Roll it back

**A link** — reversible in structure, not in content. Unlinking returns the identity to the orphan index, audited `UNLINK_IDENTITY_TO_ORPHAN`, but an overwritten login value is not recovered and is recorded nowhere.

**A user created from an orphan** — remove the user as you would any other. The orphan document is still there.

**An orphan deleted from IDM only** — the next reconciliation reports the account again.

**An orphan deleted from the managed system** — **not** reversible from OpenIAM. Restore from that system's own backup.

## Related

* [Configure reconciliation](/administration-guide/lifecycle/configure-reconciliation.md) — what creates orphans in the first place
* [Manage related accounts](/administration-guide/identities/related-accounts.md) — the right model for a second account
* [Rebuild a search index](/administration-guide/operations/rebuild-a-search-index.md) — when the orphan screen and the reconciliation disagree

*Applies to OpenIAM 2026.8.1. Last reviewed 7 August 2026.*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openiam.com/administration-guide/identities/resolve-orphan-accounts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.