> 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/deployment/environments-and-tenancy.md). # Environments and tenancy How many environments a programme needs, what moves between them and what must never move — and when to use a virtual tenant, with what organization scoping does and does not isolate. ## What this is, and when you need it Two decisions that look unrelated and are not. **How many copies of OpenIAM does the programme need, and what moves between them?** And **can one copy serve several populations that must not see each other?** Both are answered by the same underlying fact: OpenIAM's configuration lives in its database, not in a build artefact, and there is no export and import of configuration objects. You need this page when the delivery plan is being written — environment count is a cost line and a lead-time item — and when someone asks whether subsidiaries, business units or customers can share one deployment. ## The decision | Decision | Options | What it costs | What it buys | | ----------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | Number of environments | Two, three, or more | Each is a full deployment with its own infrastructure | Somewhere to break things, and somewhere to rehearse an upgrade | | How configuration reaches an environment | Rebuilt by hand, or scripted rebuild | Scripting the rebuild is real effort | Repeatability. There is no import of configuration objects, so the alternative is manual work every time | | Isolation between populations in one deployment | Nothing, organization scoping, virtual tenant, or separate deployments | A separate deployment per population multiplies everything | Real isolation only at the separate-deployment end of that list | ## How many environments Three is the common answer and it is usually the right one, but the reasons matter more than the number. **Development.** Somewhere the integration work happens and things are allowed to break. The single-instance topology is built for this — and in a cloud, the single-node shape with platform services is better than the pure single-node shape, because the virtual machine holds nothing you cannot recreate. **Test or pre-production.** This is the environment that earns its cost, and its value comes entirely from *resembling production*. Same topology, same platform services, same connector placement, same managed system endpoints pointed at test targets. An environment that differs structurally from production tests the configuration but not the deployment, and the deployment is what breaks at three in the morning. **Production.** A fourth is worth having in two situations: an upgrade rehearsal environment, when the estate is large enough that upgrades need dress rehearsals; and a dedicated performance environment, when the batch profile is heavy enough that synchronization and reconciliation runs need somewhere realistic to be measured. On Kubernetes both are cheaper than they look — the shipped material includes a chart that creates a set of namespaces per environment, so several environments can share a cluster where the isolation requirement allows it. The constraint that decides the count is rarely licensing or compute. It is **connector targets**: a test environment is only useful if it has test instances of the managed systems to talk to, and for some enterprise applications those do not exist. Where a target has no test instance, decide early whether the environment integrates against production in read-only mode, against nothing, or against a stub — and record the decision, because a stub that survives into production is a familiar failure. ## What moves between environments, and what does not The governing fact is that **there is no export and import of OpenIAM configuration objects.** Promotion is a rebuild, and the work is in knowing which category each piece of configuration falls into. | Category | Examples | How it moves | | --------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | Configuration objects | Roles, groups, resources, managed systems, policy maps, approval flows, campaigns, business rules | **Rebuilt in each environment.** There is no object import | | Stored scripts | The Groovy that customizes synchronization, provisioning, federation and rules | Held in their own database schema; deployed as content, not promoted through a screen | | Files on disk | Property files, workflow definitions, locale overrides | Deployed with the release | | Property values | System configuration settings | Promoted as *values*, environment by environment. Many are environment-specific and must differ | | Secrets | Database and broker credentials, keystore passwords, connector credentials | **Never promoted.** Each environment has its own secrets store with its own values | | Schema | The migration trees | Applied by migration, per environment, per schema | | Images and packages | The release itself | Promoted by version, from a registry or a package repository | Three consequences shape a delivery plan. **Budget for the rebuild.** If configuration is rebuilt by hand in each environment, three environments means doing the work three times and keeping three copies consistent by discipline. On a large estate that is a real cost and it is usually underestimated. The mitigation is to script the rebuild, which turns a manual exercise into a repeatable one — and it also gives you a disaster-recovery asset, because the same script rebuilds a lost environment. **Never promote a secret, and never let one environment's credentials work in another.** Each environment gets its own secrets store and its own values. This is not only good practice; it is the control that stops a test environment provisioning into a production directory, which is the single most damaging mistake available in an identity programme. **Decide where images come from before the first environment is built.** The default is OpenIAM's own registry. Estates that cannot pull from the internet, or that require images to pass through their own supply chain, use a registry of their own, and the packaged Linux distribution has an equivalent — it can be installed from a local dependency bundle rather than from the internet. Both are supported; both change what promotion means, because every version bump becomes a copy into your registry or repository first. Deciding this late is what makes the first air-gapped environment take three weeks. The Administration Guide's *Promote configuration between environments* covers the mechanics from the administrator's side, including what verification to run afterwards. ## Multi-tenancy and organization scoping The second half of this page. The question arrives as "can we run one OpenIAM for all our subsidiaries?", and it has a precise answer. ### What a virtual tenant is OpenIAM has an organization-scoped filtering feature, controlled by a single system property, `org.openiam.virtual.tenant.enabled`, labelled **Activate virtual tenant by organization**. **It ships `false`.** When it is on, roles can carry one of three virtual tenant designations, and what an administrator can see is filtered by the organizations they belong to: | Designation | What the holder sees | | ---------------------------- | ------------------------------------------------------------------------ | | Super security administrator | Everything. Unfiltered | | Organization administrator | Only entitlements and objects in their own organizations | | End user | Only their own organizations, and only what an end user could see anyway | The filter applies across the administrative lists — users, groups, roles, resources, entitlements, managed system status and the tree views that hang off them. ### What it does not isolate in this release This is the part that has to be said plainly, because "multi-tenant" carries expectations the feature does not meet. **In this release the tenant scoping is applied when lists are assembled, not at the data layer.** There is one relational database, one entitlement graph, one search index set, one message broker, one set of connectors and one set of system properties. Tenants share all of it. Concretely, that means the following are **not** isolated by a virtual tenant: system configuration and property values, which are global; connectors and managed system definitions, which are shared; the search indices and the audit trail, which are common; scheduled and batch work, which runs for the deployment rather than per tenant; the message broker; and performance, since one tenant's bulk synchronization consumes the same platform everybody else is using. **And one trap worth naming.** With the property enabled, an administrator who is neither a super security administrator nor a holder of any virtual tenant role sees **empty lists** rather than everything. Turning the feature on in a running deployment without first assigning designations to every administrative role is a self-inflicted outage of the administrative console. Plan the role assignment before the switch, not after. ### Organization scoping without virtual tenancy Separately from the virtual tenant feature, OpenIAM's organization model already scopes what people see in the end-user experience, and two shipped settings are worth knowing when designing for several populations: * `org.openiam.selfservice.organization.search.enabled`, labelled **Restrict search to organization scope**, ships `false`. Turning it on confines a user's directory search to their own organization — usually what a multi-population deployment wants, and frequently missed. * `org.openiam.ui.selfservice.directory.lookup.skip.delegation.filter` ships `true`, meaning directory lookup does not apply the delegation filter by default. If your design assumes delegated administrators only ever see their own population in every screen, check this one. Neither is isolation in the security sense. They shape what a user is shown, on a platform where everything still lives together. ## What we recommend **Three environments, with the pre-production one built to the production topology.** Resist the temptation to save money by making pre-production structurally simpler; that is exactly the saving that costs you an outage. **Script the configuration rebuild from the start.** It converts a manual promotion into a repeatable one and doubles as a recovery asset. If you do nothing else in this area, do this. **Use a virtual tenant for administrative scoping inside a single trust boundary, and separate deployments where the isolation requirement is stronger than that.** It is the right answer when several business units administer their own populations within one organization's governance, and everyone concerned is inside the same trust boundary. State plainly that in this release it is a visibility filter applied when lists are assembled. **Use separate deployments when the isolation requirement is real.** Different legal entities, different data-residency obligations, different regulators, or a hosting arrangement where one customer's administrator must not be able to affect another's — none of these is met by a filter. Separate deployments are the honest answer, and they cost what they cost. **Assign virtual tenant designations to every administrative role before enabling the property.** The circumstance that changes this advice is a group structure where subsidiaries are administered centrally and the requirement is reporting separation rather than isolation. There, one deployment with organization scoping is the better answer, and the cost of separate deployments would buy nothing. ## What OpenIAM does not do here * **There is no export and import of configuration objects.** Promotion between environments is a rebuild, whether you do it by hand or script it. * **In this release a virtual tenant is not a data partition.** One database, one graph, one index set, one broker, one set of connectors, one set of properties. * **System properties are not per tenant.** Configuration set for the deployment applies to everybody in it. * **Connectors and managed systems are not per tenant.** A managed system defined in one organization's scope is served by the same connector processes as everyone else's. * **Audit is not partitioned by tenant.** The audit trail is common to the deployment. * **Enabling the virtual tenant property without assigning designations empties administrative lists** for every administrator who is not a super security administrator. * **There is no per-tenant performance isolation.** One population's bulk work is felt by all of them. ## Related * [Choosing a topology](/solution-architecture/deployment/choosing-a-topology.md) — the shape each environment is built to. * [Kubernetes topologies](/solution-architecture/deployment/kubernetes-topologies.md) — namespaces, registries and the declarative deployment path. * [Availability and recovery](/solution-architecture/deployment/availability-and-recovery.md) — why a scripted rebuild is also a recovery asset. * [Taking a new release](/solution-architecture/deployment/upgrade-strategy.md) — what the rehearsal environment has to prove before a release reaches production. * *Promote configuration between environments* in the Administration Guide — the mechanics of moving configuration between environments. * *Resources and organizations* in the Administration Guide — the organization model that scoping is built on. * *Scope a delegated administrator* in the Administration Guide — the other way to limit what an administrator can act on. * The [Installation Guide](/installation/installation.md) — building each environment, and the registry and repository options. *Applies to OpenIAM 2026.8.1. Last reviewed 13 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/deployment/environments-and-tenancy.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.