Skip to content

Commit

Permalink
link: and wiki: vs xref: fixes, local docs using xref
Browse files Browse the repository at this point in the history
  • Loading branch information
virgo47 committed Oct 26, 2021
1 parent b250a82 commit f6c9a7a
Show file tree
Hide file tree
Showing 143 changed files with 465 additions and 464 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -531,7 +531,7 @@ Xml for the task template object you can find by the link:https://github.com/Evo
== Admin GUI Configuration and Authorizations

At the first sight the use of admin GUI configuration to define object forms and dashboard widgets may seem to be redundant.
It may look that wiki:Authorization[authorization] mechanism provides the same services.
It may look that xref:/midpoint/reference/security/authorization/[authorization] mechanism provides the same services.
But there are subtle differences.

* The authorization mechanism is designed to answer one very specific question: _can subject S do action A with object O?_ However, in user interface it is often desired to hide information that the user is entitled to see.
Expand Down Expand Up @@ -622,7 +622,7 @@ To see changes made in this part of configuration, user needs to do logout/login

== Security

Some parts of admin GUI configuration may contain wiki:Expression[expressions]. Expressions are pieces of code that are executed inside midPoint server.
Some parts of admin GUI configuration may contain xref:/midpoint/reference/expressions/expressions/[expressions]. Expressions are pieces of code that are executed inside midPoint server.
As such expressions has to be inherently trusted.
Therefore do not allow untrusted users to define sensitive parts of admin GUI configuration.

Expand All @@ -631,6 +631,6 @@ Therefore do not allow untrusted users to define sensitive parts of admin GUI co

* wiki:System+Configuration+Object[System Configuration Object]

* wiki:Authorization[Authorization]
* xref:/midpoint/reference/security/authorization/[Authorization]

* wiki:Show+Only+Active+Users+HOWTO[Show Only Active Users HOWTO]
6 changes: 3 additions & 3 deletions docs/admin-gui/admin-gui-config/index.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -1256,7 +1256,7 @@ Xml for the task template object you can find by the link:https://github.com/Evo
== Admin GUI Configuration and Authorizations

At the first sight the use of admin GUI configuration to define object forms and dashboard widgets may seem to be redundant.
It may look that wiki:Authorization[authorization] mechanism provides the same services.
It may look that xref:/midpoint/reference/security/authorization/[authorization] mechanism provides the same services.
But there are subtle differences.

* The authorization mechanism is designed to answer one very specific question: _can subject S do action A with object O?_ However, in user interface it is often desired to hide information that the user is entitled to see.
Expand Down Expand Up @@ -1347,7 +1347,7 @@ To see changes made in this part of configuration, user needs to do logout/login

== Security

Some parts of admin GUI configuration may contain wiki:Expression[expressions]. Expressions are pieces of code that are executed inside midPoint server.
Some parts of admin GUI configuration may contain xref:/midpoint/reference/expressions/expressions/[expressions]. Expressions are pieces of code that are executed inside midPoint server.
As such expressions has to be inherently trusted.
Therefore do not allow untrusted users to define sensitive parts of admin GUI configuration.

Expand All @@ -1356,6 +1356,6 @@ Therefore do not allow untrusted users to define sensitive parts of admin GUI co

* wiki:System+Configuration+Object[System Configuration Object]

* wiki:Authorization[Authorization]
* xref:/midpoint/reference/security/authorization/[Authorization]

* wiki:Show+Only+Active+Users+HOWTO[Show Only Active Users HOWTO]
6 changes: 3 additions & 3 deletions docs/admin-gui/collections-views/configuration/index.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,8 @@ Collections and views are two concepts that are very related, but still somehow
There is a special object type (ObjectCollectionType) that is used to define a collection.
It is first-class midPoint object.
Collection defines which objects belong to the collection.
The plan is that collections can be used in the entire midPoint system, e.g. collections can be used in wiki:Authorization[authorizations], wiki:Policy+Rules[policy rules] may be applied to them and so on.
Some midPoint objects can act as an implicit collections, especially wiki:Archetypes[archetypes] and wiki:Organizational+Structure[organizational units]. Object collections are designed to be solid and stable.
The plan is that collections can be used in the entire midPoint system, e.g. collections can be used in xref:/midpoint/reference/security/authorization/[authorizations], wiki:Policy+Rules[policy rules] may be applied to them and so on.
Some midPoint objects can act as an implicit collections, especially wiki:Archetypes[archetypes] and xref:/midpoint/reference/org/organizational-structure/[organizational units]. Object collections are designed to be solid and stable.
Something that midPoint policies can rely on.

* *View* is a user interface concept.
Expand Down Expand Up @@ -97,7 +97,7 @@ Therefore is one definition changes, all the collections take notice.

The use of collections in midPoint 4.0 is somehow limited.
In future midPoint releases, Collections may be reused in authorizations and policy rules.
E.g. It would be nice to use just "employees" as a criterion in wiki:Authorization[authorizations] instead of copying the search filter everywhere.
E.g. It would be nice to use just "employees" as a criterion in xref:/midpoint/reference/security/authorization/[authorizations] instead of copying the search filter everywhere.
Similarly this collection may be reused in policy rule specifications.
In the future there may be scanner tasks that scan just the objects that belong to the collections, bulk actions for the collections and similar improvements.

Expand Down
4 changes: 2 additions & 2 deletions docs/admin-gui/collections-views/index.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,8 @@ Collections and views are two concepts that are very related, but still somehow
There is a special object type (ObjectCollectionType) that is used to define a collection.
It is first-class midPoint object.
Collection defines which objects belong to the collection.
The plan is that collections can be used in the entire midPoint system, e.g. collections can be used in wiki:Authorization[authorizations], wiki:Policy+Rules[policy rules] may be applied to them and so on.
Some midPoint objects can act as an implicit collections, especially wiki:Archetypes[archetypes] and wiki:Organizational+Structure[organizational units]. Object collections are designed to be solid and stable.
The plan is that collections can be used in the entire midPoint system, e.g. collections can be used in xref:/midpoint/reference/security/authorization/[authorizations], wiki:Policy+Rules[policy rules] may be applied to them and so on.
Some midPoint objects can act as an implicit collections, especially wiki:Archetypes[archetypes] and xref:/midpoint/reference/org/organizational-structure/[organizational units]. Object collections are designed to be solid and stable.
Something that midPoint policies can rely on.

* *View* is a user interface concept.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
:page-alias: { "parent" : "/midpoint/guides/" }

There are scenarios, when it is needed to limit the number of objects that users see.
This would normally be done by using wiki:Authorization[authorizations]. But authorizations have their limits.
This would normally be done by using xref:/midpoint/reference/security/authorization/[authorizations]. But authorizations have their limits.
For example, we may normally need to allow users to see basic details of almost any objects.
This is often needed because objects may be referenced from tasks, workitems, audit records and so on.
Therefore users must be authorized to read such objects.
Expand Down
4 changes: 2 additions & 2 deletions docs/admin-gui/role-catalog/configuration.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ For an introduction to the role catalog concept please see wiki:Role+Catalog[Rol

== Role Catalog Implementation

Simply speaking, role catalog is just an wiki:Organizational+Structure[organizational structure] structure.
Simply speaking, role catalog is just an xref:/midpoint/reference/org/organizational-structure/[organizational structure] structure.
However, instead of divisions and sections the role catalog is composed of _categories_. And instead of member users there are _roles_. But apart from that the role catalog is just ordinary organizational structure.
The categories are ordinary wiki:OrgType[org objects]. The roles are assigned to the categories in exactly the same way as users are assigned to organizational structure.
Remember: MidPoint can have any number of organizational structures and the role catalog is just one of them.
Expand Down Expand Up @@ -50,4 +50,4 @@ The roleCatalogRef reference above points to the wiki:OrgType[org] which is the

* wiki:Advanced+Hybrid+RBAC[Advanced Hybrid RBAC]

* wiki:Organizational+Structure[Organizational Structure]
* xref:/midpoint/reference/org/organizational-structure/[Organizational Structure]
6 changes: 3 additions & 3 deletions docs/admin-gui/role-catalog/index.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ image::role-request.png[]
== Role Catalog for Administrators

The second purpose of role catalog is to make *role administration* and management easy.
Role catalog is essential just an wiki:Organizational+Structure[organizational structure] (see below).
Therefore it can be used to set up wiki:Authorization[fine-graned authorizations and delegated administration] of the roles.
Role catalog is essential just an xref:/midpoint/reference/org/organizational-structure/[organizational structure] (see below).
Therefore it can be used to set up xref:/midpoint/reference/security/authorization/[fine-graned authorizations and delegated administration] of the roles.
For example the application roles may be sorted to categories that represent applications and application modules.
In that case the management of the application roles can be delegated to application or module owners.

Expand All @@ -52,7 +52,7 @@ See wiki:Role+Catalog+Configuration[Role Catalog Configuration] page for descrip

* wiki:Advanced+Hybrid+RBAC[Advanced Hybrid RBAC]

* wiki:Organizational+Structure[Organizational Structure]
* xref:/midpoint/reference/org/organizational-structure/[Organizational Structure]

* wiki:Role+Catalog+Configuration[Role Catalog Configuration]

Expand Down
2 changes: 1 addition & 1 deletion docs/admin-gui/role-request/configuration.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@

== Role Catalog Configuration

The prerequisite for a good user experience is usually proper configuration of wiki:Role+Catalog+Configuration[role catalog] and wiki:Authorization[authorizations]. The end-user role selection page will display only those roles that the currently-logged-in user can assign to himself.
The prerequisite for a good user experience is usually proper configuration of wiki:Role+Catalog+Configuration[role catalog] and xref:/midpoint/reference/security/authorization/[authorizations]. The end-user role selection page will display only those roles that the currently-logged-in user can assign to himself.
Therefore especially the proper use of `assign` authorization is crucial for proper functioning of this page.


Expand Down
2 changes: 1 addition & 1 deletion docs/admin-gui/role-request/index.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ wiki:Policy+Rules[Policy rules] that apply to the roles are evaluated and enforc
== Configuration

The "catalog and shopping cart" user interface is ready made and as most parts of midPoint user interface it automatically adapts to midPoint configuration.
For example wiki:Role+Catalog[role catalog] set up and wiki:Authorization[authorizations] are automatically precessed, therefore only those roles that are actually requestable by the user are displayed.
For example wiki:Role+Catalog[role catalog] set up and xref:/midpoint/reference/security/authorization/[authorizations] are automatically precessed, therefore only those roles that are actually requestable by the user are displayed.
However there are still few things that may need to be customized.
The customization of this part of the user interface is described in wiki:Role+Request+and+Shopping+Cart+Configuration[Role Request and Shopping Cart Configuration] page.

Expand Down
24 changes: 12 additions & 12 deletions docs/admin-gui/user-interface-form-fields.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
MidPoint has a flexible user interface that automatically adapts to changed schema.
This is one of the crucial midPoint features that supports efficient midPoint deployments.
Change of schema is usually the only thing that is needed to customize the way how midPoint displays data.
E.g. if a new account attribute appears on the resource all that is needed is to refresh the cached wiki:Resource+Schema[resource schema]. MidPoint will automatically use the schema to display account forms in the user interface, it will automatically use input field that is appropriate for the attribute type, it will automatically indicate whether the attribute is optional, mandatory, single-value or multi-value, it will display a proper label and so on.
E.g. if a new account attribute appears on the resource all that is needed is to refresh the cached xref:/midpoint/reference/resources/resource-schema/[resource schema]. MidPoint will automatically use the schema to display account forms in the user interface, it will automatically use input field that is appropriate for the attribute type, it will automatically indicate whether the attribute is optional, mandatory, single-value or multi-value, it will display a proper label and so on.

Similar behavior can be seen for all the other parts of midPoint.
E.g. the fields of user form are determined from the schema of wiki:UserType[UserType], the resource configuration in the resource wizard is wiki:Resource+and+Connector+Schema+Explanation[driven by the connector schema] and so on.
Expand All @@ -27,7 +27,7 @@ Let's explain that using an example of a LDAP resource.
We have a simple LDAP resource with root suffix `dc=example,dc=com`. We want to manage LDAP accounts in ou=people,dc=example,dc=com.
The accounts will have `inetOrgPerson` object class.
This all easy.
MidPoint will discover LDAP schema and we will configure basic account object type in wiki:Resource+Schema+Handling[resource schema handling section]:
MidPoint will discover LDAP schema and we will configure basic account object type in xref:/midpoint/reference/resources/resource-configuration/schema-handling/[resource schema handling section]:

.Basic account type configuration
[source,xml]
Expand Down Expand Up @@ -55,7 +55,7 @@ The "Distinguished Name" field will be marked as required.

But LDAP distinguished names are quite ugly (e.g. uid=foo,ou=people,dc=example,dc=com).
We definitely do not want users to enter that information manually every time the account is created.
So we define a wiki:Mapping[mapping] to determine distinguished name automatically from the username:
So we define a xref:/midpoint/reference/expressions/mappings/[mapping] to determine distinguished name automatically from the username:

.Account type with a mapping
[source,xml]
Expand Down Expand Up @@ -105,8 +105,8 @@ And there is a simple way to do it.

== Limitations and Layers

The wiki:Resource+Schema+Handling[resource schema handling] sections allows to specify _limitations_ for each attribute.
The limitations override the definitions in wiki:Resource+Schema[resource schema]. The limitations can change whether the attribute will be understood as required, optional, single-value or multi-value, whether it can be read, modified and so on.
The xref:/midpoint/reference/resources/resource-configuration/schema-handling/[resource schema handling] sections allows to specify _limitations_ for each attribute.
The limitations override the definitions in xref:/midpoint/reference/resources/resource-schema/[resource schema]. The limitations can change whether the attribute will be understood as required, optional, single-value or multi-value, whether it can be read, modified and so on.

However, it is usual that different limitations apply to different system layers.
E.g. we want the `dn` attribute to be presented as optional in the user interface because there is an outbound mapping for it.
Expand Down Expand Up @@ -172,10 +172,10 @@ Then any mapping that produces multiple values for these attributes will fail wh


| schema
| The wiki:Resource+Schema[Resource Schema] layer.
| The xref:/midpoint/reference/resources/resource-schema/[Resource Schema] layer.
This is the lowest layer.
Limitations on this layer can be used to override the values given by the wiki:Resource+Schema[resource schema]. Some resources notoriously present wrong schema and it must be corrected to use usable.
However the wiki:Resource+Schema[resource schema] is usually automatically generated and therefore it is not practical to modify it directly.
Limitations on this layer can be used to override the values given by the xref:/midpoint/reference/resources/resource-schema/[resource schema]. Some resources notoriously present wrong schema and it must be corrected to use usable.
However the xref:/midpoint/reference/resources/resource-schema/[resource schema] is usually automatically generated and therefore it is not practical to modify it directly.
This layer can be used as an elegant mechanism to correct such errors.


Expand All @@ -184,7 +184,7 @@ This layer can be used as an elegant mechanism to correct such errors.

== Object Template

Similarly as resource schema handling is used to modify the resource schema, wiki:Object+Template[object template] can be used to modify the schema of wiki:Focus+and+Projections[focal objects] (wiki:UserType[UserType], wiki:RoleType[RoleType], wiki:OrgType[OrgType]). The following example shows user template that is used to hide the `additionalName` property from the schema.
Similarly as resource schema handling is used to modify the resource schema, xref:/midpoint/reference/expressions/object-template/[object template] can be used to modify the schema of wiki:Focus+and+Projections[focal objects] (wiki:UserType[UserType], wiki:RoleType[RoleType], wiki:OrgType[OrgType]). The following example shows user template that is used to hide the `additionalName` property from the schema.

.Modifying schema in object template
[source,xml]
Expand Down Expand Up @@ -274,7 +274,7 @@ There are two variables available to the expression:

== Refined Schema

The native schema (wiki:Resource+Schema[Resource Schema] or a static wiki:Data+Model[Data Model]) is merged together with limitations in wiki:Resource+Schema+Handling[resource schema handling] and wiki:Object+Template[object template] to create a _refined schema_. The refined schema defines the effective schema that applies to current midPoint configuration.
The native schema (xref:/midpoint/reference/resources/resource-schema/[Resource Schema] or a static wiki:Data+Model[Data Model]) is merged together with limitations in xref:/midpoint/reference/resources/resource-configuration/schema-handling/[resource schema handling] and xref:/midpoint/reference/expressions/object-template/[object template] to create a _refined schema_. The refined schema defines the effective schema that applies to current midPoint configuration.
The concept of refined schema is not directly visible to the midPoint user.
But it is refined schema that is used to display user interface forms, evaluate mappings and so on.
The concept of refined schema is used all over the midPoint internal implementation, therefore it might be mentioned in the documentation, issues or samples.
Expand All @@ -283,7 +283,7 @@ The concept of refined schema is used all over the midPoint internal implementat
== Authorizations and Schema

One set of constraints is given by the (refined) schema.
But there is also a flexible wiki:Authorization[authorization mechanism] that determines who has access to what.
But there is also a flexible xref:/midpoint/reference/security/authorization/[authorization mechanism] that determines who has access to what.
Given the midPoint philosophy of efficiency, if an authorization allows user to see only part of the attributes then the user interface adapts automatically and it only shows the attributes that the user is allowed to see.
Similarly, if user is allowed to edit only some attributes the user interface adapts and correctly displays field as read-only or read-write.
Therefore the (refined) schema and authorizations are combined to provide final user experience.
Expand All @@ -301,7 +301,7 @@ Large number of authorizations might cause a scalability problem.

== See Also

* wiki:Resource+Schema+Handling[Resource Schema Handling]
* xref:/midpoint/reference/resources/resource-configuration/schema-handling/[Resource Schema Handling]

* wiki:Basic+Data+Model[Basic Data Model]

Expand Down

0 comments on commit f6c9a7a

Please sign in to comment.