> 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.md).

# Reference architectures

Three worked designs — several Active Directory forests, coexistence with an incumbent IGA, and federation between two organizations — each a starting point to adapt rather than a prescription to foll

## What this is, and when you need it

A reference architecture here is **a set of decisions that have already been made, written down together with the reasoning, for a situation that recurs.** Each page names the situation it fits, shows the shape in a diagram, lists the decisions embedded in it with a pointer to the page that explains each one, and — the section that matters most — states what would make it the wrong choice.

Use these when you are early in a design and want to see a coherent whole before you start choosing piece by piece. They are also the fastest way to explain a proposed design to someone who is not going to read the rest of this guide.

## What a reference architecture is not

It is not a template to implement. Every one of these designs contains decisions that are right for the situation described and wrong for a situation that differs in one important respect — which is why each page ends by saying what those respects are. Two organizations with the same forest count and the same head-count can need different designs because one has ADFS on its domains and the other does not.

It is also not a configuration. No page here tells you which field to set; that belongs to the Administration Guide, and each decision links to the page in Parts 2 to 6 that explains the choice before the Administration Guide explains the mechanism.

And it is not a claim about what OpenIAM is good at. Each page names the situations where the design breaks down, including the ones where the honest answer is that a different platform boundary — or a different sequencing — serves the estate better.

## The three designs

| Reference architecture                                                                                                                   | The situation it fits                                                                                                           | The decision at its centre                                                                                                          |
| ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| [One organization, several Active Directory forests](/solution-architecture/reference-architectures/single-organization-multi-forest.md) | A single governance domain whose people and applications are spread across several AD forests, with different usernames in each | What links a person's accounts across forests, and where authentication happens now that it can no longer happen in "the" directory |
| [Coexistence with an incumbent IGA](/solution-architecture/reference-architectures/coexistence-with-incumbent-iga.md)                    | Two governance platforms running at once through a phased migration, with no appetite for a big-bang cutover                    | Which platform is the write owner for a given application, and how the other one sees that access without governing it              |
| [Cross-organization federation](/solution-architecture/reference-architectures/cross-organization-federation.md)                         | Two organizations that stay separate, each with its own identity provider, whose people need each other's applications          | Which platform authenticates, which authorizes, and what the federation bridge does and does not carry                              |

The three compose. A large estate frequently has all of them at once: several forests inside the acquiring organization, an incumbent IGA on the acquired side, and a federation bridge between the two while the migration runs. Where a page depends on a decision another page makes, it says so rather than repeating it.

## What all three assume

Two positions run through every design here, and it is worth stating them once.

**Identity lifecycle comes before single sign-on.** An identity has to be known in OpenIAM and known in the target application before single sign-on to that application can work at all. Every one of these designs establishes the identity first and federates second, and the sequencing page in Part 8 explains why a programme that inverts the order stalls.

**Exactly one platform writes to a given application at a time.** Two platforms may both read; only one provisions, approves and certifies. This is the rule that makes coexistence safe and the rule whose violation makes it unrecoverable.

## Related

* Part 1, *The OpenIAM architecture* — what the platform is made of, which every design here assumes.
* Part 5, *Coexistence and migration* — the individual decisions the coexistence design combines.
* *The OpenIAM object model* and *The authentication model* in the Administration Guide — the model these designs apply.

*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.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.