> 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/administration-guide/access/create-a-role.md). # Create a role Create a role on the shipped form, set its owner, parent and limits, and prove one test user gains the access before you activate it. ## What this is, and when you need it A role is OpenIAM's own container for a collection of access. It can hold users, other roles, groups, resources and organizations, it can span managed systems, and it is what you create when you want one name to mean "everything a payroll clerk needs". Create a role whenever the grouping is yours to define; create a **group** instead when the grouping already exists in a managed system. The rule of thumb is compose in roles, mirror in groups — see [The access model](/administration-guide/access/access-model.md). ## At a glance | | | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **You will end up with** | An inactive role with a name, owner, admin and contents, which one test user demonstrably holds and a non-member demonstrably does not | | **Where** | **Access Control → Role → Create New Role**, `/webconsole/editRole` | | **You need first** | The role type (`ACCESS_ROLE` or `PROVISION_ROLE`), a password policy to select, and a disposable test user | | **Takes** | 10–20 minutes, including the read-back and the one-user test | | **Reversible** | Partly — an empty role deletes cleanly, but once members exist and provisioning has run, removing the role deprovisions target accounts, and that is not always reversible | ## Before you begin * Decide the **type** now: the form asks before it asks anything else. It is a classification, not a behaviour switch — see [The access model](/administration-guide/access/access-model.md#what-the-role-type-actually-is). * Have a **password policy** to select. The drop-down is marked required on the form itself, not by the page template, so you cannot make it optional from **Page templates**. * Decide which mechanism will own the population. Pick one, before anyone is a member. ## Create the role {% stepper %} {% step %} ### Search for the name first **Access Control → Role**. Search the planned name across all statuses and all managed systems. Role names are unique per managed system: a collision fails the save with `Role name is already in use` (message key `openiam.ui.webconsole.role.name.taken`). Inactive roles count, and the search defaults do not include them, which is why this is step one. {% endstep %} {% step %} ### Choose the role type **Create new role** opens `/webconsole/editRole` with no parameters, which returns the `roles/selectRoleType` view listing the `ROLE_TYPE` metadata types. Pick `ACCESS_ROLE` or `PROVISION_ROLE`. Your choice is written to `ROLE.TYPE_ID` and is a classification only. {% endstep %} {% step %} ### Fill the template fields **Role Name** is the only required one. Set **Role Status** to something other than `ACTIVE` while you build — an inactive role is a checkpoint you can inspect, an active one is a change in behaviour. Set **Role Managed System** only if this role belongs to exactly one target. Leave it empty for a role that composes access across systems. **Max. User Number** is enforced when a membership is saved, not reported afterwards: once the role is full, OpenIAM drops the new membership from the request rather than warning about it, so the user is saved without the role. Decide who responds when the limit is reached before you set it, and verify by adding a member past the limit on a test role — the save succeeds and the membership is simply absent when you reopen the user. **Default Membership Duration** sets the default `endDate` offset for new memberships. Remember that nothing revokes on that date until `AUTO_REVOCATION` is enabled. Every field on this form, with its shipped required and editable flags, is in [Role and group field reference](/administration-guide/access/manage-roles-and-groups/role-and-group-reference.md#the-shipped-default-role-template). {% endstep %} {% step %} ### Set the parent, if any: now or never on this screen **Role Parent** appears only while the role has no ID — that is, on the create screen and never again. After the first save you manage parents from `/webconsole/roleEntitlements?id=` instead. Adding a parent grants the parent's whole content to every member of this role, so confirm that is what you want, and walk the parent's ancestors for a loop first. {% endstep %} {% step %} ### Set the owner and admin Use the **Role Owner** and **Role Admin** pickers. Neither offers organizations or roles as selectable types, so an owner or admin is a user or a group. The owner is business accountability; the admin is delegated operational authority. Both pickers open and save even though their template rows ship `IS_EDITABLE='N'`. That flag is not enforced for these two fields, so do not treat it as a control — see [the three non-editable rows](/administration-guide/access/manage-roles-and-groups/role-and-group-reference.md#the-three-non-editable-rows-and-what-really-happens). {% endstep %} {% step %} ### Leave the wide switches alone **Provision all users with this role** grants the role to the entire user population; on a role carrying a managed-system entitlement that is a mass provisioning event. It ships `false`. **Virtual tenant role** is the virtual-tenant visibility filter, not a job title — set it only if you are implementing that scoping model. Both are described in [Role and group field reference](/administration-guide/access/manage-roles-and-groups/role-and-group-reference.md#fields-on-the-role-form-that-are-not-in-the-template). {% endstep %} {% step %} ### Save and read it back On a successful create the browser is redirected to `editRole?id=` and the message is `Role was saved successfully` (message key `openiam.ui.webconsole.role.save.success`). Reopen the role and confirm the ID, status, type, managed system, owner and admin persisted — the redirect proves the row exists, not that every field on it is what you intended. {% endstep %} {% step %} ### Add contents, then test one user Open **Role entitlements** and add the child roles, groups and resources the design calls for. Then add one disposable user with a short end date, confirm the membership from both the role and the user, and confirm a non-member is still refused. Only then activate. {% endstep %} {% endstepper %} ## Verification | What to check | Where | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | The role exists with the intended type | Reopen `/webconsole/editRole?id=`; `TYPE_ID` is `ACCESS_ROLE` or `PROVISION_ROLE` | | The create was recorded | Audit action `CREATE_ROLE`; a later edit records `MODIFY_ROLE`; a clone records `CLONE_ROLE` | | Owner and admin persisted | Reload the role; the pickers repopulate with the saved user or group | | A member actually gains the access | The user's effective access, not the membership row — see [Search indexes and the authorization graph](/administration-guide/reference/search-indexes.md) | | The target received it | The provisioning request and connector reply, not the OpenIAM save | ## When it goes wrong | Symptom | Cause | Fix | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Role name is already in use` | A role of that name exists in the same managed system, possibly inactive | Search including inactive roles and across all managed systems; uniqueness is per managed system, not global | | A field this page mentions is missing | Its `UI_FIELD_TEMPLATE_XREF` row was deleted from `DEFAULT_RL_TEMPLATE` | **Administration → Page Template → Default Role Template**; compare against [the twelve shipped rows](/administration-guide/access/manage-roles-and-groups/role-and-group-reference.md#the-shipped-default-role-template) | | **Role Parent** is not on the form | You are editing an existing role; the field is create-only | Manage parents from `/webconsole/roleEntitlements?id=` | | Owner field is editable although the template says `IS_EDITABLE='N'` | The owner picker honours only `IS_REQUIRED` | Expected; the flag is not enforced for that field, so do not treat it as a control | | Save fails with "fill required fields" and nothing looks empty | `ROLE_PARTICIPATE_CERTIFICATION` ships `IS_REQUIRED='Y'` but renders no control | Set that xref's `IS_REQUIRED` to `N`, or delete the row | | Members exceed **Max. User Number** | The limit was raised, or memberships predate it | The limit rejects only *new* memberships; existing ones are never trimmed, so reduce the membership yourself | | The role grants nothing despite full contents | The role is excluded from authorization, or the authorization graph is stale | No screen shows the exclusion — read `ROLE.EXCLUDE_FROM_AUTH` as described in [the role field on neither the form nor the template](/administration-guide/access/manage-roles-and-groups/role-and-group-reference.md#the-role-field-on-neither-the-form-nor-the-template). If it is `'N'`, the graph is stale: [Rebuild the authorization graph](/administration-guide/operations/rebuild-the-authorization-graph.md) | | A new role appeared that you did not create | Creating a managed system auto-creates a role named after it, typed `PROVISION_ROLE` | Expected; it is the managed system's own role | ## Roll it back A role with no members, no contents and nothing referencing it deletes cleanly. Past that point, deletion is refused while another object still points at the role, and OpenIAM does not name the references it does not hold as memberships — a business-rule target, a certification campaign in flight, a request catalog entry or an SoD rule set. Clear those yourself first. If the role has already provisioned accounts, set its status inactive and remove the memberships deliberately rather than deleting it: deprovisioning is reversible only with consequences. See [Change configuration safely](/administration-guide/start/change-safely.md#reversibility-honestly). ## The routes, once you know your way around | Route | Behaviour | | --------------------------------------------- | ------------------------------------------------ | | `/webconsole/editRole` | No `id`, no `roleTypeId` → the type-chooser view | | `/webconsole/editRole?roleTypeId=ACCESS_ROLE` | New role of that type | | `/webconsole/editRole?id=` | Edit an existing role | | `/webconsole/compare-roles?id=` | Compare this role's contents against another | An `id` that does not exist returns 404 with the message `Role '' does not exist`, which is the quickest way to tell a deleted role from a role you cannot see. The membership and entitlement routes are in [Manage roles and groups](/administration-guide/access/manage-roles-and-groups.md#the-routes). ## Related * [Role and group field reference](/administration-guide/access/manage-roles-and-groups/role-and-group-reference.md) — every field on both forms, and what **Page templates** can and cannot change * [The access model](/administration-guide/access/access-model.md) — what the role type is and is not * [Manage roles and groups](/administration-guide/access/manage-roles-and-groups.md) — members, nesting, effective dates * [Role engineering and maintenance](/administration-guide/access/role-engineering.md) — building a catalog you can maintain, rather than one role at a time * [Enumerated values](/administration-guide/reference/enums.md) — the risk levels and statuses the drop-downs offer *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/administration-guide/access/create-a-role.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.