> 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/coexistence/cross-organization-federation.md). # Cross-organisation federation Trust between two identity providers — why each direction is a separate decision, why the identifiers on the two sides need not match, and why synchronization is the basis for the identity with just-i ## What this is, and when you need it Two organizations, two identity providers, and people on each side who need to reach applications on the other. Neither identity provider is going away — at least not on the timescale of this decision. Three questions have to be answered, and they are independent of each other. **Which direction of trust do you need, and when?** **How does a person known by one identifier in one estate become the right person in the other?** And **how does the receiving estate come to know that person at all — ahead of time, or at the moment they first arrive?** The third is the one this page argues hardest about, because it is usually decided by default and the default is the wrong way round. ## The decision The substantive choice is how the identity gets into the receiving estate. | Approach | What it gives you | What it costs | | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Synchronization** — the population is provisioned into the receiving estate ahead of any sign-in (recommended for workforce) | The receiver can answer "who could sign in here" without waiting for someone to try; can certify the population; can report on it; can disable on a leaver signal; and can attach entitlements before first use rather than during it | A feed to build and operate, and an agreement between two organizations about what data crosses — which is a negotiation, not a configuration | | **Just-in-time provisioning** — the identity is created on first successful sign-in | Nothing to pre-stage. A partner population that may never arrive costs nothing until it does. Right for large, loosely coupled or consumer-facing populations | The receiver cannot see, certify or report on a population that has not signed in yet, and has no lifecycle signal afterwards: the record is created by an assertion, and nothing removes it when the person leaves. In OpenIAM it is also a script you write and maintain | | **Locally created accounts, no federation** | No trust to configure; total control | A second credential per person, a second password reset path, and a population nobody's HR system owns. Defensible for a few dozen people and nothing more | | **No integration** — each organization's people use only their own applications | Nothing to build | Only viable if the business genuinely does not need the crossing. Usually it does, and the workaround is shared accounts | **Synchronize the identity, then federate the authentication.** Just-in-time provisioning works and it has its place; it is the fallback, and a design that reaches for it first is usually avoiding a conversation between the two organizations rather than making an architectural choice. ## Each direction of trust is a separate decision A federation trust is one-way in the sense that matters: it lets the *relying* side accept assertions from the *asserting* side. Two organizations that both need to reach each other's applications need two trusts, configured independently, often months apart, and each with its own agreement about attributes and identifiers. Read the diagram as trust direction only. Each labelled arrow is one configuration, on the side the arrow starts from. ```mermaid flowchart LR AIDP[OpenIAM, identity provider for organization A] BIDP[Partner identity provider for organization B] AAPP[Applications owned by A] BAPP[Applications owned by B] AIDP --> AAPP BIDP --> BAPP BIDP -->|trusts assertions from| AIDP AIDP -->|trusts assertions from| BIDP ``` The upper trust is what lets a person whose home identity is in A reach an application owned by B; the lower one is the mirror. Establishing one does not establish the other, and it is common for the business case to exist in only one direction for the first year. Do not hold the needed direction back waiting for the other. OpenIAM occupies both roles. It acts as a SAML identity provider for applications that trust it, and as a SAML service provider to an external identity provider, and the two can be chained: an authentication provider can be marked as chained, with the next provider in the chain named, so that a request arriving at OpenIAM is passed on to the partner's identity provider and the response comes back through OpenIAM to the application. Chaining is what lets an application that only trusts one identity provider serve people whose credentials live in another. ## The identifiers do not need to match The standing objection to cross-organization federation is that the two estates identify the same person differently — different usernames, different employee numbers, sometimes different mail domains — and that nobody is willing to renumber. That objection does not survive contact with the protocols, which are explicit about identity translation: the assertion names the subject in whatever form the asserting party uses, and the relying party maps it to its own record. OpenIAM exposes that mapping on both sides. As an identity provider it decides what goes into the assertion, with a **NameID Resolver Groovy Script** determining the name identifier's value and format; shipped example resolvers demonstrate the contract for both roles. As a service provider it decides what an inbound assertion means, which is where a partner's identifier becomes an OpenIAM identity. What you do need is a **stable mapping**, agreed in writing between the two organizations, that survives a name change, a transfer and a re-issued account. That is the same requirement as an internal correlation key and it is settled the same way: on a workforce identifier or a synthetic enterprise identifier, never on a username and never on an email address. Large organizations that operate through subsidiaries frequently mint an enterprise-wide identifier for exactly this reason — so that one person has one identity across the parent and its parts, whatever the local HR system calls them. See Part 2, *Identity correlation: choosing a matching key*. ## Why synchronization is the basis and just-in-time is the fallback The two approaches look interchangeable from the user's seat: in both cases the person signs in and reaches the application. They are not interchangeable from anywhere else. **Synchronization makes the population knowable.** A receiving estate that has been synchronized can answer questions about people who have not signed in yet — how many partner identities exist, which have access to what, which should be disabled. A receiving estate relying on just-in-time provisioning can only answer questions about people who have already arrived, and cannot distinguish "has no access" from "has not tried". **Synchronization gives lifecycle a place to attach.** A leaver in the partner organization is a change to a record the receiving estate already holds. With just-in-time provisioning the record was created by an authentication event, and there is no equivalent event for departure — the assertions simply stop, and nothing in the receiving estate notices. That is the single most common defect in these designs: an assumption that access lapses when the partner stops authenticating the person. It does not. **Synchronization puts entitlement before use.** Access can be requested, approved and provisioned before the person's first sign-in, which is the ordinary sequence. With just-in-time provisioning the identity comes into existence in the middle of an authentication transaction, so entitlement is either granted by the same script — which turns a partner's assertion into an authorization decision, and should give you pause — or granted afterwards, which means the first sign-in reaches nothing. **Synchronization is what a regulated estate is asked for.** "Show me every person who can authenticate into this system, and who approved their access" is answerable from a synchronized population and only partially answerable from a just-in-time one. Just-in-time provisioning is the right answer where pre-provisioning is disproportionate: very large partner populations of whom only a fraction will ever sign in, loosely coupled relationships, and consumer-facing scenarios. It is common in customer identity and uncommon in workforce identity, and that distribution is not an accident. ### What just-in-time provisioning actually is in OpenIAM Before choosing it, know its shape here, because it is less of a feature and more of an extension point. Just-in-time provisioning for inbound SAML is **a Groovy script you write**, selected on the SAML service provider configuration as the **Just-in-time provisioning groovy script**. Selecting a script is what enables the behaviour; there is no separate switch. The script extends a shipped base class and supplies the identity's attributes — the name, the email and whatever else you populate — typically by reading named attributes out of the assertion. The script is invoked for **both new and existing users**, so it is also where an existing identity is updated from an inbound assertion, and a shipped example demonstrates the contract. The example is a demonstration, not a starting configuration: it fabricates names. Treat it as documentation of the interface. Two limits follow, and both belong in the design. **It creates; it does not maintain.** A record created on first sign-in is not updated or disabled by later events unless something else does that. There is no lifecycle in this path. **A separate just-in-time capability flag exists in the authentication provider model and is not the mechanism.** It gates a different code path that has no implementation behind it. If you are looking for a checkbox, you will find one that does nothing; the script is the feature. ## What federation does not carry Worth restating in the design review, because assumptions to the contrary are what turn a working trust into an incident. A federation assertion carries **an authentication event and a set of attributes**. It does not carry entitlements — the receiving organization decides what the person may do, from its own records. It does not provision, unless the receiver has deliberately configured just-in-time provisioning to do so. It does not carry a request or an approval; see [Where a request lives when two catalogues exist](/solution-architecture/coexistence/where-a-request-lives.md). And it does not carry lifecycle; see [Lifecycle events across a governance boundary](/solution-architecture/coexistence/lifecycle-across-a-governance-boundary.md). One sentence for the review: **federation moves the authentication event; it does not move the identity, the entitlement, or the lifecycle.** ## What we recommend **Synchronize the population first, federate second.** A trust that works before the receiving estate knows who the people are will appear to work and will fail audit. **Treat the two directions as two projects.** Build the one the business needs now. The second trust is a second agreement as much as a second configuration. **Agree the identifier mapping in writing, jointly, and base it on something stable.** This is the decision with the highest cost of revision and the lowest cost of getting right early. **Keep authentication policy at home and authorization policy at the application.** Each organization retains its own multi-factor and adaptive rules for its own people; the application's owner decides entitlement and may still require step-up for a sensitive operation. See Part 3, *Where authentication should live*. **Use just-in-time provisioning deliberately, and write down why.** Large, loosely coupled or consumer-facing populations, yes. Workforce federation between two organizations that both have HR systems, no — that estate can be synchronized, and the reason it has not been is usually organizational. **If you do use it, pair it with a periodic reconciliation of the created population.** It is the only way to answer who exists and to catch the records nothing will ever disable. **Solve termination with the feed, never with the trust.** Removing a trust does not remove access; it removes a route to it. ## What OpenIAM does not do here * **Inbound federation from a partner organization is SAML.** OpenIAM acts as an OpenID Connect provider for applications that trust it, and as a SAML service provider for inbound federation; the other shipped inbound provider types are the named social and verification providers. Plan a partner trust as SAML. * **Federation does not synchronize anything.** If the identity must exist on both sides — and for workforce federation it must — that is a separate feed you build and operate. * **Just-in-time provisioning is a script, not a configuration.** There is no declarative attribute mapping and no shipped production script; the only shipped script is an interface example. * **Just-in-time provisioning creates and updates on sign-in only.** Nothing disables a record because the person stopped arriving. * **A trust in one direction is not a trust in both.** Each is configured independently on the relying side. * **OpenIAM does not route a request or an approval across a trust.** Requests stay with the catalogue that owns the application. ## Related * [Where a request lives when two catalogues exist](/solution-architecture/coexistence/where-a-request-lives.md) — what the user does after crossing. * [Lifecycle events across a governance boundary](/solution-architecture/coexistence/lifecycle-across-a-governance-boundary.md) — the feed that federation does not replace. * Part 3, *Where authentication should live* — the decision this one sits on top of. * *OpenIAM as a SAML identity provider*, *OpenIAM as a SAML service provider* and *Just-in-time provisioning* in the Administration Guide — the trust, the chaining and the script contract. *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/coexistence/cross-organization-federation.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.