> 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/cross-organization-federation.md). # Cross-organisation federation Two organizations that stay separate, each with its own identity provider, federated in both directions — which platform authenticates, which authorizes, and what a federation assertion does and does ## What this is, and when you need it Two organizations, two identity providers, and people on each side who need applications on the other. Neither estate is being absorbed into the other — at least not soon — and neither identity provider is going away. What is needed is a trust in both directions, and a clear answer to the question that decides everything else: **when a person from one organization opens an application owned by the other, which platform checked who they are, and which platform decided what they may do?** You need this design after a merger where the two halves stay operationally distinct, in a joint venture, in a parent-and-subsidiary structure where the subsidiary keeps its own IT, and alongside [coexistence with an incumbent IGA](/solution-architecture/reference-architectures/coexistence-with-incumbent-iga.md) — that design covers who governs an application, this one covers how a user reaches it. ## The situation it fits * Two identity providers, each authoritative for its own population's credentials, both staying. * Applications owned unambiguously by one organization or the other, each with a single catalogue, approval policy and provisioning path. * Identifiers that differ between the estates — different usernames, different employee numbers, sometimes different email domains — with no plan to unify them. * A requirement that each organization retains control of its own authentication policy, including its own multi-factor rules. * Users who will not accept a second set of credentials, and who arrive at applications by bookmark as often as by portal. ## The shape Read this as a chain of trust. The user's home identity provider authenticates; the application's identity provider authorizes and issues the assertion the application itself trusts. ```mermaid sequenceDiagram participant U as User, home identity in Organization A participant APP as Application owned by Organization B participant BIDP as Organization B identity provider participant AIDP as OpenIAM, Organization A identity provider U->>APP: Opens the application URL APP->>BIDP: Redirects the browser for authentication BIDP->>AIDP: Recognises a home realm in A and redirects on AIDP->>AIDP: Authenticates the user under A's own policy AIDP->>BIDP: Assertion carrying A's identifier for the user BIDP->>BIDP: Translates to B's identifier and applies B's authorization BIDP->>APP: Assertion the application already trusts APP->>U: Establishes the application session ``` The mirror case — a user from B reaching an application owned by A — is the same picture with the roles exchanged. Both directions have to be configured; a trust established one way does not work the other. OpenIAM supports both roles in this chain. It acts as a SAML identity provider for applications that trust it, and as a SAML service provider to an external identity provider, and those roles can be chained — which is what the middle of the diagram requires. ## The decisions embedded in it | Decision | The choice made here | Explained in | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Which platform authenticates | Always the user's home identity provider, under its own authentication and MFA policy | Part 3, *Where authentication should live* | | Which platform authorizes | Always the application's owner. Entitlement is decided where the application is governed | Part 5, *Where a request lives when two catalogues exist* | | How the identity is known on both sides | Established in advance by synchronization, not created at sign-in time | Part 5, *Cross-organization federation* | | How identifiers are reconciled | By translation at the bridge; the two organizations' identifiers do not need to match | Part 2, *Identity correlation: choosing a matching key* | | Where a user requests the other organization's applications | In that organization's catalogue, reached across the bridge | Part 5, *Where a request lives when two catalogues exist* | | Where a user starts | Either end — SP-initiated from the application, or IdP-initiated from the portal. Both are supported and both should work | Part 3, *Entry points and the user's experience* | | What MFA applies | The home organization's, at authentication; step-up at the application's owner if its policy demands more | Part 3, *Authentication and access*, which routes the mechanism to the Administration Guide | ### What federation carries, and what it does not This is where cross-organization designs go wrong, so it is worth being blunt. A federation assertion carries **an authentication event and a set of attributes**. That is all. In particular: * It does **not** carry entitlements. The receiving organization decides what the user may do, from its own records. An assertion that lists group memberships from the sending organization is carrying attributes that the receiver may choose to interpret — it is not carrying authorization. * It does **not** provision. No account is created in the receiving estate by an assertion arriving, unless the receiver has deliberately configured just-in-time provisioning to do so. * It does **not** carry a request or an approval. A user cannot ask for access in one organization's catalogue and have it granted in the other's. * It does **not** carry lifecycle. A leaver in organization A is not a leaver in organization B because the assertions stop arriving; B's records still show the access. Termination across the boundary is a lifecycle problem, and it is solved by the feed, not by the trust. * It does **not** establish a session in the other organization's other applications by itself. What the receiving identity provider does with the assertion — whether it mints its own session usable across its estate — is the receiver's design decision. The single sentence to carry into the design review: **federation moves the authentication event; it does not move the identity, the entitlement, or the lifecycle.** ### The identifiers do not need to match A recurring objection is that the two organizations use different identifiers for the same person, so federation cannot work. It can. The protocols are explicit about identity translation: the assertion names the subject in whatever form the sending party uses, and the receiving party maps it to its own record. OpenIAM does this in both roles. As a service provider it correlates an inbound assertion to a user, with a resolver script available for the cases where matching on the subject identifier alone is not enough — a different identifier per partner, a composite key, a lookup through an attribute rather than the subject. As an identity provider it controls what identifier it puts in the assertion, with a post-processing script available where the outbound form needs shaping for a particular partner. What you do need is a **stable mapping** — one that survives a name change, a transfer, and a re-issued account. That is the same requirement as an internal correlation key and it should be settled the same way: on a workforce identifier or a synthetic enterprise identifier, never on a username or an email address. ### Synchronization before federation, and why just-in-time is the fallback For federation to be useful, the identity has to exist in the receiving estate. There are two ways to get it there, and the choice matters more than it appears to. | Approach | What it gives you | What it costs | | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Synchronization** — the identity is provisioned into the receiving estate ahead of any sign-in | A complete picture: the receiver can certify the population, report on it, disable it on a leaver event, and answer "who could sign in here" without waiting for someone to try | A feed to build and operate, and an agreement between the two organizations about what is shared | | **Just-in-time provisioning** — the identity is created on first successful sign-in | Nothing to build in advance; a partner population that may never sign in costs nothing until it does | The receiver cannot see a population that has not arrived yet, cannot certify it, and has no lifecycle signal — the record is created by an assertion and nothing removes it when the person leaves | **Prefer synchronization for workforce federation.** It is cleaner, more comprehensive, and it gives the compliance control that a regulated estate will be asked for. Just-in-time provisioning works, OpenIAM supports it as a service provider, and it is the right answer for large, loosely-coupled or customer-facing populations where pre-provisioning everyone is disproportionate. It is the fallback, not the default, and a design that reaches for it first is usually avoiding a conversation between the two organizations rather than making an architectural choice. ### Where a user asks for an application owned by the other organization The user crosses the bridge; the request does not. Each application has one catalogue entry, one approval policy, one connector and one provisioning owner, all held by the organization that owns it. A user from A who wants an application owned by B signs in through the bridge to B's request experience and asks there. The approval is B's, the provisioning is B's, and the certification is B's. The alternative — routing the request back into A's catalogue and having A ask B to fulfil it — creates a request with two owners, an approval record in one platform and a provisioning record in another, and no single place that can answer whether the access was granted. It is the same failure as breaking the single-writer rule, arriving from a different direction. ### Both entry points have to work Users will arrive both ways and the design should not care. **SP-initiated** is the user opening the application's own URL — the bookmark they have had for three years — and being redirected to authenticate. **IdP-initiated** is the user starting at their own portal and launching the application from there. OpenIAM supports both, and IdP-initiated single sign-on is recorded distinctly in the audit log under the `SAML_IDP_INITIATED_SSO` action, so the two are separable in evidence. Design for both. A user with twenty bookmarks is not going to adopt a portal because the architecture would prefer it, and a design that only supports one entry point produces a launch full of support tickets that are all the same ticket. ## What we recommend **Decide the direction of each trust separately.** They are two configurations and two agreements, and it is common for one direction to be needed months before the other. Do not wait to build both. **Establish the identity before you establish the trust.** Synchronize first, federate second. A federation that works before the receiving estate knows who the people are will appear to work and will fail audit. **Agree the identifier mapping in writing between the two organizations, and base it on something stable.** This is a joint decision, not a technical detail, and it is the one that is expensive to revisit. **Keep authentication policy at home and authorization policy at the application.** Each organization retains its own MFA and adaptive rules for its own people; the application's owner decides entitlement and may still demand step-up for a sensitive operation. **Solve termination with the lifecycle feed, not with the trust.** The most common defect in these designs is an assumption that access lapses when the partner stops authenticating the person. It does not. **If a coexistence migration is also running, keep the two designs separate in the documentation.** The federation bridge is about how a user gets there; the single-writer rule is about who governs what they find. Programmes conflate them and then cannot explain either. ## What would make this the wrong choice * **The two organizations are actually one governance domain.** If there is one HR function, one audit boundary and one set of policies, federating between two identity providers is preserving an accident of history at permanent cost. Consolidate instead, and use [the multi-forest design](/solution-architecture/reference-architectures/single-organization-multi-forest.md). * **A single audit trail spanning both estates is a hard requirement.** Federation deliberately keeps authentication evidence with the authenticating party. If a regulator requires one continuous record of authentication and authorization across both organizations, that is a consolidation requirement wearing a federation costume. * **The partner identity provider cannot do SAML.** OpenIAM's inbound federation from a general external identity provider is SAML-based. If the partner offers only a proprietary integration, this design does not apply as written. * **The populations are tiny.** Federating for a few dozen people is a lot of trust configuration to maintain. Provisioned accounts in the receiving estate may be the proportionate answer. * **Neither side will commit to a stable identifier.** Without a durable mapping, translation has to be re-derived from mutable attributes, and it will break on the first name change. ## What OpenIAM does not do here * **There is no generic OpenID Connect relying-party integration for an arbitrary external identity provider.** OpenIAM acts as an OpenID Connect provider for applications, and as a SAML service provider for inbound federation; the shipped inbound provider types besides SAML are the named social and verification providers — Google, Facebook, LinkedIn, Apple, Criipto and Duo. Plan inbound federation from a partner organization as SAML. * **Federation does not synchronize anything.** If the identity has to exist on both sides — and for workforce federation it does — that is a separate feed you build. * **Just-in-time provisioning creates; it does not maintain.** A record created by a first sign-in is not updated or disabled by later events unless a lifecycle feed does it. * **A trust in one direction is not a trust in both.** Each direction is configured independently. * **OpenIAM does not route a request across a federation trust.** Requests stay with the catalogue that owns the application. ## Related * Part 5, *Cross-organization federation* — the decision in isolation, with the synchronization and just-in-time comparison in full. * [Coexistence with an incumbent IGA](/solution-architecture/reference-architectures/coexistence-with-incumbent-iga.md) — the governance half of the same situation. * *OpenIAM as a SAML identity provider*, *OpenIAM as a SAML service provider* and *Just-in-time provisioning* in the Administration Guide — the mechanisms behind this design. *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/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.