> 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/platform/system-configuration.md).

# System configuration

Find the right System configuration tab, and change a shipped property without breaking a working system.

## What this is, and when you need it

**Administration → System Configuration** at `/webconsole/propertyValues` is a single editor over one table: `PROPERTY_FILE_VALUES`. Each tab is one distinct value of that table's `CATEGORY` column, and each row on a tab is one `PROPERTY_ID`. There is nothing behind a tab that is specific to it: every tab is the same screen reading and writing the same table. The set of categories is fixed in the release — you cannot add a tab, and a property you invent will not appear on one.

There is nothing to learn per tab. You need the right tab, the exact key, its shipped default, and a change procedure that does not lock you out. Every key and default is in [System property reference](/administration-guide/reference/system-properties.md); this page gives you the procedure, the map of the tabs, and the shipped defaults that surprise people.

## At a glance

|                          |                                                                                                                                                                                                                  |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **You will end up with** | One related set of property values changed, read back from the stored row, and proved by a case that must work and a case that must be rejected                                                                  |
| **Where**                | **Administration → System Configuration** at `/webconsole/propertyValues`. One tab per `CATEGORY` value of `PROPERTY_FILE_VALUES`                                                                                |
| **You need first**       | The exact property key and its category, from [System properties](/administration-guide/reference/system-properties.md); the current value, copied into your change record; a test that proves the new behaviour |
| **Takes**                | 5 minutes to change, plus up to 5 minutes for other nodes to pick the value up                                                                                                                                   |
| **Reversible**           | Yes, if you captured the old value first. The screen has no undo and no history, so an uncaptured value is gone                                                                                                  |

## Before you begin

Most of these fields are comma-separated lists whose order matters, and **nothing in OpenIAM keeps a previous value**: there is no version history on a property row and the save is not reversible from the screen. Copy the current value into your change record before you type over it, not into memory.

## Change a property safely

This is the procedure for every tab. It appears once, here.

{% stepper %}
{% step %}

### Find the tab that owns the key

Look the key up in [System property reference](/administration-guide/reference/system-properties.md), which gives its category, type and shipped default, then open that tab. [The tabs](#the-tabs) below maps every category to what it governs and how many keys it holds. A key you cannot find in the reference does not exist as a `PROPERTY_FILE_VALUES` row, and no tab will show it — it is either a container-only setting or a key a later release removed.
{% endstep %}

{% step %}

### Capture the current value

Copy the existing value into the change record before you type over it — not into memory. Most of these fields are comma-separated lists whose order matters, and the screen has no undo.
{% endstep %}

{% step %}

### Change one related set, not one property

Some settings only make sense together: a status list and its counterpart, an OAuth flag and the entitlements it was hiding. Change the whole set, nothing more.
{% endstep %}

{% step %}

### Save once

**Save** writes every row on the tab, not just the one you touched, and is audited as `MODIFY_SYSTEM_PROPERTIES`. Other nodes refresh on their own timer — `org.openiam.property.value.threadsweep` is `300000` ms in the UI images, `30000` ms in the ESB — so another session can show the old value for five minutes.
{% endstep %}

{% step %}

### Reopen the tab and read the stored value back

Do not trust the form you submitted. Reload the tab and confirm the field contains what you intended, character for character — values are coerced to the row's `PROPERTY_TYPE`.
{% endstep %}

{% step %}

### Test one case that must work and one that must be rejected

A setting that only permits is untested. If you enabled OAuth authorization, confirm an entitled user gets a token *and* that an unentitled one is refused.
{% endstep %}
{% endstepper %}

## Verification

| Evidence                                                     | Meaning                                                                                                                                                                                                 |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A `MODIFY_SYSTEM_PROPERTIES` audit event                     | The save reached the back end. The submitted value set is stamped onto the event, which is the only record of what the value was before you changed it — provided you captured it                       |
| The tab reopened, showing your value character for character | The row stores what you intended. Values are coerced to the row's `PROPERTY_TYPE`, so what you typed and what was stored are not always the same string                                                 |
| One case that must work, and one that must be rejected       | The setting does what you think. A setting that only permits is untested                                                                                                                                |
| The behaviour on a *second* node, after five minutes         | The value reached the rest of the cluster. `org.openiam.property.value.threadsweep` is `300000` ms in the UI images and `30000` ms in the ESB; the Webconsole node you saved from refreshes immediately |

## When it goes wrong

| Symptom                                                                                      | Inspect                                                                                                                                 | Fix                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Save rejected: *Active and Inactive statuses cannot have the same values*                    | `org.openiam.ui.webconsole.active.user.status` against `...inactive.user.status`                                                        | The two sets must not overlap. The response code is `COULD_NOT_SAVE_STATUS_PROPERTIES`                                                                                                  |
| Save rejected: *Property '…' has a missing or invalid value*                                 | The value against the row's `PROPERTY_TYPE`, and whether the row allows an empty value                                                  | `PROPERTY_VALUE_INVALID` covers three back-end causes: a missing translation for a multilingual row, a required value left empty, and a value that will not coerce to the declared type |
| Save rejected: *Redirect URL is not valid. External resources cannot be used for redirects.* | The value you typed on the **Custom Redirect** tab                                                                                      | Every value on that tab is validated as a postback URL; an external destination is refused outright                                                                                     |
| The tab shows your value, the service behaves as before                                      | The deployment manifest for `OPENIAM_PROP_<underscored_key>`                                                                            | A container override wins over the row and is invisible from this screen. See [Where settings live](/administration-guide/start/where-settings-live.md)                                 |
| Another session still shows the old value                                                    | How long ago you saved                                                                                                                  | Other nodes refresh on `org.openiam.property.value.threadsweep`, up to five minutes in the UI images                                                                                    |
| The key you were told to set is not on any tab                                               | [Properties removed by a later migration](/administration-guide/reference/system-properties.md#properties-removed-by-a-later-migration) | Thirty keys were seeded by one release and deleted by a later one. The runbook predates your release                                                                                    |
| The Gateway tab's password field shows a mask and never your value                           | Nothing — this is deliberate                                                                                                            | Saving the Gateway tab writes the typed secret straight to the vault and blanks the property row                                                                                        |

## Roll it back

Paste the value you captured back into the field, save, and reopen the tab to confirm the stored row matches. Do not leave a half-applied set in place while you investigate: where two properties only make sense together — a status list and its counterpart, an OAuth flag and the entitlements it was hiding — restore both. If you did not capture the value, the `MODIFY_SYSTEM_PROPERTIES` audit event for the *previous* save carries whatever was submitted then; failing that, the shipped default in [System properties](/administration-guide/reference/system-properties.md) is all that is left.

## The tabs

**202** non-audit properties are spread over 14 categories. The 15th, `SystemAuditLog`, is a generated family of **502** retention keys — one per audit action — and belongs in [Audit actions and retention](/administration-guide/reference/audit-actions-and-retention.md), not here.

| Tab (screen label)             | `CATEGORY` value    | What it governs                                                                             | Count                                                                        |
| ------------------------------ | ------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| UI                             | `UI`                | SelfService page composition, CAPTCHA, branding, profile-edit Groovy hooks                  | [35](/administration-guide/reference/system-properties.md#ui)                |
| System                         | `System`            | Date formats, validation regexes, user-status sets, crypto algorithm, provisioning switches | [32](/administration-guide/reference/system-properties.md#system)            |
| Workflow                       | `Workflow`          | Approver-association scripts, default approver, termination and access expiry               | [32](/administration-guide/reference/system-properties.md#workflow)          |
| Gateway (SMTP)                 | `Gateway`           | The legacy single SMTP mail account; the tab label says deprecated                          | [16](/administration-guide/reference/system-properties.md#gateway)           |
| Password                       | `Password`          | Reset and unlock methods, OTP requirements, what the reset screen offers                    | [16](/administration-guide/reference/system-properties.md#password)          |
| Authentication                 | `Authentication`    | Sign-in routing, new-device/new-IP notification, FIDO relying party, SAML clock skew        | [15](/administration-guide/reference/system-properties.md#authentication)    |
| Directory Lookup               | `DirectoryLookup`   | Columns and sections the directory search and profile view render                           | [12](/administration-guide/reference/system-properties.md#directory-lookup)  |
| IDM                            | `IDM`               | Provisioning pre/post-processor and connector-response Groovy scripts                       | [9](/administration-guide/reference/system-properties.md#idm)                |
| User Entitlements              | `UserEntitlements`  | Cart validation, batch sync/recon scripts, resource types on entitlement screens            | [8](/administration-guide/reference/system-properties.md#user-entitlements)  |
| Custom Redirect                | `CustomRedirect`    | Where the user lands after login, logout, profile save, password reset                      | [7](/administration-guide/reference/system-properties.md#custom-redirect)    |
| Organization                   | `Organization`      | Which type means "division" and "department", hierarchy string, leaver script               | [7](/administration-guide/reference/system-properties.md#organization)       |
| IP                             | `IP`                | Geo-IP lookup source and local geo database                                                 | [6](/administration-guide/reference/system-properties.md#ip)                 |
| Security Questions & Help Desk | `ChallengeResponse` | Default question group, answer encryption, help-desk verification                           | [5](/administration-guide/reference/system-properties.md#challenge-response) |
| Notifications                  | `Notifications`     | The login-page banner: text, and whether it is public                                       | [2](/administration-guide/reference/system-properties.md#notifications)      |
| System Audit Log               | `SystemAuditLog`    | Per-action audit retention in days                                                          | [502](/administration-guide/reference/audit-actions-and-retention.md)        |

{% hint style="danger" %}
**The Gateway tab is not the Access Gateway.** All 16 of its keys are `org.openiam.smtp.mail.*` or a mail vault secret key — it is the SMTP mail gateway. Nothing about rProxy, content providers or URI patterns is on this tab. For the reverse proxy go to [Administer the Access Gateway](/administration-guide/gateway.md); for mail, prefer **Administration → Mailbox Configurations** as described in [Mail and notifications](/administration-guide/platform/mail-and-notifications.md).
{% endhint %}

## Settings that surprise people

Every value below is what a freshly migrated database contains. Read each one back on the tab named beside it before you rely on it — an upgraded installation can carry a value an earlier release set.

{% hint style="danger" %}
`org.openiam.authorization.oauth.disabled` ships **`true`** and `org.openiam.authorization.create.request.disabled` ships **`true`**. Both deliberately disable an authorization check, for backward compatibility with releases before 4.1.8. With OAuth authorization disabled, any authenticated user can complete an authorization against any non-public OAuth client; with create-request authorization disabled, the request catalogue returns every `ACTIVE` application category rather than the requester's entitled subset. Set both to `false` once you have entitled the right roles to your OAuth clients and request categories.
{% endhint %}

| Property                                                                        | Ships as                                                                                              | Why it surprises                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `org.openiam.provision.service.flag`                                            | `true`                                                                                                | The master provisioning switch. Set to `false`, the Webconsole still accepts user edits — it just stops calling connectors and stops requiring a login. Nothing on screen says provisioning is off; the observable difference is that no `PROVISIONING` audit event is written for a change that should have reached a managed system. |
| `org.openiam.iam.cryptor.algorithm`                                             | `AES`                                                                                                 | Not a display preference: changing it makes the ESB regenerate key material, which is a migration rather than an edit. Existing encrypted values were written under the old algorithm, and nothing on the screen warns you. Treat a change here as a project with a restore plan, not a property edit.                                 |
| `org.openiam.ui.webconsole.allow.change.own.entitlements`                       | `false`                                                                                               | An administrator cannot grant entitlements to themselves. The requester ID is compared to the target user ID before rights are evaluated, so the add fails with `CAN_NOT_CHANGE_OWN_ENTITLEMENT` even with full menu rights.                                                                                                           |
| `org.openiam.ui.enforce.subordinate.check.flag`                                 | `false`                                                                                               | Holding the `RESET_PASSWORD_DIRECT_REPORT` right lets a user reset *anyone's* password until this is `true`; only then is the target checked against the requester's actual subordinates. Test it with an account that holds the right and a target who is not their report.                                                           |
| `org.openiam.selfservice.organization.search.enabled`                           | `false`                                                                                               | Turning it on scopes search to the requester's organizations, but only when the path starts with `/selfservice` and the requester is not a super security admin. So it changes nothing in the Webconsole and nothing for your own account.                                                                                             |
| `org.openiam.virtual.tenant.enabled`                                            | `false`                                                                                               | Virtual tenancy by organization is off in a new installation; an organization hierarchy does not imply it.                                                                                                                                                                                                                             |
| `org.openiam.ui.captcha.testing.active` / `org.openiam.ui.captcha.default.code` | `false` / `123ABC`                                                                                    | Testing mode does not weaken the CAPTCHA, it removes it: the generator returns the default code instead of six random alphanumerics, so every challenge is `123ABC`. Never enable it on an internet-facing IdP.                                                                                                                        |
| `org.openiam.email.validation.regexp.name.first`, `...name.last`                | `^[a-zA-Z0-9_,]*$`                                                                                    | No space, hyphen, apostrophe or accented character in a name. `Mary-Jane`, `O'Brien` and `José` are all rejected when the user is provisioned. Widen these before your first HR feed — the rejection surfaces as a failed record in the synchronization report, not as a validation message on screen.                                 |
| `org.openiam.email.validation.regexp.login`                                     | `^[a-zA-Z0-9_,.@-]*$`                                                                                 | Applied to every principal on add or replace, and to group names on create. A login with a space cannot be provisioned.                                                                                                                                                                                                                |
| `org.openiam.email.validation.regexp`                                           | `^[_A-Za-z0-9-+]+(.[_A-Za-z0-9-+]+)*@[A-Za-z0-9-]+(.[A-Za-z0-9]+)*(\.[A-Za-z0-9]{1,})?$`              | The trailing dot-group is optional, so `<TEST_USER>@localhost` validates as an email address; and the `.` inside the two earlier groups is unescaped, so it matches any character. This is a permissive pattern, not a strict one.                                                                                                     |
| `org.openiam.ui.webconsole.active.user.status` / `...inactive.user.status`      | `ACTIVE,LEAVE,LEAVE_OF_ABSENCE,LEAVE_WITH_PAY,PENDING_INITIAL_LOGIN` / `TERMINATED,INACTIVE,DECEASED` | The two sets must not overlap. Save rejects any status present in both with `COULD_NOT_SAVE_STATUS_PROPERTIES` — "Active and Inactive statuses cannot have the same values".                                                                                                                                                           |

**`org.openiam.ui.webconsole.prohibited.user.status`** (*Prohibited User Status from Self-Service*) needs a note, because its shipped value depends on your upgrade history rather than on the release. It is seeded conditionally: empty when `org.openiam.ui.user.search.terminated.objects.flag` was `false` at upgrade time, and `TERMINATED,INACTIVE,DECEASED` when it was `true`. Since that flag itself ships `false`, **a freshly migrated database gets an empty value** and no status is prohibited from SelfService, while a system where somebody had set the old flag gets the three-status list. There is no way to tell which you have except to read the value on the **UI** tab; do that before writing a statement about what your SelfService hides.

## When the screen and the service disagree

A value shown here is authoritative for the database row and nothing more. A container can override the same key with an `OPENIAM_PROP_*` environment variable. If a service behaves as though your edit never happened, resolve the precedence question first — see [Where settings live](/administration-guide/start/where-settings-live.md) for the four layers and which one wins.

## Recognising a stale runbook

Thirty keys were seeded by one migration and deleted by a later one — among them `org.openiam.syslog.*` and `org.openiam.password.expiration.warnDays`. They are listed under [Properties removed by a later migration](/administration-guide/reference/system-properties.md#properties-removed-by-a-later-migration). If a runbook tells you to set one, it predates your release: the row is gone, the field is not on the tab, and nothing reads the value.

## Related

* [System property reference](/administration-guide/reference/system-properties.md) — every key, type and shipped default
* [Change configuration safely](/administration-guide/start/change-safely.md) — the general safety standard this page applies
* [Mail and notifications](/administration-guide/platform/mail-and-notifications.md) — where the deprecated Gateway tab's settings moved to

*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/platform/system-configuration.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.