[syncope] 03/03: [SYNCOPE-957] Documentation

[il...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

ilgrosso pushed a commit to branch 2_1_X
in repository https://gitbox.apache.org/repos/asf/syncope.git

commit d8d1700dde5d96007eda6f390c364e4d5fc7b84a
Author: Francesco Chicchiriccò <il...@apache.org>
AuthorDate: Thu Oct 31 13:40:10 2019 +0100

    [SYNCOPE-957] Documentation
---
 src/main/asciidoc/images/linked_accounts.png       | Bin 0 -> 183454 bytes
 src/main/asciidoc/images/linked_accounts.xml       |  20 +++++++++++++++++
 .../concepts/externalresources.adoc                |  24 +++++++++++++++++++++
 .../reference-guide/concepts/policies.adoc         |   8 +++----
 4 files changed, 48 insertions(+), 4 deletions(-)

diff --git a/src/main/asciidoc/images/linked_accounts.png b/src/main/asciidoc/images/linked_accounts.png
new file mode 100644
index 0000000..793cf87
Binary files /dev/null and b/src/main/asciidoc/images/linked_accounts.png differ
diff --git a/src/main/asciidoc/images/linked_accounts.xml b/src/main/asciidoc/images/linked_accounts.xml
new file mode 100644
index 0000000..89ae954
--- /dev/null
+++ b/src/main/asciidoc/images/linked_accounts.xml
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+<mxfile host="www.draw.io" modified="2019-10-31T12:36:37.509Z" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Ubuntu Chromium/77.0.3865.90 Chrome/77.0.3865.90 Safari/537.36" etag="prmw2re_9YNOJ9OtYV13" version="12.1.9" type="device" pages="1"><diagram id="VK5GpMV0TUeCPIBW4NtI" name="Page-1">7LzXruRMsyX2NP+lALLoL+m9J4vmZkDvXdHz6cXs/s6ZcyQNMAI0mJGgDfTeZBZNmogVa0Vk9b8QdrjEXzLX+pQX/b8+UH79C+H+9fkQOPn+Bg333waUwP42VL8m/9sE/9cGt3mKfxqhf1r3Ji/W/3ThNk391sz/uTGbxrHIt [...]
diff --git a/src/main/asciidoc/reference-guide/concepts/externalresources.adoc b/src/main/asciidoc/reference-guide/concepts/externalresources.adoc
index f47d018..6f91ed6 100644
--- a/src/main/asciidoc/reference-guide/concepts/externalresources.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/externalresources.adoc
@@ -235,3 +235,27 @@ previous working state.
 The maximum number of configurations to keep, for each Connector Instance and for each External Resource, is set by
 `connector.conf.history.size` and `resource.conf.history.size`: see <<configuration-parameters, below>> for details.
 ====
+
+==== Linked Accounts
+
+Sometimes the information provided by the <<mapping,mapping>> is not enough to define a one-to-one correspondence
+between Users / Groups / Any Objects and objects on External Resources.
+
+There can be many reasons for this situation, including existence of so-called _service accounts_ (typical with LDAP or
+Active Directory), or simply the uncomfortable reality that system integrators keep encountering when legacy systems
+are to be enrolled into a brand new IAM system.
+
+Starting with Apache Syncope 2.1.6, Users can have, on a given External Resource with `USER` mapping defined:
+
+. zero or one _mapped account_ +
+if the External Resource is assigned either directly or via Group membership.
+. zero or more _linked accounts_ +
+as internal representation of objects on the External Resource, defined in terms of username, password and / or plain
+attribute values override, with reference to the owning User.
+
+Linked Accounts are propagated alongside with owning User - following the existing
+<<push-correlation-rules,push correation rule>> if available - and pulled according to the given
+<<pull-correlation-rules,pull correation rule>>, if present.
+
+[.text-center]
+image::linked_accounts.png[title="Linked Accounts",alt="Linked Accounts"]
diff --git a/src/main/asciidoc/reference-guide/concepts/policies.adoc b/src/main/asciidoc/reference-guide/concepts/policies.adoc
index dbc3a58..2421f56 100644
--- a/src/main/asciidoc/reference-guide/concepts/policies.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/policies.adoc
@@ -299,8 +299,8 @@ different rule is required
 
 ===== Pull Correlation Rules
 
-Pull correlation rules define how to match objects received from <<connector-instance-details,connector instances>>
-with existing Users, Groups or Any Objects.
+Pull correlation rules define how to match objects received from <<external-resources>>
+with existing Users (including <<linked-accounts>>), Groups or Any Objects.
 
 The
 ifeval::["{snapshotOrRelease}" == "release"]
@@ -336,8 +336,8 @@ When set for resource R, a push policy is enforced on all Users, Groups and Any
 
 ===== Push Correlation Rules
 
-Push correlation rules define how to match existing Users, Groups or Any Objects with objects received from
-<<connector-instance-details,connector instances>>.
+Push correlation rules define how to match Users (including <<linked-accounts>>), Groups or Any Objects with
+objects existing on <<external-resources>>.
 
 The
 ifeval::["{snapshotOrRelease}" == "release"]