> 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/identity/populations.md). # Designing for every population Design for every population the estate actually contains — employees, contractors, seasonal returners, contractor-to-employee conversions, partners, customers and non-human identities — on the basis t ## What this is, and when you need it A population is a group of people whose identity behaves differently: a different authoritative source, a different joiner event, a different end condition, a different set of birthright access, sometimes a different authentication design. This page is about naming all of them before the build starts, and about the transitions between them — which are where identity programmes actually fail. You need it at the point where someone says "we'll do joiners, movers and leavers". That sentence describes about sixty per cent of the events a large estate produces. The rest are mutations: a contractor who becomes an employee, a seasonal worker who returns for the fourth year, a person who transfers between subsidiaries with different HR systems, an employee on long-term leave whose access must be suspended but not destroyed. ## The position this page starts from **Lifecycle mutations are the norm, not the exception.** A design that handles joiner and leaver cleanly and treats everything else as an edge case will not survive contact with a hundred-thousand-person workforce. Conversions and returns are not rare events at that scale; they are a continuous stream, and they are the events that produce duplicate identities, orphaned access and missed terminations. The practical consequence is that the design has to answer, for every pair of populations, *what happens to a person who moves between them* — before it answers what a request form looks like. ## The decision | Population | Authoritative source | The end condition | The trap | | --------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------- | | **Employees** | The HR system for their organization | A termination date from HR | Multiple HR systems disagreeing about the same person after a transfer | | **Contractors and agency staff** | A contractor or vendor register, or OpenIAM itself with a sponsor | A mandatory end date, extended only by an explicit act | No end date, so the account outlives the contract | | **Seasonal and returning workers** | The same source as the population they return into | End date each season; the identity persists, the access does not | A returner matched as a new joiner, producing a second identity | | **Contractor-to-employee conversions** | Authority moves from one source to another on a known date | Not an end condition — a change of authority | The old source terminating the person after the conversion | | **Partners and external collaborators** | The partner organization, through a federation trust or a sponsored record | The sponsorship or the trust ending | Nobody owns the review, because the person is not anybody's employee | | **Customers and consumers** | Self-registration, or the customer system of record | The account being closed or going dormant | Applying a workforce lifecycle to a population that has none | | **Non-human identities** | The team that requested it, with a named human owner | The service being decommissioned, or the owner disowning it | The owner leaves and the account has no owner and no end | ## Statuses and what they are for OpenIAM's user status vocabulary is deliberately larger than active and terminated — it includes states for people who are on leave with pay, on a leave of absence, retired, deceased, pending a start date, pending deactivation and pending deletion, among others. Use that vocabulary rather than compressing everything into two states, because **the status is what drives the access decision** and the states genuinely differ. A person on parental leave should usually keep their identity, lose interactive access, and retain their entitlement record so that it can be restored intact. A person who has left should lose access and retain an auditable record. A person with a future start date should exist, hold their birthright access in a pending form, and be unable to sign in until the date. Collapsing those into "disabled" makes the return from each of them a manual rebuild. Two design rules follow: **Decide the access consequence of every status you intend to use**, in a table, before the first lifecycle rule is written. A status with no defined consequence is a status that will be set and ignored. **Distinguish suspending access from ending an identity.** They are different operations with different reversibility, and conflating them is what makes a returner expensive. ## The mutations, one at a time ### The seasonal returner Someone works a season, leaves, and comes back eleven months later. Whether that is cheap or expensive is decided by one thing: **does the returning record correlate to the identity that already exists?** If the correlation key is the enterprise workforce identifier and the person keeps it across seasons, the return is an update: the same identity, reactivated, with new entitlements granted for the new season. History is intact, the audit trail is continuous, and last season's access is visibly revoked rather than mysteriously absent. If the source issues a new number each season, or the key is a username or an email address, the return is a new identity. The person now has two, and the old one holds whatever access was never cleaned up. Do that four years running and the estate contains four identities and three sets of stale entitlements for one person. So the seasonal design is a Part 2 decision made in [Choosing the enterprise unique identifier](/solution-architecture/identity/unique-identifier.md), not a lifecycle feature. What belongs here is the retention rule: **how long an inactive identity is kept before it is removed**, and the fact that removing it too early converts every returner into a duplicate. Set that retention from the longest realistic gap, not from a storage argument. ### The contractor who becomes an employee The hard part is not the type change. It is that two sources now describe the same person, briefly, and one of them is about to say they left. The design has to state four things: the date authority moves; what the old source is told to stop asserting; what happens to the existing accounts; and what happens to the existing access. On accounts and access, take a position deliberately rather than by default. **Keeping the same accounts** preserves the person's working life — the same mailbox, the same profile, the same history — and is what users expect. **Replacing them** gives a clean employee record and satisfies an auditor who wants the contractor relationship visibly closed. Regulated estates often need the second and get the first by accident. OpenIAM supports a conversion operation that changes a user's type, records a conversion date and can merge a second record's access into the target in the same transaction. Two properties of it belong in the design: the merge is a script you write, because "which of the contractor's access should an employee keep" is a question only your organization can answer; and **the shipped script does nothing** — with it in place, conversion changes the type and merges no access at all. A design that assumes access carries across will get a type change, no access and a success message. ### The transfer between subsidiaries The same shape as a conversion, with an extra failure mode: the person moves from one HR system to another, and the two systems use different identifiers. If the enterprise identifier travels with the person, this is a change of organization on one identity. If it does not, the person leaves one organization and joins another — access revoked, access re-granted, history broken, and an enterprise view that shows two people. This is the case that most often forces an organization to mint its own identifier, and it is worth walking through explicitly in a design review with a real example. ### Long-term leave, and the states in between Leave is the population everyone forgets. Suspend interactive access, retain the identity, retain the entitlement record, and define the return. Do not revoke entitlements on the way in unless the regulatory position demands it, because restoring them is manual and will be done wrong. ## Partners, customers and the boundary of the workforce model Two populations do not belong in the workforce lifecycle, and forcing them in is a recognisable design smell. **Partners** are other organizations' employees. The strong pattern is federation: the partner organization authenticates them, and your estate governs only what they may reach. Their joiner and leaver events happen somewhere you cannot see, which is exactly why a sponsored end date and a periodic re-attestation by an internal owner are not optional. Where federation is not available, a sponsored identity with a mandatory end date is the fallback, and it is the same design as a contractor. **Customers** have no manager, no HR record and no termination date, and their volume is an order of magnitude larger. Self-registration, self-service profile management and a dormancy rule replace the joiner–mover–leaver model entirely. Where consumer identity is genuinely in scope, treat it as a separate design with its own authentication policy, not as a workforce population with different attributes. Where several partner organizations or customer segments must be kept from seeing each other, OpenIAM can scope visibility by organization — a virtual-tenant mode that ships disabled and has to be a deliberate architectural choice, because it changes what every administrator can see. **Non-human identities** are covered in [One person, many accounts](/solution-architecture/identity/one-person-many-accounts.md). The population point is only this: count them. In most estates there are more of them than anyone expects, and they are the population with no natural end condition at all. ## What we recommend **Enumerate the populations first, and give each one a named source, a named end condition and a named owner.** A population with no end condition is a finding waiting to happen. **Design the transitions, not just the states.** For every pair of populations that people actually move between, write down what happens to the identity, the accounts, the access and the authority. In a large estate that is four or five transitions, and they are worth a workshop each. **Make the identity survive the mutation.** One person, one identity, across seasons, conversions and transfers. This is a restatement of the correlation-key decision, and it is the single control that makes every mutation cheap. **Set inactive-identity retention from the longest realistic return gap**, and state it. Deleting too early manufactures duplicates. **Give every non-employee population a mandatory end date and a sponsor**, and re-attest rather than extend silently. **Keep customer identity out of the workforce design.** If it is in scope, it is a second design. The circumstance that changes this advice is an organization with one employee population, no contractors and no seasonality — in which case the joiner–mover–leaver model really is sufficient, and this page costs you an hour to confirm it. ## What OpenIAM does not do here * **The shipped user-type conversion script merges nothing.** Conversion changes the type, stamps a conversion date and reprovisions; carrying access across is a script you write. * **There is no automatic re-hire or return detection.** A returning person is matched by the ordinary correlation rule, or not at all. Nothing in the product notices that a new record resembles a former identity. * **There is no product concept of a population.** Populations are user types, organizations and attributes that you define and then use consistently; the product will not stop you from mixing them. * **A status change does not carry an access consequence by itself.** What happens when a person moves to a leave status is a lifecycle rule you configure, not a shipped behaviour. * **Nothing enforces an end date on a non-employee identity.** Making it mandatory is a design and configuration decision, and an identity created without one will simply not expire. * **Virtual tenancy by organization ships disabled**, and turning it on changes visibility for every administrator — it is an architectural choice, not a per-population toggle. ## Related * [Choosing your authoritative sources](/solution-architecture/identity/authoritative-sources.md) — the source each population needs. * [Choosing the enterprise unique identifier](/solution-architecture/identity/unique-identifier.md) — the decision that makes returns and conversions cheap. * *Convert a user's type* and *Run a user lifecycle action* in the Administration Guide — the operations behind the mutations described here. * Part 5, *Lifecycle events across a governance boundary* — what these transitions look like when two platforms are live at once. *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/identity/populations.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.