Merge remote-tracking branch 'refs/remotes/origin/master'

docs/admin-gui/localization.adoc

@@ -37,7 +37,7 @@ However, Evolveum does *not*  maintain any localization or translation, except f
 The translation work is done by Evolveum partners, customers, midPoint community users and so on.
 There is a significant number of translations and every single one was contributed by midPoint community.
 The translation process itself is coordinated by the community.
-Translation coordinator is Petr Gašpark, the effort is supported by AMI Praha.
+Translation coordinator is Jan Mokráček, the effort is supported by AMI Praha.
 
 This arrangement was not part of the original plan.
 It has naturally evolved over the years when midPoint community offered more and more translations.
@@ -68,7 +68,7 @@ The easiest way to help with midPoint localization is to use link:https://app.tr
 Just create a free account on Transifex and request to join the midPoint localization team.
 Any work that you do on Transifex will be synchronized to localization files in midPoint source code repositories.
 
-In case of any questions please contact link:https://app.transifex.com/user/profile/petr.gasparik/[Petr Gašpark] who coordinates the translation effort.
+In case of any questions please contact link:https://app.transifex.com/user/profile/jan.mokracek/[Jan Mokráček] who coordinates the translation effort.
 
 
 == Localization Of Diagnostics
@@ -118,4 +118,4 @@ MidPoint does not fully support such deployment and it is expected that a xref:/
 
 * xref:/midpoint/reference/concepts/polystring/[PolyString]
 
-* xref:/community/[Participation]
+* xref:/community/[Participation]

docs/concepts/object-lifecycle/index.adoc

@@ -21,14 +21,14 @@ image::schemas-lifecycle-statechart.png[]
 
 If no explicit lifecycle state is defined then the `active` state is assumed.
 In addition to the pre-defined states custom lifecycle states can be used.
-However currently (midPoint 3.5) all the custom lifecycle states are considered to be non-active.
+However, currently all the custom lifecycle states are considered to be non-active.
 
 
 == Pre-defined Lifecycle States
 
 [%autowidth]
 |===
-| State | Focus active | Assignments active | Description
+| State | Focus active | Assignments active | Description | Examples
 
 | draft
 | no
@@ -37,6 +37,7 @@ However currently (midPoint 3.5) all the custom lifecycle states are considered
 The object is NOT active.
 The definition may change at any moment.
 It is not ready yet.
+| Role definition in preparation (not finished yet).
 
 
 | proposed
@@ -45,13 +46,27 @@ It is not ready yet.
 | 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.
+| Finished new role definition in approval process. +
+Self-registered user, not yet validated.
 
 
 | active
 | YES
 | YES
 | Active and working definition.
 Ready to be used without any unusual limitations.
+| Active employee. +
+Role in production use.
+
+| suspended
+| no
+| YES
+| Suspended definition, temporarily disabled.
+It is expected that the object will return to _active_ state eventually.
+
+Available since midPoint 4.8.
+| Employee on temporary leave (maternal leave, sabbatical). +
+Resource temporarily disabled for maintenance.
 
 
 | deprecated
@@ -61,6 +76,8 @@ Ready to be used without any unusual limitations.
 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.
+| Deprecated role: still working, but not intended to be assigned any more. +
+Legacy resource: we still want to read the data, but we do not want to create new accounts.
 
 
 | archived
@@ -69,6 +86,8 @@ E.g. it should not be requested, it should not be approved, etc.
 | Inactive historical definition.
 It is no longer used.
 It is maintained only for historical, auditing and sentimental reasons.
+| Retired employee, keeping minimal record for accounting reasons and to avoid identifier recycling. +
+Phased-out role definition, kept for historical reasons.
 
 
 | failed
@@ -78,6 +97,9 @@ It is maintained only for historical, auditing and sentimental reasons.
 Result of that event is that the object is rendered inactive.
 The situation cannot be automatically remedied.
 Manual action is needed.
+| Role definition rejected during approvals, without obvious continuation of the process. +
+Role definition identified to be in violation of the policy, immediately taken out of use. +
+Resource with unexpected critical errors, requiring attention od administrators.
 
 
 |===
@@ -113,6 +135,13 @@ E.g. there is a pending approval.
 | Active and working assignment.
 
 
+| suspended
+| no
+| Temporarily disabled assignment.
+
+Available since midPoint 4.8.
+
+
 | deprecated
 | YES
 | *NOT USED*

docs/expressions/expressions/index.adoc

@@ -537,31 +537,83 @@ Therefore the following two expressions are equivalent (assuming that user is se
 
 == Security
 
-=== Run As
+[#_privilege_elevation]
+=== Privilege Elevation (Run As, Run Privileged)
 
 Expressions are normally evaluated using the security principal of the user that initiated the operation.
-This is best security practice as the authorizations go deep into the system and close to the data.
-In this it unlikely that an expression would read data or initiate an operation that the user is not authorized for.
-Therefore the probability of a security breach is reduced.
+This is the best security practice, as the authorizations go deep into the system and close to the data.
+By doing this, it is unlikely that an expression would read data or initiate an operation that the user is not authorized for.
+Therefore, the probability of a security breach is reduced.
 
-However, there are some cases when an expression needs access to data or operations that the use do not usually has.
-Since midPoint 3.6 the expression can be executed with the identity of a different user:
+However, there are some cases when an expression needs access to data or operations beyond the user's authorization.
+Since midPoint 3.6, the expression can be executed with the identity of a different user, and since 4.8, a faster option of elevating the privileges only is available as well.
 
+==== How to Use Elevated Privileges
+++++
+{% include since.html since="4.8" %}
+++++
+
+The following example shows both options for privilege elevation.
+Although they can be used at the same time, you normally use only one of them.
+
+.An example of the current runAs/runPrivileged syntax
 [source,xml]
 ----
 <expression>
-    <runAsRef oid="e5e0f2fe-0aea-11e7-b02b-2b6815aa719e"/>
+    <privileges>
+        <runAsRef oid="e5e0f2fe-0aea-11e7-b02b-2b6815aa719e" type="UserType"/> <!--1-->
+        <runPrivileged>true</runPrivileged> <!--2-->
+    </privileges>
     <script>
         ....
     </script>
 </expression>
 ----
+<1> Switches the identity of the principal
+<2> Keeps the identity, elevates only the privileges
 
-The expression above will be executed with authorizations of the user identified by OID `e5e0f2fe-0aea-11e7-b02b-2b6815aa719e`. If the expression executes any operations that are audited, then this identity will also be used for auditing.
+==== Legacy Way of Privilege Escalation (from 3.6 to 4.7.x)
+
+.An example of the legacy runAs syntax
+[source,xml]
+----
+<expression>
+    <runAsRef oid="e5e0f2fe-0aea-11e7-b02b-2b6815aa719e"/> <!-- from 3.6 to 4.7 -->
+    <script>
+        ....
+    </script>
+</expression>
+----
+
+==== Effects of Privilege Escalation
+
+When `runAsRef` is used, the expression will be executed with the authorization of the object referenced.
+In the examples above, it will be the user identified by OID `e5e0f2fe-0aea-11e7-b02b-2b6815aa719e`.
 
 The variable `actor` that is present in most expressions still refers to the identity of the user that initiated the operations.
 This variable is not affected by the `runAs` configuration.
 
+When `runPrivileged` is used (since 4.8), the expression will be executed under the identity of the currently logged-in users.
+Their authorizations will be extended by including "allow all" (`http://midpoint.evolveum.com/xml/ns/public/security/authorization-3#all`) for the duration of expression evaluation.
+
+==== Performance Implications
+
+The use of `runAsRef` involves the login process, which can take considerable time.
+In some cases, the time needed may be in the range of tens of milliseconds.
+This may or may not be acceptable, e.g., for the evaluation of frequently used expressions.
+
+The use of `runPrivileged` should be much faster.
+
+==== Auditing
+
+Since 4.8, each audit record contains the `effectivePrincipalRef` item that contains the reference to the identity under which the operation took place.
+When `runAsRef` is used, the referenced identity is recorded.
+
+Also, `effectivePrivilegesModification` property is there, indicating whether privileges were modified with regard to the original ones defined in the repository.
+When `runPrivileged` is used, this property has a value of `fullElevation`.
+
+Please see xref:/midpoint/reference/security/privilege-elevation.adoc[] for more information.
+
 === Security of Script Expressions
 
 Script expressions are a code that runs inside midPoint servers.