# RoleType (Complex Type)

### Namespace: http://midpoint.evolveum.com/xml/ns/public/common/common-3

Supertype: AbstractRoleType

A role in the extended Role-Based Access Control (RBAC) sense. The roles specify privileges that the user (or other object) should have.

The role may "grant" accounts on resources, attributes and entitlements for such accounts. The role can also assign organizational units, other roles or various IDM objects that can be assigned directly to user. From this point of view the role is in fact just a named set of assignments.

The roles form the basic building block of midPoint's extended role-based access control (RBAC) mechanism. It defines what rights (e.g. accounts) should be given to user, how they should look like (attributes) and what groups or native roles to assign to them (entitlements).

Roles can also specify user authorizations to access specific parts of midPoint. This is used to implement fine-grained authorization mechanism. When combined with organizational structure it forms a delegated administration mechanism.

Roles can also be conditional, i.e. applicable only if a specific condition is true. Roles can be parametric, e.g. the expressions inside the role can use parameters that were specified at the time when the role was assigned (as opposed to parameters defined when the role was defined).

Item Summary
Name | Type | Multiplicity | Description
--- | --- | --- | ---
name | property PolyStringType | [0,1] | Human-readable, mutable name of the object.
description | property string | [0,1] | Free-form textual description of the object.
documentation | property string | [0,1] | AsciiDoc-formatted technical documentation of the object.
subtype | property string | [0,-1] | Type of the object.
fetchResult | property OperationResultType | [0,1] | Result of the operation that fetched this instance of the object.
extension | container ExtensionType | [0,1] | Extension container that provides generic extensibility mechanism.
parentOrgRef | reference ObjectReferenceType | [0,-1] | Set of the orgs (organizational units, projects, teams) that the object relates to.
trigger | container TriggerType | [0,-1] | Triggers for this object.
metadata | container MetadataType | [0,1] | Meta-data about object creation, modification, etc.
tenantRef | reference ObjectReferenceType | [0,1] | Reference to the tenant to which this object belongs.
lifecycleState | property string | [0,1] | Lifecycle state of the object.
operationExecution | container OperationExecutionType | [0,-1] | Description of recent operations executed on this object (or related objects in special cases).
lensContext | container LensContextType | [0,1] | Model context describing executed operation
policySituation | property anyURI | [0,-1] | The policy situation(s) of this object.
triggeredPolicyRule | property EvaluatedPolicyRuleType | [0,-1] | Triggered policy rules for this assignment.
policyException | container PolicyExceptionType | [0,-1] | Recorded exception from a policy rule.
diagnosticInformation | property DiagnosticInformationType | [0,-1] | Diagnostic information attached to this object.
indestructible | property boolean | [0,1] | Protection againts accidental deletion.
assignment | container AssignmentType | [0,-1] | Set of object's assignments.
iteration | property int | [0,1] | Iteration number.
iterationToken | property string | [0,1] | Iteration token.
archetypeRef | reference ObjectReferenceType | [0,-1] | References to all applicable archetypes, including "indirect" archetypes such as archetype supertypes.
roleMembershipRef | reference ObjectReferenceType | [0,-1] | References to abstract roles (roles, orgs, services) that this focus currently belongs to - directly or indirectly.
delegatedRef | reference ObjectReferenceType | [0,-1] | References to objects (abstract roles as well as users) obtained via delegation.
roleInfluenceRef | reference ObjectReferenceType | [0,-1] | References to abstract roles (roles and orgs) that this focus may directly belong to.
linkRef | reference ObjectReferenceType | [0,-1] | Set of shadows (projections) linked to this focal object.
personaRef | reference ObjectReferenceType | [0,-1] | Set of personas linked to this focal object.
activation | container ActivationType | [0,1] | Type that defines activation properties.
jpegPhoto | property base64Binary | [0,1] | Photo corresponding to the user / org / role.
costCenter | property string | [0,1] | The name, identifier or code of the cost center to which the user belongs.
locality | property PolyStringType | [0,1] | Primary locality of the user, the place where the user usually works, the country, city or building that he belongs to.
preferredLanguage | property string | [0,1] | Indicates user's preferred language, usually for the purpose of localizing user interfaces.
locale | property string | [0,1] | Defines user's preference in displaying currency, dates and other items related to location and culture.
timezone | property string | [0,1] | User's preferred timezone.
emailAddress | property string | [0,1] | E-Mail address of the user, org.
telephoneNumber | property string | [0,1] | Primary telephone number of the user, org.
credentials | container CredentialsType | [0,1] | The set of focus's credentials (such as passwords).
behavior | container BehaviorType | [0,1] | General-purpose behavioral data.
displayName | property PolyStringType | [0,1] | Human-readable name of the role or org.
identifier | property string | [0,1] | Identifier of the role or org.
inducement | container AssignmentType | [0,-1] | Inducements define the privileges and "features" that other objects should have.
authorization | container AuthorizationType | [0,-1] | Set of role authorizations.
requestable | property boolean | [0,1] | If set to true then this role may be directly requested by the users.
delegable | property boolean | [0,1] | If set to true then this role may be delegated to a deputy.
idempotence | property IdempotenceType | [0,1] | This value indicates whether the evaluation of this role gives the same results regardless of its position in the assignment/inducement hierarchy.
riskLevel | property string | [0,1] | Indication of the level of risk associated with the permissions that this role assigns.
condition | container MappingType | [0,1] | The role is applied only if the condition is evaluated to true.
adminGuiConfiguration | container AdminGuiConfigurationType | [0,1] | Specifies the admin GUI configuration that should be used for the members of this role.
dataProtection | container DataProtectionType | [0,1] | Specifies the GDPR related attributes
autoassign | container AutoassignSpecificationType | [0,1] | Specification of role auto-assignment properties.
roleType | property string | [0,1] | Type of a role, usually denotes a "layer" or "purpose" of the role.

- ### Items

  - #### name

    Flags: RAM,runtime

    Multiplicity: [0,1]

    Human-readable, mutable name of the object. It may also be an identifier (login name, group name). It is usually unique in the respective context of interpretation. E.g. the name of the UserType subtype is usually unique in the whole system. The name of the ShadowType subtype is usually unique in the scope of resource (target system) that it belongs to.

    The name may not be human-readable in a sense to display to a common end-user. It is intended to be displayed to IDM system administrator. Therefore it may contain quite a "ugly" structures such as LDAP DN or URL.

    Name is mutable. It is considered to be ordinary property of the object. Therefore it can be changed by invoking usual modifyObject operations. However, change of the name may have side effects (rename process).

    Although name is specified as optional by this schema, it is in fact mandatory for most object types. The reason for specifying the name as optional is that the name may be generated by the system instead of supplied by the clients. However, all objects stored in the repository must have a name.

  - #### description

    Flags: RAM,runtime

    Multiplicity: [0,1]

    Free-form textual description of the object. This is meant to be displayed in the user interface.

  - #### documentation

    Flags: RAM,runtime

    Multiplicity: [0,1]

    AsciiDoc-formatted technical documentation of the object.

  - #### subtype

    Flags: RAM,runtime

    Multiplicity: [0,-1]

    Type of the object. It is used to distinguish what a specific object represents. Whether it is a different kind of organizational unit, project, team, or different kind of user, etc.

  - #### fetchResult

    Flags: RAM,runtime,oper

    Multiplicity: [0,1]

    Result of the operation that fetched this instance of the object. It is mostly used to indicate that the object is not complete or there is some problem with the object. This is used instead of exception if the object is part of larger structures (lists as in list/search operations or composite objects). If not present then the "SUCCESS" state is assumed.

    This field is TRANSIENT. It must only be used in runtime. It should never be stored in the repository.

  - #### extension

    Flags: RAM,runtime

    Multiplicity: [0,1]

    Extension container that provides generic extensibility mechanism. Almost any extension property can be placed in this container. This mechanism is used to extend objects with new properties. The extension is treated exactly the same as other object properties by the code (storage, modifications, etc), except that the system may not be able to understand their meaning.

  - #### parentOrgRef

    Flags: RAM,oper

    Multiplicity: [0,-1]

    Set of the orgs (organizational units, projects, teams) that the object relates to. This usually means that the object belongs to them but it may have other meanings as well (e.g. user manages an organizational unit).

  - #### trigger

    Flags: RAM,runtime,oper

    Multiplicity: [0,-1]

    Triggers for this object. They drive invocations of corresponding trigger handlers at specified time.

  - #### metadata

    Flags: RAM,runtime,oper

    Multiplicity: [0,1]

    Meta-data about object creation, modification, etc.

  - #### tenantRef

    Flags: RAM,oper

    Multiplicity: [0,1]

    Reference to the tenant to which this object belongs. It is a computed value set automatically by midPoint. It is determined from the organizational structure. Even though this value is computed it is also stored in the repository due to performance reasons.

  - #### lifecycleState

    Flags: RAM,runtime

    Multiplicity: [0,1]

    Lifecycle state of the object. This property defines whether the object represents a draft, proposed definition, whether it is active, deprecated, and so on.

    There are few pre-defined lifecycle states. But custom lifecycle states may also be defined. Pre-defined lifecycle states are:

    - draft: Definition of the new object in progress. The object is NOT active. The definition may change at any moment. It is not ready yet.
    - proposed: Definition of a new object is ready for use, but there is still a review process to be applied (e.g. approval). The object is NOT active. However the definition should not change in this state.
    - active: Active and working definition. Ready to be used without any unusual limitations.
    - deprecated: Active definition which is being phased out. The definition is still fully operational. But it should not be used for new assignments. E.g. it should not be requested, it should not be approved, etc.
    - archived: Inactive historical definition. It is no longer used. It is maintained only for historical, auditing and sentimental reasons.
    - failed: Unexpected error has occurred during object lifecycle. Result of that event is that the object is rendered inactive. The situation cannot be automatically remedied. Manual action is needed.

  - #### operationExecution

    Flags: RAM,runtime,oper

    Multiplicity: [0,-1]

    Description of recent operations executed on this object (or related objects in special cases). The number of operations to be kept here is configurable.

  - #### lensContext

    Flags: RAM,runtime

    Multiplicity: [0,1]

    Model context describing executed operation

  - #### policySituation

    Flags: RAM,runtime,oper

    Multiplicity: [0,-1]

    The policy situation(s) of this object. The situations are result of evaluation of the policy rules. This property is recorded for each object and can be used for reporting, diagnostics, target selection in certification campaigns, etc.

  - #### triggeredPolicyRule

    Flags: RAM,runtime,oper

    Multiplicity: [0,-1]

    Triggered policy rules for this assignment. (Not necessarily complete; subject to specified storage strategy.) This is EXPERIMENTAL functionality. It is possibly to change in the near future.

  - #### policyException

    Flags: RAM,runtime

    Multiplicity: [0,-1]

    Recorded exception from a policy rule. The exceptions that are approved are recoded here to avoid re-evaluating and re-approving them all the time. This is EXPERIMENTAL functionality. It is likely to change in the near future.

  - #### diagnosticInformation

    Flags: RAM,runtime

    Multiplicity: [0,-1]

    Diagnostic information attached to this object.

  - #### indestructible

    Flags: RAM,runtime

    Multiplicity: [0,1]

    Protection againts accidental deletion. If set to true then this object cannot be deleted. If the object needs to be deleted then it has to be modified first to reset this flag.

  - #### assignment

    Flags: RAM,runtime

    Multiplicity: [0,-1]

    Set of object's assignments. Assignments define the privileges and "features" that this object should have, that this object is entitled to. Typical assignment will point to a role or define a construction of an account.

    Assignments represent what the object SHOULD HAVE. The assignments represent a policy, a desired state of things (cf. linkRef, roleMembershipRef).

  - #### iteration

    Flags: RAM,runtime,oper

    Multiplicity: [0,1]

    Iteration number. Starts with 0. It is used to iteratively find unique identifier for the object.

  - #### iterationToken

    Flags: RAM,runtime,oper

    Multiplicity: [0,1]

    Iteration token. String value that is usually a suffix to the identifier based on iteration number. E.g. ".007". It is used to iteratively find unique identifier for the object.

  - #### archetypeRef

    Flags: RAM,oper

    Multiplicity: [0,-1]

    References to all applicable archetypes, including "indirect" archetypes such as archetype supertypes. Contains references to active archetypes only.

    Note: the value of this reference is only updated when object is recomputed. Therefore if a role definition changes then all the affected objects must be recomputed for this reference to be consistent.

    This is an operational property. It is set and managed by the system. It is used for efficient use of archetypes.

  - #### roleMembershipRef

    Flags: RAM,oper

    Multiplicity: [0,-1]

    References to abstract roles (roles, orgs, services) that this focus currently belongs to - directly or indirectly. This reference points to all the roles in the role hierarchy. It only points to the roles that were evaluated as active during last recompute (conditions were true, validity constraints not violated).

    Note: the value of this reference is only updated when a focal object is recomputed. Therefore if a role definition changes then all the affected focal objects must be recomputed for this reference to be consistent.

    Roles mentioned here are those that are NOT obtained via delegation, i.e. "deputy" relations. Relations acquired by delegation are listed in delegatedRef item.

    This is an operational property. It is set and managed by the system. It is used for efficient search of all current role members, e.g. for the purpose of displaying this information in the GUI.

    Note: roleMembershipRef will be probably renamed to something like linkRef or outboundLinkRef. We need to generalize it to contain information on generic links between objects (e.g. between child and its parents).

  - #### delegatedRef

    Flags: RAM,oper

    Multiplicity: [0,-1]

    References to objects (abstract roles as well as users) obtained via delegation. If A1 is a deputy of A, its delegatedRef contains a union of A, A.roleMembershipRef and A.delegatedRef.

    This is an operational property. It is set and managed by the system. It is used for efficient search of all current role members, e.g. for the purpose of displaying this information in the GUI.

  - #### roleInfluenceRef

    Flags: RAM,oper

    Multiplicity: [0,-1]

    References to abstract roles (roles and orgs) that this focus may directly belong to. This reference only points to the next role in the hierarchy. However, it is backed by a "closure" index in the repository subsystem. Therefore it can efficiently support tree-like queries. This reference points to the roles for whose the condition is not true. Therefore it does not reliably show who actually has a role. It shows potential role members - all the object that are possibly influenced when a role definition changes.

    This is an operational property. It is set and managed by the system. It is used for efficient search of all possible role members, e.g. for the purpose of recomputing all role members after the role definition is changed.

    TODO. NOT IMPLEMENTED YET. EXPERIMENTAL. UNSTABLE.

  - #### linkRef

    Flags: RAM

    Multiplicity: [0,-1]

    Set of shadows (projections) linked to this focal object. E.g. a set of accounts linked to a user. This is the set of shadows that belongs to the focal object in a sense that these shadows represents the focal object on the resource. E.g. The set of accounts that represent the same midPoint user (the same physical person, they are "analogous").

    Links define what the object HAS. The links reflect real state of things (cf. assignment).

    Note: linkRef will be probably renamed to projectionRef or projectionLinkRef. There are more kinds of links between objects than focus - projection links (cf. roleMembershipRef).

  - #### personaRef

    Flags: RAM

    Multiplicity: [0,-1]

    Set of personas linked to this focal object. E.g. a set of virtual identities linked to a user. This is the set of "secondary" focal objects that belongs to this focal object in a sense that the current focal object is in control over the linked focal objects. E.g. this reference can be used to link user object which specified a physical person with his virtual identities (personas) that specify his identity as an employee, system administrator, customer, etc. The default meaning is that the personas are "analogous", i.e. the represent different facets of the same physical person. However, this meaning may be theoretically overridden by using various relation parameters in this reference.

    This reference define what the object HAS. The links reflect real state of things (cf. assignment).

  - #### activation

    Flags: RAM,runtime

    Multiplicity: [0,1]

    Type that defines activation properties. Determines whether something is active (and working) or inactive (e.g. disabled).

    It applies to several object types. It may apply to user, account, assignment, etc. The data in this type define if the described concept is active, from when it is active and until when. The "active" means that it works. If something is not active, it should not work or not cause any effect. E.g. inactive user should not be able to log in or run any tasks, the non-active role should not be assigned and if assigned it should not be taken into account when computing the accounts.

  - #### jpegPhoto

    Flags: RAM,runtime

    Multiplicity: [0,1]

    Photo corresponding to the user / org / role.

  - #### costCenter

    Flags: RAM,runtime

    Multiplicity: [0,1]

    The name, identifier or code of the cost center to which the user belongs.

    Please note that organization objects (OrgType) also have a costCenter property. Therefore it is usual that if a user belongs to an organization the costCenter from the organization is used. Therefore this property is usually used only for users that do not belong to any organization or for users that have different cost center than the one defined by the organization.

  - #### locality

    Flags: RAM,runtime

    Multiplicity: [0,1]

    Primary locality of the user, the place where the user usually works, the country, city or building that he belongs to. The specific meaning and form of this property is deployment-specific.

  - #### preferredLanguage

    Flags: RAM,runtime

    Multiplicity: [0,1]

    Indicates user's preferred language, usually for the purpose of localizing user interfaces. The format is IETF language tag defined in BCP 47, where underscore is used as a subtag separator. This is usually a ISO 639-1 two-letter language code optionally followed by ISO 3166-1 two letter country code separated by underscore. The languages that do not have country-specific variants are usually specified by using a two-letter country code ("sk", "cs", "tr"). Languages with country-specific variants have country-specific subtags ("pt_BR", "zn_CN"). If no value is specified in this property then system default locale is assumed.

    Examples:

    - en_US
    - sk
    - cs
    - pt_BR

  - #### locale

    Flags: RAM,runtime

    Multiplicity: [0,1]

    Defines user's preference in displaying currency, dates and other items related to location and culture. The format is IETF language tag defined in BCP 47, where underscore is used as a subtag separator. This is usually a ISO 639-1 two-letter language code optionally followed by ISO 3166-1 two letter country code separated by underscore. The languages that do not have country-specific variants are usually specified by using a two-letter country code ("sk", "cs", "tr"). Languages with country-specific variants have country-specific subtags ("pt_BR", "zn_CN"). If not specified then system default locale is assumed.

    Examples:

    - en_US
    - sk
    - cs
    - pt_BR

  - #### timezone

    Flags: RAM,runtime

    Multiplicity: [0,1]

    User's preferred timezone. It is specified in the "tz database" (a.k.a "Olson") format. If not specified then system default timezone is assumed.

    Examples:

    - Europe/Bratislava

  - #### emailAddress

    Flags: RAM,runtime

    Multiplicity: [0,1]

    E-Mail address of the user, org. unit, etc. This is the address supposed to be used for communication with the user, org. unit, etc. E.g. IDM system may send notifications to the e-mail address. It is NOT supposed to be full-featured e-mail address data structure e.g. for the purpose of complex address-book application.

  - #### telephoneNumber

    Flags: RAM,runtime

    Multiplicity: [0,1]

    Primary telephone number of the user, org. unit, etc.

  - #### credentials

    Flags: RAM,runtime

    Multiplicity: [0,1]

    The set of focus's credentials (such as passwords).

  - #### behavior

    Flags: RAM,runtime

    Multiplicity: [0,1]

    General-purpose behavioral data. In a more specific meaning: behavioral data of an agent (user or system), usually represented in midPoint by focus. This data structure records informational data about the agent's behavior, such as authentications, interaction with systems and so on. Such data are inherently _observed_, e.g. they are not configured by the user.

  - #### displayName

    Flags: RAM,runtime

    Multiplicity: [0,1]

    Human-readable name of the role or org. It may be quite long, container national characters and there is no uniqueness requirement. It is used if the "name" property contains a code that is not entirely user-friendly. This properly will be deprecated soon. Use of display/label is recommended instead of displayName.

  - #### identifier

    Flags: RAM,runtime

    Multiplicity: [0,1]

    Identifier of the role or org. It should be a structured information usually used for referring to the role or org or correlating it in various systems. E.g. numeric organizational unit identifier, role code, etc. It should be unique in its "own" scope. E.g. an organizational unit identifier should be unique in the scope of all organizational units but it may conflict with an identifier of a project.

  - #### inducement

    Flags: RAM,runtime

    Multiplicity: [0,-1]

    Inducements define the privileges and "features" that other objects should have. It is a form of indirect assignment.

    Unlike assignments inducements do not apply to the object in which they are specified. Inducements apply to the object that is has assigned the object which contains inducements. E.g. inducements specified in a role will not be applied to the role itself. The inducements will be applied to the user that is assigned to such role.

    See Assignment vs Inducement in midPoint wiki.

  - #### authorization

    Flags: RAM,runtime

    Multiplicity: [0,-1]

    Set of role authorizations. Authorization define fine-grained access to midPoint objects and system functionality. The authorizations that are defined in a role apply to all users that have this role assigned (such user is a "subject" of the authorizations).

  - #### requestable

    Flags: RAM,runtime

    Multiplicity: [0,1]

    If set to true then this role may be directly requested by the users. This is an ordinary property without any special built-in function. It does NOT directly control any access control or presentation mechanisms. Appropriate authorization rules should be defined to make this property work. E.g. see authorization statements in the default end user role.

  - #### delegable

    Flags: RAM,runtime

    Multiplicity: [0,1]

    If set to true then this role may be delegated to a deputy. This is an ordinary property without any special built-in function. It does NOT directly control any access control or presentation mechanisms. Appropriate authorization rules should be defined to make this property work.

  - #### idempotence

    Flags: RAM,runtime,AVals:3

    Multiplicity: [0,1]

    This value indicates whether the evaluation of this role gives the same results regardless of its position in the assignment/inducement hierarchy. I.e. evaluation of this role does not depend on the assignment parameters of focus or any of the preceding roles. This flag is used to enable aggressive caching of role evaluation, so idempotent roles are only evaluated once regardless of their position in the hierarchy as we can assume that any subsequent evaluation will produce exactly the same results as the first evaluation. This is a very important feature that allows efficient evaluation of big role hierarchies.

    Marking role as idempotent is likely to result in huge performance improvements in systems with large role hierarchies. But there are also risks of incorrect evaluation of the roles. If an role is idempotent then is is also assumed that any roles included in this role are also idempotent. Therefore please take care when constructing role hierarchies. This property has a default value that indicates no idempotency.

    Rules of the thumb: Roles that are frequently used, roles that are included in many other roles and roles that combine many other roles are should be idempotent. Typical example is a "basic" roles that is assigned to almost any user and that contains a lot of smaller roles. Roles that are parametric or very dynamic should NOT be idempotent. Note: it is perfectly OK for some dynamic roles to be marked as idempotent - even if the role contains complex expressions and conditions. If those conditions depend only on the environment or properties of the focus then their outcome does not depend on their position in assignment/inducement hierarchy and these roles can be made idempotent.

  - #### riskLevel

    Flags: RAM,runtime

    Multiplicity: [0,1]

    Indication of the level of risk associated with the permissions that this role assigns. This may be a numeric value, textual label are any other suitable machine-processable indication.

  - #### condition

    Flags: RAM,runtime

    Multiplicity: [0,1]

    The role is applied only if the condition is evaluated to true. The condition is used to define conditional roles. If condition is not present, it is assumed to be true.

  - #### adminGuiConfiguration

    Flags: RAM,runtime

    Multiplicity: [0,1]

    Specifies the admin GUI configuration that should be used for the members of this role.

  - #### dataProtection

    Flags: RAM,runtime

    Multiplicity: [0,1]

    Specifies the GDPR related attributes

  - #### autoassign

    Flags: RAM,runtime

    Multiplicity: [0,1]

    Specification of role auto-assignment properties. Those properties are evaluated to detect whether a role should be automatically assigned to focus.

  - #### roleType

    Flags: RAM,runtime

    Multiplicity: [0,1]

    Type of a role, usually denotes a "layer" or "purpose" of the role. Such as "business", "IT", "asset", etc. This field has no special meaning in the IDM computation logic. Its purpose is to organize roles for presentation (GUI) and management. Therefor it is assumed that the values of the roleType will be an enumeration.

    In a complex RBAC structures the role type is usually defined by an assignment of a meta-role. However, selecting the roles by (sometimes transitive) meta-role assignment is not very efficient. Therefore the recommended use is for a meta-role to set the value of (focal) role roleType property to a simple string value (focusMapping in a meta-role is ideal for this purpose). The roleType property should also be associated with a LookupTable (or similar mechanism) to allow GUI to efficiently display and select role types.

    Examples:

    - application
    - business
    - it
    - technical
    - asset

    DEPRECATED: use ObjectType.subtype