> 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/governance/role-model.md). # Designing the role model Which OpenIAM object should carry which idea — role, group, organization or resource — how deep a hierarchy is defensible, when not to build a role at all, and what designing a catalogue costs in a re ## What this is, and when you need it Every IGA programme is asked, early and by someone senior, "how many roles will there be?". The honest answer depends on a decision nobody has made yet: **which of OpenIAM's four container objects carries which idea in your estate.** Role, group, organization and resource can all hold users, and a design that uses them interchangeably produces a catalogue that cannot be reviewed, cannot be certified meaningfully, and grows without limit. This page is that decision, plus the two that follow from it: how deep the hierarchy is allowed to go, and when the right answer is not to build a role at all. It is not a description of the objects — *The access model* in the Administration Guide is, and it is the better place to learn what each one is. This page is about applying them to an estate that already exists. You need it before anyone opens a spreadsheet of proposed role names. Role catalogues are cheap to propose and expensive to converge, and the convergence work lands on whoever inherits the design. ## The decision | Object | Carry this in it | Do not carry this in it | What it costs you | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | **Role** | An access bundle: a job, a responsibility, or a named permission in one target system. The only object that can span managed systems and contain the others | Reporting structure, or a person | Design effort. Every role needs an owner, a risk rating, a description a reviewer can read, and a decision about which mechanism populates it | | **Group** | Membership that a managed system itself enforces as a group, so that a membership in OpenIAM can become a real directory membership | A bundle that has no counterpart in a target. If the target has no group concept, you do not need a group | One-to-one coupling with a target's own model, which is a maintenance dependency on that target | | **Organization** | Company, subsidiary, division, department — and delegated administrative scope. Four organization types ship, and the product enforces which may contain which | A substitute for a role. An organization is where somebody sits, not what they may do | Affiliations propagate up the hierarchy by default, so an entitlement attached to a parent reaches more people than the org chart suggests | | **Resource** | The protected thing: an application, a URI pattern, a menu entry, a managed system, an OAuth scope | Organizational hierarchy | Resource types differ in whether they may be nested at all, so a hierarchy you assume is available may be refused | **Compose in roles; mirror in groups; place in organizations; protect resources.** That single sentence resolves most of the arguments a design review will have, and it is worth putting in the design document verbatim. ### Roles versus groups is not a size question The distinction people reach for — business meaning in roles, technical detail in groups — is not what the product implements. The real line is **who owns the concept**. A directory group exists because the directory has it; when the directory renames it, your model has to follow. A role exists because you decided it does, and it can contain groups, resources, organizations and other roles across as many target systems as you like. That makes the practical rule easy: a group that exists only to be a container, with no counterpart in a target system, is doing a role's job badly. Collapse it. ### The two-layer catalogue is a convention, not a feature Most designs end up with outer roles named for responsibilities containing inner roles and groups named for target permissions. This is a good convention and you should use it. **It is not something OpenIAM implements.** There is no business-role object and no technical-role object; the role type field is a classification you can search and report on, not a behaviour switch, and nothing in the product treats the two layers differently. The design consequence is that the layer has to be expressed in things the product actually stores and searches — whether the role is associated with a single managed system, its owner, its risk rating, its description, and consistent use of the type as a label. Do that, and your reports mean something. Skip it, and the two-layer catalogue exists only in the document that proposed it. ## How deep a hierarchy Roles nest. Groups nest. Organizations nest, with typed constraints. The depth question is answered differently for each, and only one of the three is enforced. **Roles and groups have no depth limit and no meaningful cycle protection.** The product refuses a role that is made its own direct child; it does not detect a longer loop, and it does not cap depth. Depth discipline is entirely yours to impose, and nothing will warn you when it has been lost. **Two levels is the working answer, three is the outside limit.** The constraint is not technical, it is a reviewer's. Inheritance is a real access change: every parent you add grants its entire content to every existing and future member of the child. A reviewer presented with a three-level chain is being asked to approve access they cannot see from the object in front of them, and they will approve it anyway — which is the failure mode that makes deep catalogues worse than no catalogue. **Prefer containment to inheritance.** A role that contains three reusable roles is legible; a role that inherits from a chain of three parents is not, even though the effective access may be identical. The difference matters only when somebody has to attest to it, which is precisely the moment you built the catalogue for. **Organizations are the exception, and the depth is given to you.** The shipped organization types are organization, subsidiary, division and department, and the product enforces which type may sit inside which — an organization may contain any of the other three, a subsidiary may contain a division, and a division may contain a department. That is a three-or-four-level structure with the semantics already decided, which is a good reason to put the org chart in organizations rather than modelling it as roles. One consequence of that structure is worth knowing before you condition anything on it: **affiliation propagates upward by default.** A person affiliated to a department under a division is treated as affiliated to the division and the organization above it, automatically, because automatic hierarchy assignment ships enabled. That is usually what you want. It also means an entitlement attached high in the tree reaches everybody underneath it, and a rule that matches on a parent organization matches people nobody ever placed there. ## When not to build a role Four cases come up in every programme, and in all four the role is the wrong answer. **When the population is one person.** A role per individual is a spreadsheet with extra steps. If the access is genuinely personal, grant it directly with an end date and a documented reason; if it is attribute-driven, express the attribute in a rule over one shared role. A catalogue that has grown a role per person does not need a deeper hierarchy — it needs the exception mechanism it never built. **When the role would mirror exactly one group in exactly one target.** You already have the object. Use the group, and reach for a role when something has to span systems or carry meaning the target does not have. **When it encodes the org chart.** Department membership is an organization affiliation. Turning it into a role duplicates a structure that already exists, and the two versions diverge within a quarter. **When nobody will own it.** An unowned role cannot resolve a certification reviewer, cannot route an approval, and cannot be defended when someone asks why it exists. If no named person will accept accountability for the role at design time, the role is not ready, and creating it anyway simply moves the problem to the first campaign. ## What designing a catalogue actually costs This is the part most often left out of a plan, and it is the reason to state a limit plainly: > **This release does not include role mining or clustering.** Nothing in the 2026.8.1 product examines who currently holds what and proposes candidate roles, and there is no screen that discovers a catalogue from observed entitlement patterns. The catalogue in a 2026.8.1 design is therefore built from analysis rather than proposed by the product, and the analysis has to be budgeted for. That is a limit worth carrying into a design conversation rather than discovering during delivery, because it decides how the work is done. **Role design in OpenIAM is manual, iterative and evidence-driven**, and the design has to budget for all three words. *Manual* means somebody writes the catalogue. It arrives as a structured file with the owner, the admin, the approvers, the risk and the duration on each line, and it is loaded rather than hand-typed — which also gives you a version-controlled artefact of the design, which the product does not otherwise keep. There is no role versioning and no approval-of-design workflow: the role record is mutable and the audit log is its only history, so the file you imported from *is* your design history. *Evidence-driven* means the catalogue is proposed from measurements of the current state, not from job descriptions. The shipped entitlement and membership reports tell you which roles have no members, how access is currently being granted, and where the estate has drifted. If you want bottom-up discovery, export that data, cluster it in whatever tool your analysts already use, and load the result back — this release will not do the clustering for you, but it will happily consume the answer. *Iterative* means the first catalogue is wrong and the plan must survive that. Convergence — finding near-duplicate roles, deciding which survives, moving members, retiring the loser — is real, recurring work. The product helps: it can compare two roles and show what each holds that the other does not. It compares **two at a time**, on roles you nominate; there is no catalogue-wide duplicate sweep. Narrowing the candidate pairs is your job, which is another reason the measurement above comes first. ## What we recommend **Write the object mapping down before the first role exists.** One sentence per object, in the design document, agreed by everyone who will create objects. Most catalogue decay traces back to this never having been agreed. **Two levels, three at the outside, and prefer containment.** Justify any exception in terms of what a reviewer will see, not in terms of elegance. **Put the org chart in organizations, and know that affiliation propagates upward.** Then condition on the specific unit you mean, not on an ancestor. **Require an owner and a risk rating at creation time.** These are the two fields the rest of Part 4 depends on: certification reviewer resolution needs the owner, and a catalogue where every role is unrated produces a risk report that says nothing. **Load the catalogue from a file, and keep the file.** It is your design record, your promotion artefact between environments, and the only versioned form the design will ever have. **Budget the role-design effort explicitly, as analysis work, in the plan.** Because this release proposes no candidate roles for you, this is a workstream with people on it — not a configuration task that follows installation. The circumstance that changes this advice is an estate with no stable job structure: a research organization, a project-based business, a population that is mostly contractors on short engagements. There, a large role catalogue will never converge, and the better design is a small set of birthright roles plus a strong request-and-approval path with end dates. Say so early; a role catalogue proposed for a population that does not have roles is a programme that fails slowly. ## What OpenIAM does not do here * **This release does not include role mining or clustering.** No candidate roles are proposed from observed access, on any screen. * **There is no catalogue-wide duplicate detector.** Role comparison is pairwise and you supply both roles; sweeping a catalogue means choosing the pairs yourself. * **There is no business-role or technical-role object.** The two-layer catalogue is a convention you impose and express in fields the product stores. * **There is no depth limit on roles or groups, and no deep-cycle check.** Only a role made its own direct child is refused. A longer loop is not detected. * **There is no role versioning and no design-approval workflow.** The role record is mutable; its history is the audit log and the file you imported from. * **Role attributes are not shown to a reviewer.** Anything a reviewer must read in order to decide belongs in the role's name and description, not in metadata attached to it. ## Related * [How access gets granted](/solution-architecture/governance/how-access-is-granted.md) — the mechanism that populates each role you decide to build. * [Designing a certification programme](/solution-architecture/governance/certification-programme.md) — why owners and descriptions are load-bearing. * *The access model* and *Role engineering and maintenance* in the Administration Guide — the objects, and the tools for converging a catalogue. * Part 2, *Designing for every population* — the populations a catalogue has to cover, including the ones that do not have jobs. *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/governance/role-model.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.