Roles assign members to groups in target systems. They exist inside Role models. You can create roles one at a time, or generate them in bulk using Role generators.

To get started, the recommended process is to Provision groups & manage memberships.

Each role comprises three parts:

  1. Name of the role

  2. User groups in one or more target systems

  3. User accounts in those target systems to be assigned as members in the groups

The purpose of roles is to manage security and entitlements in a controlled, simplified way. For example, in your organization you might have 10,000+ separate entitlements (application access, software licenses, accounts, file shares, permissions, etc) which are assignable to employees by means of group membership in your target systems. A NIM role consolidates multiple groups into a single object, so you can grant membership to all of them simultaneously. For this reason, the number of roles you create in NIM is always significantly fewer than the number of total groups in your target systems. To say it again, the purpose of roles is to simplify entitlement grants via group assignments.

How to design your role model is up to you. Many organizations use a simple 1:1 correspondence of roles to departments, and the tutorials in this documentation are based on this example. Another common design is one role per combination of variables. For example, in K-12 school settings, one role per combination of grades, classes, and buildings. These designs are best implemented with the help of a role generator.


The assignment of entitlements to user groups takes place in the target systems, not in NIM. The roles feature in NIM is strictly about managing the memberships of those groups. Entitlements are granted to users indirectly, through their group memberships.

Roles are executed via groupmembership-type operations in Jobs.

Use the Inspect roles tool to evaluate the current Development role model.

Group management

NIM provides two different ways to manage groups and group memberships in target systems:

  • Mappings: Create/update/delete groups

  • Roles: Manage group memberships in existing groups

The recommended workflow for most organizations is to use mappings to dynamically create/update/delete groups based on data in your HR system (e.g., departments), and roles to manage the memberships in those groups.

To get started, Provision groups & manage memberships.


Some system connectors support group membership mapping functions, to assign group memberships on a one-off basis. These are best used sparingly, for example, to manage memberships for <5 users and <5 groups. For managing a non-trivial number of group memberships, roles are far more efficient.

Additionally, do not attempt to manage memberships in a single group using both mappings and roles simultaneously. This will cause conflicts and provisioning errors. (See All-or-nothing management.)

All-or-nothing management

After you've added a group to at least one role and the role has been executed, NIM now manages that group on an all-or-nothing basis. Any user accounts assigned to the group by means other than a NIM role are removed. This includes accounts assigned to the group via the system's own administration portal. It also includes any groups and/or memberships created with NIM's mapping functions (see Group management). This removal process is repeated every time the role is executed.

Thus, for each target group, you must decide whether or not NIM will manage it via roles. For groups that NIM will manage, you must:

  • Configure the role's filter to include all necessary users.

  • No longer manage the group's memberships by any other means than NIM roles.

For Active Directory target systems, you should avoid using NIM to manage built-in groups such as Administrators, Backup Operators, Domain Admins, etc.