> 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/start/change-safely.md). # Change configuration safely The change, test and rollback standard every procedure in this guide assumes — stated once, here. ## What this is, and when you need it This is the guide's single safety standard. Task pages link here rather than restating it, so if a procedure does not repeat a warning you have already read, that is deliberate. Pages add a caution only where the risk is specific to that task. ## The standard Five things, before any change that is not read-only. **Record the current state.** The exact setting or object, its current value, the layer you are editing ([where settings live](/administration-guide/start/where-settings-live.md)), the product build, your account, the time, and who owns the rollback. A change you cannot describe is a change you cannot reverse. **Change one related set at a time.** Not one field — one *coherent* set, such as the composition rules of a password policy. Save once. Changing two unrelated things and testing afterwards tells you nothing about which one broke. **Confirm the change persisted.** Reopen the object or tab and read the stored value back. A `Save` message means the request was accepted, not that the value is what you intended, and not that the subsystem consuming it has picked it up. **Test one case that must succeed and one that must fail.** The negative test is the one that finds the mistake. A password policy that accepts a good password proves nothing until it also rejects the bad one; an entitlement that grants access to the assigned user proves nothing until the unassigned user is still refused. **Verify the outcome, not the save.** OpenIAM work crosses the browser, a UI service, the ESB, RabbitMQ, a connector and the managed system. Evidence lives at the far end: the target object, the connector reply, the reconciliation or workflow history, the audit event. See [Diagnose a failed operation](/administration-guide/operations/diagnose-a-failed-operation.md). ## Scope your first test Use a disposable identity, a dedicated test organization or container, and an inactive or narrowly scoped object. Two specific boundaries matter more than the others: * **Never point a first connection at a production-wide base DN, an unfiltered table, or an administrative account.** A too-broad search scope on a first reconciliation or synchronization does not fail safely — it correlates or provisions at scale. * **Leave `Active` off** while building a managed system, authentication provider or campaign. Saving an inactive object is a checkpoint you can inspect; an active one is a change in behaviour. ## Keep a way back in Before you touch anything that decides how people sign in — authentication providers or policies, content providers, URI patterns, redirects, federation trusts, certificates, sessions, or the Webconsole's own protection — establish and **test** a break-glass administrator that does not depend on the thing you are about to change. Test it in a separate browser session, before the change, and confirm it still works after. A locked-out administrator on a system whose sign-in routing is broken is a database-level recovery. That is the one failure in OpenIAM administration that the product cannot help you out of. ## Changes with a wide blast radius These are the settings and flags where a small edit affects a large population. Treat each as a reviewed change with an impact estimate, not a configuration tweak. | Change | Why it is wide | | ---------------------------------------------- | -------------------------------------------------------------------------------------------- | | Authentication provider, policy or routing | Affects everyone who signs in, including you | | Content provider or URI pattern | Decides what is reachable and what is protected | | `Provision all users with this managed system` | Associates the managed system on user save, without an entitlement | | Birthright rules and universal roles or groups | Grants to a population, not a person | | Reconciliation situation responses | Can create, disable or delete accounts on either side at scale | | Synchronization source scope or filter | Decides which identities are authoritative | | Business rules | Recalculated nightly by an enabled batch task, so a change applies whether or not you run it | | Password policy | Applies at next change or reset, across every user it governs | | Tenant scope | Changes what every administrator can see | | Search index or authorization graph rebuild | Expensive, and competes with live traffic | | Service credential rotation | Breaks every integration still holding the old secret | ## Reversibility, honestly Not everything is reversible, and the guide will tell you which is which. Three categories: **Reversible.** Property values, most object fields, entitlement grants. Restore the recorded value and re-test. **Reversible with consequences.** Provisioning and deprovisioning. You can re-grant a revoked entitlement, but the account may have been disabled or deleted in the target, and the target's own history is not restored by OpenIAM. **Not reversible.** Deleted audit history. A rotated secret — you must roll forward, never restore a compromised credential. A campaign whose decisions have been applied. A pruned log. ## Secrets Never put a credential in an object description, a screenshot, a ticket, or a script that logs its input. A masked value on reload proves the field is masked, not that the target accepted it. If a secret has been exposed, rotate it — do not restore it. ## Related * [Where settings live](/administration-guide/start/where-settings-live.md) — which layer you are actually editing * [Diagnose a failed operation](/administration-guide/operations/diagnose-a-failed-operation.md) — where the proof is * [Shipped batch tasks](/administration-guide/reference/shipped-batch-tasks.md) — what is already running on a schedule *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/start/change-safely.md?ask=&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.