> 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/solution-architecture/reference-architectures/coexistence-with-incumbent-iga.md). # Coexistence with an incumbent IGA OpenIAM running alongside an incumbent identity governance platform through a phased migration — the single-writer rule, read-only synchronization for the enterprise view, and migrating applications i ## What this is, and when you need it Two governance platforms are running at the same time and both of them are real. One is the incumbent — already governing an application estate, already certified, already relied on by an audit function. The other is OpenIAM, adopted for the wider organization. Nobody is prepared to cut over in one step, and nobody wants to run two platforms forever either. This design is how you run both without producing two versions of the truth. Its centre is a rule rather than a component: **exactly one platform is the write owner for a given application at any moment.** Every other decision on this page follows from it. You need this when an acquisition brings a governance platform with it, when a migration is long enough that "during" is a state you have to operate in rather than pass through, or when a regulator will ask who was accountable for a given access grant on a given date and the answer has to be one name. ## The situation it fits * Two identity governance platforms in production at once, each with an application estate it owns. * Two HR systems, or one HR system plus a second population that the incumbent's platform is authoritative for. * A migration measured in quarters, running application by application rather than all at once. * A requirement — usually from audit, sometimes from a merger integration office — for one enterprise-wide view of who has access to what, spanning both estates, before the migration finishes. * A regulated environment, where every change of governance owner has to be validated rather than merely configured. ## The shape Read the solid arrows as "governs, approves and provisions". Read the labelled read-only arrows as "copies the resulting access across for visibility, and writes nothing back". ```mermaid flowchart LR HRA[Primary HR system] --> IAM[OpenIAM] HRB[Acquired organization HR system] --> INC[Incumbent IGA] IAM -->|governs and provisions| MIG[Applications in a completed wave] INC -->|governs and provisions| PEND[Applications awaiting their wave] PEND -->|read-only into OpenIAM| IAM MIG -->|read-only, if the incumbent still needs the view| INC ``` Over the life of the migration, applications move from the lower branch to the upper one, one wave at a time. The diagram does not change shape; only the membership of the two application sets changes. When the last application has moved, the incumbent branch is empty and the platform is retired. ## The decisions embedded in it | Decision | The choice made here | Explained in | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Who governs each application | Exactly one platform, named per application, changed only at a wave boundary | Part 5, *Coexisting with an incumbent IGA* | | How the other platform sees that access | Read-only synchronization of the resulting entitlements, with no write path back | Part 5, *The enterprise view without duplicate governance* | | Where a user requests an application | In the catalogue of the platform that owns it. The user crosses to the other platform; the request does not | Part 5, *Where a request lives when two catalogues exist* | | How a leaver is handled while both platforms run | The write owner for each application performs the removal; the other reflects it | Part 5, *Lifecycle events across a governance boundary* | | How the two estates authenticate each other's users | A federation trust between the two identity providers | Part 5, *Cross-organization federation*, and [Cross-organization federation](/solution-architecture/reference-architectures/cross-organization-federation.md) | | What order applications migrate in | By risk, by dependency and by the availability of the connector, not by convenience | Part 5, *Planning a wave migration* | | What the primary identity is | Established from the acquiring organization's HR feed, correlated on a workforce identifier | Part 2, *Identity correlation: choosing a matching key* | | What evidence the arrangement has to produce | Per-application, per-period, naming the platform that was the write owner at the time | Part 8, *Operating in a regulated environment* | ### The single-writer rule, stated precisely For each application, at each moment, one platform holds all four of these: the catalogue entry the user requests from, the approval policy, the connector that performs the change, and the certification that attests to the result. They do not split. An arrangement where one platform approves and the other provisions is not coexistence, it is a distributed system with no owner, and it fails the first time the two disagree. The rule is worth writing into the programme's governance documents in those terms, because the pressure to break it is constant and always reasonable-sounding: someone wants to raise a request in the platform they already know, or wants a role in one platform to grant access in an application owned by the other. Both requests split the four things above, and both should be declined until the application's wave arrives. What the other platform may do is **see** the access. That is not governance and it does not violate the rule. ### The enterprise view, without duplicate governance The audit function wants one screen showing who holds what across both estates. That is achievable and it is the main thing the coexistence period has to deliver beyond simply not breaking. The mechanism is a read-only reconciliation. OpenIAM models each incumbent-governed application as a managed system, reads its accounts and entitlement memberships, and records them against the OpenIAM identity — so the enterprise view is assembled from real data rather than from a spreadsheet. What makes it read-only is which reconciliation outcomes you allow. For an incumbent-owned application, permit only the outcomes that write into OpenIAM — **Add Record to IDM from Resource** and **Update IDM from Resource** — with **Do Nothing** wherever no action is wanted, and permit none of the outcomes that write to the application: **Add Record to Resource from IDM**, **Update Resource from IDM** and **Delete from Resource**. Configured that way, OpenIAM can see everything and change nothing, which is exactly the property the rule requires. Two responses look like they belong on that list and do not. **Do Nothing and Inform** and **Disable (or change status in Resource)** appear in the drop-down but have no built-in command behind them, and selecting either without supplying a custom command script fails the run rather than doing nothing. Use **Do Nothing**. [The enterprise view without duplicate governance](/solution-architecture/coexistence/the-enterprise-view.md) covers this and the narrower response set that group reconciliation supports. Two consequences to plan for. First, the imported access is **observed, not governed** — it appears in reports and in the enterprise view, but it must not be included in an OpenIAM certification campaign, because OpenIAM cannot act on a revoke decision for an application it does not write to. A campaign that collects decisions it cannot enforce produces evidence that is worse than no evidence. Second, the imported memberships must be visibly distinguishable from OpenIAM-governed ones, or somebody will eventually try to revoke one. The same arrangement can run in the other direction where the incumbent needs to see OpenIAM-governed access. It is the same rule, mirrored. ### Migrating in waves A wave is a set of applications whose write ownership transfers together, on a date, with a validation step. The transfer itself is the moment of risk, and it has a specific shape: the incumbent stops being the write owner *before* OpenIAM starts, and the interval between the two is when nothing governs the application. Keep it short, plan it deliberately, and do not let it span a certification period. Choosing the order is the part that most often goes wrong. Sequence by risk and dependency, not by ease: * Applications whose entitlements feed other applications' access decisions go early, because everything downstream inherits their correctness. * Applications in scope for the next certification cycle go before it, not during it — a campaign that straddles a change of write owner is very hard to explain to an auditor. * Applications whose connector does not yet exist do not go in a wave at all until it does. A wave that depends on an integration being written is a wave that will slip. * The highest-risk application should not be first. It should be early enough to matter and late enough that the process has been proved twice. Each wave ends with the same evidence: the incumbent no longer holds the four things, OpenIAM does, and the access after the transfer matches the access before it. ### Leavers and transfers across the boundary Two lifecycle events cross the governance boundary and both need answering explicitly, because a design that only handles a joiner will not survive contact with the estate. **A leaver** is detected by whichever platform is fed by the HR system that holds the person's employment. That platform removes the access it owns. The access the *other* platform owns is not removed by that event and will not be removed by it — the read-only view will show it sitting there, correctly, and someone has to act. The clean answer during coexistence is that each platform runs its own leaver process against its own estate on its own HR signal, and the enterprise view is what proves that both ran. The unclean answer, which is worth naming because it gets proposed, is to let one platform reach into the other's applications for terminations only. That splits the four things and breaks the rule; it also produces removals with no approval record. **A transfer between the two organizations** is harder than a leaver, because the person is a leaver in one HR system and a joiner in the other, usually with a new employee identifier. If the correlation key changes, the identity fractures and the person's history splits in two. The design decision to make in advance is which identifier survives the move, and the practical answer is usually that the enterprise identifier does — one more reason to mint one rather than adopt an HR system's own numbering. Get this wrong and every transfer creates an orphaned identity holding access nobody is now accountable for. ## What we recommend **Write the single-writer rule into the programme's terms of reference, not just the architecture.** It will be tested by people with legitimate business reasons, and the architecture document is not where that argument gets settled. **Deliver the read-only enterprise view early — it is the coexistence period's main deliverable.** It is what makes running two platforms defensible to an audit function, and it is achievable long before the first application migrates. **Do not certify what you cannot revoke.** Keep imported access out of OpenIAM campaigns until the application's wave has completed. **Decide the transfer case before the first wave.** It will happen during the migration, and improvising it produces split identities that are expensive to repair. **Plan the incumbent's retirement as a wave with a date, not as an eventual state.** Coexistence architectures that lose their end date become permanent, and a permanent two-platform estate has all of the cost and none of the benefit. **Keep the federation bridge and the governance boundary as separate concerns.** Users crossing between estates is an authentication decision; who governs an application is a governance decision. They are frequently conflated in these programmes and they have different owners. ## What would make this the wrong choice * **The incumbent can be switched off in one step.** If the estate is small enough, or the incumbent's coverage thin enough, a single cutover is cheaper and safer than a coexistence architecture. Coexistence is a cost you accept to avoid a bigger one; if the bigger one is not there, do not accept it. * **The two platforms would have to write to the same application.** If there is an application that genuinely cannot have a single write owner — because two independent business units provision into it on different schedules — this design does not accommodate it, and pretending otherwise produces the failure it exists to prevent. Solve that application separately, before the wave plan. * **There is no correlation key that spans both estates.** Without one, the enterprise view cannot be assembled: you get two lists rather than one picture. Establish the key first. * **The incumbent has no readable interface.** The read-only view depends on being able to read accounts and entitlement memberships out of the incumbent's estate — usually from the applications themselves rather than from the incumbent platform. If neither is readable, the enterprise view is not available and the main benefit of this design goes with it. * **The migration has no end date.** Then this is not a migration architecture, it is a permanent federated-governance design, and it should be assessed as one. ## What OpenIAM does not do here * **OpenIAM does not integrate with another IGA platform as a platform.** There is no connector to a governance product's own model. The read-only view is assembled by reading the *applications* the incumbent governs, in the same way OpenIAM reads any other managed system. * **Imported access is not governable access.** OpenIAM can display and report on entitlements it did not grant; it cannot revoke them in an application it has no write path to. * **There is no cross-platform approval routing.** A request in one platform's catalogue cannot be approved in the other's inbox. * **A reconciliation that finds an account it cannot match to an identity does not fail; it reports an orphan.** During coexistence orphans are expected and their volume is a signal about the correlation key — see *Resolve orphan accounts* in the Administration Guide. * **Nothing in the product enforces the single-writer rule.** Both platforms can be configured to write to the same application. The rule is an operating discipline, and the architecture is what makes it visible when it is broken, not what prevents it. ## Related * Part 5, *Coexisting with an incumbent IGA* and *Planning a wave migration* — the decisions this design combines. * [Cross-organization federation](/solution-architecture/reference-architectures/cross-organization-federation.md) — the authentication half of the same situation. * *Import roles, groups, organizations and entitlement memberships* and *Configure reconciliation* in the Administration Guide — the mechanisms behind the read-only view. *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/solution-architecture/reference-architectures/coexistence-with-incumbent-iga.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.