Skip to content

Commit

Permalink
Update authorization docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@mederly
mederly committed Aug 22, 2023
1 parent 47bb18b commit d7983dc
Show file tree
Hide file tree
Showing 14 changed files with 544 additions and 238 deletions.
3 changes: 2 additions & 1 deletion docs/expressions/expressions/profiles/configuration.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
:page-wiki-metadata-modify-date: 2019-09-26T14:54:40.106+02:00
:page-since: "4.0"
:page-upkeep-status: green
:page-toc: top

[NOTE]
.Limited feature
Expand Down Expand Up @@ -299,7 +300,7 @@ Please do not use this character as the first one in your profile identifiers.
Also, it is not possible to reference built-in profiles from within your configuration.
So, if you need to create a "full access" profile, you need to create your own.
In 4.8, there are the following built-in profiles: `##full` (full access), `##none` (no access), `##legacyUnprivilegedBulkActions` (see below).
In 4.8, there are the following built-in profiles: `\\##full` (full access), `##none` (no access), `##legacyUnprivilegedBulkActions` (see below).
====

=== For Bulk Actions
Expand Down
271 changes: 34 additions & 237 deletions docs/security/authorization/configuration/index.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -469,206 +469,55 @@ However it can be freely modified and replaced with a better least-privilege adm

== Object Specification

Object of the authorization can be selected in a variety of ways:
Object of the authorization can be selected in a variety of ways.
They are summarized in the following table.

.Object selector clauses
[%autowidth]
|===
| Clause | Description

=== Object Selection by Type

Authorization applies only to objects of the specified type.
In the following case it only applies to shadows:

[source,xml]
----
<authorization>
<action>...</action>
<object>
<type>ShadowType</type>
</object>
</authorization>
----

=== Object Selection by Query Filter

Authorization applies only to objects that match specified query.
In the following case it only applies to objects that have property `locality` set to value `Caribbean`.

[source,xml]
----
<authorization>
<action>...</action>
<object>
<filter>
<q:equal>
<q:path>locality</q:path>
<q:value>Caribbean</q:value>
</q:equal>
</filter>
</object>
</authorization>
----

Or, alternatively, using midPoint Query Language.

[source,xml]
----
<authorization>
<action>...</action>
<object>
<filter>
<q:text>locality = "Caribbean"</q:text>
</filter>
</object>
</authorization>
----

=== Object Selection by Archetype

Authorization applies only to objects that have specified archetype.

[source,xml]
----
<authorization>
<action>...</action>
<object>
<archetypeRef oid="00000000-0000-0000-0000-000000000321"/>
</object>
</authorization>
----

Archetype specification is multi-valued.
If more than one `archetypeRef` is used in the same authorization, then _or_ operation is implied.
I.e. match of a single archetypes from the list will make the authorization applicable for the object.

[TIP]
====
The <archetypeRef> mechanism is available in midPoint 4.0 and later.
See also xref:/midpoint/reference/schema/archetypes/[Archetypes].
====

=== Object Selection by Organization Structure Membership

Authorization applies only to objects that are members of a specific xref:/midpoint/architecture/archive/data-model/midpoint-common-schema/orgtype/[Org].
In the following case it only applies to members of Org identified by OID `1f82e908-0072-11e4-9532-001e8c717e5b`.

[source,xml]
----
<authorization>
<action>...</action>
<object>
<orgRef oid="1f82e908-0072-11e4-9532-001e8c717e5b"/>
</object>
</authorization>
----

This is good for delegated administration to fixed organizational subtrees.

NOTE: The organization object itself (`1f82e908-0072-11e4-9532-001e8c717e5b` in the above example) is _not_ covered by the authorization.
In fact, it is not a member of itself.

=== Object Selection by Organization Structure Relation

This authorization type applies only to objects that are members of any org, for which the subject has a specific relation.
E.g. it can give access to any objects that are part of any organizational unit that the subject is managing.
This is illustrated in the following snippet.
This authorization gives managers the ability to control any object that they are "managing".

[source,xml]
----
<authorization>
<action>...</action>
<object>
<orgRelation>
<subjectRelation>org:manager</subjectRelation>
</orgRelation>
</object>
</authorization>
----

This is good for dynamic delegated administration.
But please note that this authorization may degrade performance if the subject has relation to many organizational units.

[TIP]
====
The `<orgRelation>` mechanism is available in midPoint 3.4 and later.
====

=== Self Object Selection

Authorization applies only to objects that represent the user which initiates the operation.
I.e. if the object is also a subject of the operation.
| xref:selectors/type-and-parent.adoc[`type`]
| Authorization applies only to objects of the specified type.

[source,xml]
----
<authorization>
<action>...</action>
<object>
<special>self</special>
</object>
</authorization>
----
| xref:selectors/type-and-parent.adoc[`parent`]
| Authorization applies only to objects positioned at specified path within given parents.

=== Object Selection by Owner
| xref:selectors/filter.adoc[`filter`]
| Authorization applies only to objects that match specified filter.
(Optionally, with expressions.)

Authorization applies only to objects that have an owner which is specified by inner object selection.
| xref:selectors/archetypeRef.adoc[`archetypeRef`]
| Authorization applies only to objects that have specified archetype.

[source,xml]
----
<authorization>
<action>...</action>
<object>
<owner>
... inner object selection specification goes here ...
</owner>
</object>
</authorization>
----
| xref:selectors/orgRef.adoc[`orgRef`]
| Authorization applies only to objects that are members of a specific xref:/midpoint/architecture/archive/data-model/midpoint-common-schema/orgtype/[Org].

The object owner is its xref:/midpoint/reference/schema/focus-and-projections/[focal object].
E.g. typical owner of account shadows is a user to whom the accounts are linked.
| xref:selectors/orgRelation.adoc[`orgRelation`]
| Authorization applies only to objects that are members of any org, for which the subject has a specific relation.

E.g. the following example only applies to objects that have owner who is a full-time employee, represented by having the archetype with OID `164319fb-7c23-4346-8a58-6e128b4861d5`.
| xref:selectors/self.adoc[`self`]
| Authorization applies only to objects that represent the user which initiates the operation.

[source,xml]
----
<authorization>
<action>...</action>
<object>
<owner>
<archetypeRef oid="164319fb-7c23-4346-8a58-6e128b4861d5"/> <!-- Full-time employee -->
</owner>
</object>
</authorization>
----
| xref:selectors/owner.adoc[`owner`]
| Authorization applies only to objects that have an owner which is specified by inner object selector.

=== Object Selection by Tenant
| xref:selectors/delegator.adoc[`delegator`]
| Authorization applies only to users that have active delegation assignment to objects selected by inner selector (currently limited to `self`).

++++
{% include since.html since="3.9" %}
++++
| xref:selectors/requester.adoc[`requester`]
| Authorization applies only to objects (e.g. cases) for which objects selected by inner selector are requesters.

Authorization applies only to objects that have the same tenant as the subject.
| xref:selectors/assignee.adoc[`assignee` and `candidateAssignee`]
| Authorization applies only to objects (e.g. cases) for which objects selected by inner selector are assignees (or candidate assignees).

[source,xml]
----
<authorization>
<action>...</action>
<object>
<tenant>
<sameAsSubject>true</sameAsSubject>
<includeTenantOrg>false</includeTenantOrg>
</tenant>
</object>
</authorization>
----
| xref:selectors/relatedObject.adoc[`relatedObject`]
| Authorization applies only to objects (cases, tasks) that are related to objects selected by the inner selector.

This authorization can be used to limit users to access objects only inside their own tenant.
The `includeTenantOrg` element can be used to include or exclude the tenant (tenant org) itself.
E.g. it can be used to prohibit modification of the tenant itself, but allow modification of any other object in its "tenancy".
| xref:selectors/tenant.adoc[`tenant`]
| Authorization applies only to objects that have the same tenant as the subject.

This authorization works only if both subject and object are multi-tenant.
I.e. it will not work if subject does not have tenant (no `tenantRef`) or in case that the object does not have tenant.
Ordinary (non-tenant) authorizations should be used for those cases.
|===

=== Object Selection Combinations

Expand Down Expand Up @@ -849,58 +698,6 @@ Therefore if no `orderConstraints` clause is present, then the authorization all
This behavior is slightly different from other authorization clauses, where no clause means no limitation.
But this behavior was chosen for compatibility reasons.

== Expressions

++++
{% include since.html since="3.7" %}
++++

xref:/midpoint/reference/expressions/expressions/[Expressions] can be used in authorization search filters:

[source,xml]
----
<authorization>
<action>http://midpoint.evolveum.com/xml/ns/public/security/authorization-model-3#read</action>
<object>
<type>RoleType</type>
<filter>
<q:equal>
<q:path>roleType</q:path>
<expression>
<!-- Make sure empty value of costCenter does not allow any access. -->
<queryInterpretationOfNoValue>filterNone</queryInterpretationOfNoValue>
<path>$subject/costCenter</path>
</expression>
</q:equal>
</filter>
</object>
</authorization>
----

The authorization above allows read access to all roles that have the same `roleType` as is the values of `costCenter` property of the user who is subject of the authorization.

Variable `subject` may be used in the expressions to represent authorization subject (user).
Other common expressions variables may also be available or will be made available in the future.
However, we recommend to avoid using the `actor` variable.
Please use `subject` variable instead.
Those variables are usually set to the same value.
But there may be situations when the value is different (e.g. administrator evaluating authorization of a different user).
The `subject` variable is usually the right one.

[NOTE]
====
Authorizations are evaluated frequently.
Evaluations are done at least twice during ordinary midPoint operation.
Authorizations are designed to be very efficient to evaluate.
However, if expression is part of the evaluation then the expression may impact performance of the entire system.
Expressions that use the `path` evaluator (as the one above) are usually very fast, and they are safe.
Even simple script expressions usually do not create any major issue.
However, try to avoid placing complex or slow expressions into authorizations.
Those are almost certain to have a severe negative impact on system performance.
If you need complex computation, it is perhaps better to compute the value in xref:/midpoint/reference/expressions/object-template/[object template] and place it into property of the object (e.g. user extension property).
Then use only the result of the computation stored in that property in authorization expressions.
====

== Item Authorizations

Almost all "core" authorizations may be limited to a specific set of items.
Expand Down
21 changes: 21 additions & 0 deletions docs/security/authorization/configuration/selectors/archetypeRef.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
= Archetype Clause
:page-since: 4.0

Authorization applies only to objects that have specified archetype.

.Listing 1. Authorization applicable to objects with a given archetype.
[source,xml]
----
<authorization>
<action>...</action>
<object>
<archetypeRef oid="00000000-0000-0000-0000-000000000321"/>
</object>
</authorization>
----

Archetype specification is multivalued.
If more than one `archetypeRef` is used in the same authorization, then _or_ operation is implied.
I.e. match of a single archetypes from the list will make the authorization applicable for the object.

See also xref:/midpoint/reference/schema/archetypes/[Archetypes].
53 changes: 53 additions & 0 deletions docs/security/authorization/configuration/selectors/assignee.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
= Assignee and Candidate Assignee Clause

It selects objects (cases, work items) that have an assignee which is specified by inner object selector.

An example:

.Listing 1. An authorization allowing reading any case in which the subject is an assignee
[source,xml]
----
<authorization>
<name>cases-assignee-self-read</name>
<action>http://midpoint.evolveum.com/xml/ns/public/security/authorization-model-3#read</action>
<object>
<type>CaseType</type>
<assignee>
<special>self</special>
</assignee>
</object>
</authorization>
----

The following behavior applies to midPoint 4.8.

.Supported object types
[%autowidth]
|===
| Object type | What are the assignees?

| `CaseType`
| All `assigneeRef` values from all `workItem` values.

| `AccessCertificationCaseType`
| All `assigneeRef` values from all `workItem` values.

| `AbstractWorkItemType` (work items for both types of cases)
| All `assigneeRef` values.
|===

== Delegation
During evaluation of this clause, the `self` clause in the inner selector has an interpretation that slightly differs from the usual one:
Instead of matching the principal object only, it matches all of its deputies relevant for given area (i.e., case management or access certification).
So, if `ann` is a deputy of `jack` with the rights in the area of case management, and a case `C` has a work item assigned to `jack`, and `ann` has the authorization depicted in Listing 1, then she can read the case `C` exactly as `jack` can.

== Limitations
. When searching, only `self` selector is supported.

== Candidate Assignee
++++
{% include since.html since="4.8" %}
++++

In a similar way, candidate assignees can be authorized regarding cases, certification cases, and their work items.
The `candidateRef` item is taken into account instead of `assigneeRef`.

0 comments on commit d7983dc

Please sign in to comment.