> 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/find-a-user.md).

# Find a user

Search for a user in the Webconsole, diagnose the case where the user exists but search cannot find them, and change which columns and criteria the search screen offers.

## What this is, and when you need it

Almost every administrative task starts by finding one person. The one thing to know before you start is that user search does **not** read the user table — it reads the `users` OpenSearch index. That single fact explains most "the user is there but search returns nothing" reports, and it is the first thing to check when a search disappoints you.

## At a glance

|                          |                                                                                         |
| ------------------------ | --------------------------------------------------------------------------------------- |
| **You will end up with** | The user's record open, or a definite answer about why search cannot reach them         |
| **Where**                | **User Admin → User Search**, `/webconsole/users`                                       |
| **You need first**       | The `USER_ROOT_MENU` grant, and at least one search value — there is no list-all        |
| **Takes**                | Under a minute, unless you have to rebuild an index                                     |
| **Reversible**           | Yes — searching changes nothing. Changing the search configuration is a property change |

## Search for a user

{% stepper %}
{% step %}

### Open the user search screen

Go to **User Admin → User Search**, or `/webconsole/users`. `/webconsole/users/legacy` is the pre-4.2.2 screen and is deprecated since 4.2.2 — use it only to compare behaviour, never as your normal screen.
{% endstep %}

{% step %}

### Supply at least one criterion

**An empty form returns nothing, not everything.** OpenIAM short-circuits an empty search model and returns an empty response without querying anything, so there is no "list all users" by design. Type a name, an email address, an employee ID or a principal.
{% endstep %}

{% step %}

### Read the results, knowing how they are ordered

Whatever you sorted by orders the query; the page you get back is then re-sorted by name within itself. So the first page is the right set of users in name order, not in your sort order.

The displayed **name** is composed, not stored: `org.openiam.ui.user.fullname.compose.rule` ships `firstName,lastName`, and OpenIAM builds the name column from those fields in that order.
{% endstep %}

{% step %}

### If the person is not there, decide whether it is the data or the index

Open the person by another route — from their manager's direct reports, from an audit event, from a role's membership list, or by id. If the record opens and is correct, the data is fine and the index is stale. Go to [The user exists but search cannot find them](#the-user-exists-but-search-cannot-find-them).
{% endstep %}
{% endstepper %}

## The user exists but search cannot find them

This is the commonest search failure and it has a clean diagnosis.

{% hint style="warning" %}
**Correct on its own screen, absent from search, means the index — not the data.** User search is served from the `users` OpenSearch index. A user created outside the normal path, or created while the index was unavailable, has a perfectly good record and no document to match. Nothing you change on the user record will fix that; nothing is wrong with the user record.

The repair is to rebuild the one index: [Rebuild a search index](/administration-guide/operations/rebuild-a-search-index.md), entity `users` — and `userattributes` as well if you search on user attributes.

The opposite case matters too. If opening the record directly *also* shows the wrong value, the data is wrong and a rebuild will faithfully re-index it. Check the record first, every time.
{% endhint %}

Two narrower reasons a user can be missing from a search that is otherwise working:

**Under `/selfservice` only, prohibited statuses are filtered out.** `org.openiam.ui.webconsole.prohibited.user.status` removes users in those statuses from SelfService search when it is non-empty. Its shipped value is conditional on your upgrade path, so read it at **Administration → System Configuration**, category `System`, rather than assuming. In the Webconsole, terminated users remain findable whatever the list says. Searching for the same person from both surfaces tells you at once which case you are in.

**Under `/selfservice` only, organization scope may apply.** With `org.openiam.selfservice.organization.search.enabled` on, a requester who is not a super security administrator sees only their own organizations — and a requester with no organization affiliation at all sees nobody. See [Scope a delegated administrator](/administration-guide/identities/delegated-administration.md).

## Change what the search screen shows

Both of the settings below are properties at **Administration → System Configuration**, category `System`. They are read from a cache that refreshes on the property sweep interval — five minutes on shipped configuration — so give a change a sweep before you conclude it did not take.

{% stepper %}
{% step %}

### Set the result columns

`org.openiam.ui.user.search.result.columns`, label **Columns Shown in User Search Results**, type `OrderableValue`. It ships:

{% code overflow="wrap" %}

```
name,phone,email,userStatus,accountStatus
```

{% endcode %}

Order in the property is order on screen, and whitespace is **not** trimmed. Every accepted column name, and the two columns that behave differently from the rest, are in [User search configuration](/administration-guide/reference/user-search-configuration.md).
{% endstep %}

{% step %}

### Pre-expand optional search criteria

`org.openiam.ui.user.search.form.additional.criteria`, label **Additional User Search Criteria**, type `MultiSelect`. It ships **empty**, and empty is valid — out of the box no optional criterion is pre-expanded.

This property does not decide which criteria exist; it names the ones already expanded when the form loads.

{% hint style="danger" %}
More than one search widget consumes this property, and each validates it against **its own vocabulary**, so a value that works on one screen is silently dropped on another with no error. Only `userStatus`, `accountStatus`, `employeeType`, `jobCode`, `maidenName`, `attribute` and `resourceId` are safe on both of the main widgets. Every vocabulary is in [User search configuration](/administration-guide/reference/user-search-configuration.md).
{% endhint %}
{% endstep %}

{% step %}

### Reload the search screen and read the result back off it

Reload `/webconsole/users` and compare the grid headers with the order you set: the columns are rendered in the property's order, so the grid *is* the readback. Then check that the criteria you named are already expanded on the form rather than folded away.

Neither change is instant. Both are read from a cached copy of the configuration, so a screen that still shows the old columns a few seconds after you saved is usually a change that has not swept yet. Wait out one sweep interval before you change anything else.

One criterion behaves differently from the rest. **The Organization criterion is hidden exactly when organization scoping is restricting the search** — it would have narrowed nothing, so OpenIAM leaves it off the form. If you named it and it never appears, check whether scoping applies to the account you are signed in as, before you go looking at the property. See [Scope a delegated administrator](/administration-guide/identities/delegated-administration.md).
{% endstep %}
{% endstepper %}

### Worked example: a help desk that triages by employee ID

The help desk needs the target identity visible alongside the employee ID, with status and job code pre-expanded on the form. Two property changes:

{% code overflow="wrap" %}

```
org.openiam.ui.user.search.result.columns            = name,principal,employeeId,email,userStatus,accountStatus
org.openiam.ui.user.search.form.additional.criteria  = userStatus,jobCode
```

{% endcode %}

Both criteria values are inside the safe seven, and `principal` is what makes OpenIAM load each row's default identity.

## Verification

* **Finding a user.** The record opens from the search result. If you were diagnosing a stale index, the previously missing user now appears in the same search that returned nothing.
* **Column configuration.** The grid headers on `/webconsole/users` are your columns, in your order. A header you recognise above an empty column is a name the grid did not resolve — check the spelling.
* **Criteria configuration.** The criteria you named are already expanded when the search form loads, rather than folded away behind the optional section.

## When it goes wrong

| Symptom                                                                | Cause                                                                                                                 | Fix                                                                                                                                                |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Search returns nothing for a user whose record opens correctly         | The `users` index is stale or was rebuilt without this record                                                         | [Rebuild a search index](/administration-guide/operations/rebuild-a-search-index.md) for `users`                                                   |
| Search returns nothing for a blank form                                | An empty search model returns an empty response without querying                                                      | Supply at least one criterion; there is no list-all                                                                                                |
| A terminated user is findable in the Webconsole but not in SelfService | `org.openiam.ui.webconsole.prohibited.user.status` includes `TERMINATED`, and it is applied only under `/selfservice` | Expected. Search from the Webconsole                                                                                                               |
| A SelfService user finds nobody at all                                 | Organization scoping is on and that requester has no organization affiliation                                         | Give them an affiliation, or turn scoping off. See [Scope a delegated administrator](/administration-guide/identities/delegated-administration.md) |
| A configured column is blank on every row                              | The name is misspelled or padded with a space                                                                         | Check it against [User search configuration](/administration-guide/reference/user-search-configuration.md)                                         |
| An optional criterion you added never appears                          | The value is not in the vocabulary the rendering widget filters against                                               | Use the seven-value intersection                                                                                                                   |
| The grid does not match the property you just saved                    | The search configuration is cached and the property is re-read on the sweep interval                                  | Wait out one sweep and reload the screen before changing anything else                                                                             |
| Results are not in the order you sorted by                             | The returned page is re-sorted by name within itself after the query orders it                                        | Expected. Narrow the search rather than paging for order                                                                                           |

## Related

* [Create a user](/administration-guide/identities/create-a-user.md) — the two creation routes, and why a brand new user may not be in search yet
* [Rebuild a search index](/administration-guide/operations/rebuild-a-search-index.md) — the repair for a user who exists but cannot be found
* [User search configuration](/administration-guide/reference/user-search-configuration.md) — every column name and criterion value the two properties accept

*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/find-a-user.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.