===== Business roles =====

{{ :devel:documentation:business_01.png|}}

Business role (role composition) is a role which does not (only) grant permissions by itself, but groups other roles together. Roles contained in a business role are called **sub roles**. When a business role is assigned to an owner (identity, account, ...), all its sub roles are assigned automatically as one logical unit - the owner does not have to request each sub role separately.

Business roles are defined on the role detail. Any role can become a business role just by adding at least one sub role to it - there is no special "business role" flag. A single role can be a superior role (contains sub roles) and a sub role of another role at the same time, so business roles can form a hierarchy (tree) of an arbitrary depth.


==== Terminology ====

  * **Superior role** - the role which contains other roles (the business role itself).
  * **Sub role** - a role contained in a superior role by a composition.
  * **Role composition** (''IdmRoleComposition'') - one edge in the tree: a link superior role => sub role. Business role definition is the set of its compositions.
  * **Direct role** - the assignment which was requested explicitly (by a user, automatic role, synchronization, ...). Direct role has an empty ''directRole'' attribute.
  * **Assigned sub role** - the assignment created automatically from a composition. It has the ''directRole'' attribute filled with the id of the direct (superior) assignment it was derived from, and the ''roleComposition'' attribute filled with the composition it came from. This is how the system distinguishes an assignment which is a consequence of a business role from an independent assignment.

==== Assignment ====

When a business role is assigned to an owner, the business role and all its sub roles are resolved and assigned within a single **role request**:

  * Sub roles are expanded **recursively** - if a sub role is itself a business role, its own sub roles are assigned too.
  * Since version 10.6.0 sub roles are always processed as a part of the role request. The older ''IdentityRoleAssignSubRolesProcessor'' is deprecated and not used anymore (it assigned sub roles directly, outside of a role request).
  * Each assigned sub role has the same **validity** (valid from / valid till) as the direct role it was derived from.
  * Each assigned sub role keeps a reference to its direct role (''directRole'') and to the composition it came from (''roleComposition''). It is shown in the assigned roles agenda in the column **Assigned by role**.

==== Updating ====

When the validity (valid from / valid till) of an already assigned business role is changed, the change is propagated to its assigned sub roles - they are recalculated to the same validity.

==== Removal ====

{{ :devel:documentation:business_02.png|}}

When an assigned business role (direct role) is removed from an owner, all its assigned sub roles are removed automatically too (cascade by ''directRole''). An assigned sub role can not be removed on its own - it can be removed only together with its direct role.

If the same role is assigned both directly (independently) and as a sub role of a business role, the two assignments are independent - removing the business role removes only the assignment created from the composition (''directRole'' filled), the independent assignment (''directRole'' empty) stays. See also the duplicate assignments edge case below.

==== Changing business role definition ====

Sub roles are recalculated on the background by [[devel:documentation:application_configuration:dev:scheduled_tasks:task-scheduler#addnewrolecompositiontaskexecutor|long running tasks]] when the business role definition is changed, for **all owners** which already own the business (or any superior) role:

  * **Adding** a new composition - ''AddNewRoleCompositionTaskExecutor'' assigns the newly added sub role to all owners which already own the superior (business) role.
  * **Removing** a composition - ''RemoveRoleCompositionTaskExecutor'' removes the sub roles assigned by that composition from all owners; the composition (''IdmRoleComposition'') is deleted only after all the assigned sub roles are removed.

==== Approval ====

Only the assignment of the **direct role** (the main business role itself) goes through the approval process. The sub roles derived from the business role are assigned (and removed) automatically as a consequence of the direct role, without a separate approval. The same applies to removal - the approval is driven by the business role, the sub roles follow automatically.

==== Business roles and other owners (accounts) ====

Roles - including business roles - can be assigned not only to identities (through an identity contract) but also directly to an **account** (''AccAccountRoleAssignment''), and generally to any assignable owner (for example a technical account).

The business role mechanics are the **same** for all owner types:

  * assigning a business role to an owner assigns all its sub roles to the **same owner**,
  * sub roles inherit the validity and keep the ''directRole'' / ''roleComposition'' references,
  * removing the business role removes the assigned sub roles (cascade),
  * a change of the business role definition (adding / removing a composition) is recalculated for all owners which already own the business role.

=== System mapping rule ===

An account is always created on a concrete system. Therefore only roles which **map that system** can be assigned directly to the account - roles which do not map the account's system are not offered (this is the standard product behaviour).

For a business role this rule applies to the **assigned (direct) business role only** - the top business role you assign to the account must map the account's system. Its **sub roles do not have to map the same system**. As a result a business role can pull in sub roles which map a different system, no system at all, or only grant permissions (see the edge cases below).

==== Edge cases ====

=== Sub roles which do not affect an account ===

Because a business role may contain sub roles that are unrelated to the account's system, some sub roles assigned to an account have **no effect** on that account. They are still recorded as account role assignments (for consistency and for a correct removal), but they do not trigger any provisioning, they do not create any additional account and they do not influence the account in any way.

Example: an account is created on the system **AD** and the business role **Developer** (which maps AD) is assigned to that account. Among its sub roles there can be:

  * **GitLab - developer** - maps a **different** system (GitLab). It has no effect on the AD account - no GitLab account is created from this assignment and the AD account is not influenced.
  * **Company employee** - maps **no** system (it is only a container / business role grouping general onboarding roles). It has no effect on the account.
  * **IdM - report reader** - grants **only IdM permissions**. It has no effect on an account. IdM permissions (authorization inside IdM) are evaluated **only for identities** - you can not sign in to IdM as an account, so there is nothing to evaluate. This is about IdM authorization only. Entitlements provisioned to a target system (for example an AD group membership set through a system mapping) are **not** IdM permissions and are delivered to the account normally - provided the role maps the account's system.

In all these cases the assignment itself is created and correctly removed together with the business role - only the provisioning / effect on the account does not happen.

=== Duplicate assignments ===

A business role does not deduplicate the roles it pulls in. If the same role is reached more than once, it is assigned (and shown in the assigned roles agenda) more than once:

  * the same role is a sub role on **more than one branch** of the same business role tree, or
  * the role is assigned **directly** and at the same time it is a sub role of an assigned business role.

Example tree - business role **Developer**:

  * ''Developer -> Backend developer''
  * ''Developer -> Frontend developer''
  * ''Backend developer -> Database access''
  * ''Backend developer -> Git repository access''
  * ''Frontend developer -> Git repository access''
  * ''Frontend developer -> CI/CD access''

Assigning **Developer** assigns Backend developer, Frontend developer, Database access, CI/CD access and **Git repository access twice** - once through Backend developer and once through Frontend developer.

The same happens when a role is assigned on top of a business role which already contains it - for example assigning **Git repository access** directly to an owner which already has **Developer** creates another assignment next to the one derived from the business role. When assigning to an **account**, this directly assigned role must map the account's system (see the system mapping rule).

IdM does not merge these assignments automatically on assignment. A separate [[devel:documentation:roles:dev:identity-role-deduplication|deduplication]] feature can detect and remove duplicates, but two sub roles coming from different compositions are not treated as duplicates of each other (only assignments with the same ''directRole'' and the same ''roleComposition'' are).

=== Incompatible roles ===

Incompatible roles are resolved across the **whole business role tree**. If a business role - directly or through any of its sub roles - pulls in two roles which are defined as mutually incompatible, the incompatibility is reported (warning). The evaluation expands the business role and checks all its sub roles, not only the directly assigned roles.

=== Circular composition ===

A cycle in the business role definition can not occur. When a new composition is created, it is validated (''checkCircularDependency'') and a composition which would introduce a cycle (for example ''A -> B -> A'') is rejected. A duplicate composition edge (the same superior => sub link) is prevented as well.

=== Invalid direct role ===

Because sub roles inherit the validity of their direct role, an invalid (for example expired or not yet valid) business role also has invalid sub roles. Invalid assignments are not provisioned - the effect on the account is applied only while the assignment is valid.