syncope-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ilgro...@apache.org
Subject [2/2] syncope git commit: [SYNCOPE-700] Concepts: Provisioning
Date Mon, 01 Aug 2016 16:09:37 GMT
[SYNCOPE-700] Concepts: Provisioning


Project: http://git-wip-us.apache.org/repos/asf/syncope/repo
Commit: http://git-wip-us.apache.org/repos/asf/syncope/commit/5c90dd82
Tree: http://git-wip-us.apache.org/repos/asf/syncope/tree/5c90dd82
Diff: http://git-wip-us.apache.org/repos/asf/syncope/diff/5c90dd82

Branch: refs/heads/master
Commit: 5c90dd82c8c79679ec2e75f12f8b056ea772704e
Parents: ecae3c1
Author: Francesco Chicchiriccò <ilgrosso@apache.org>
Authored: Mon Aug 1 18:09:27 2016 +0200
Committer: Francesco Chicchiriccò <ilgrosso@apache.org>
Committed: Mon Aug 1 18:09:27 2016 +0200

----------------------------------------------------------------------
 src/main/asciidoc/images/provisioningFlow.png   | Bin 0 -> 118368 bytes
 src/main/asciidoc/images/provisioningFlow.xml   |  20 +++
 .../reference-guide/concepts/concepts.adoc      |  31 ++++-
 .../concepts/provisioning/connectors.adoc       |  32 -----
 .../concepts/provisioning/propagation.adoc      | 109 +++++++++++++---
 .../concepts/provisioning/provisioning.adoc     |  47 +++++--
 .../concepts/provisioning/pull.adoc             | 129 ++++++++++++++-----
 .../concepts/provisioning/push.adoc             |  77 ++++++-----
 .../concepts/provisioning/resources.adoc        |  51 --------
 .../adminconsole/extensions.adoc                |   2 +-
 .../adminconsole/realms.adoc                    |   2 +-
 .../adminconsole/reports.adoc                   |   2 +-
 .../workingwithapachesyncope.adoc               |   3 +
 13 files changed, 320 insertions(+), 185 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/syncope/blob/5c90dd82/src/main/asciidoc/images/provisioningFlow.png
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/images/provisioningFlow.png b/src/main/asciidoc/images/provisioningFlow.png
new file mode 100644
index 0000000..054583d
Binary files /dev/null and b/src/main/asciidoc/images/provisioningFlow.png differ

http://git-wip-us.apache.org/repos/asf/syncope/blob/5c90dd82/src/main/asciidoc/images/provisioningFlow.xml
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/images/provisioningFlow.xml b/src/main/asciidoc/images/provisioningFlow.xml
new file mode 100644
index 0000000..d995480
--- /dev/null
+++ b/src/main/asciidoc/images/provisioningFlow.xml
@@ -0,0 +1,20 @@
+<mxfile userAgent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko)
Ubuntu Chromium/51.0.2704.79 Chrome/51.0.2704.79 Safari/537.36" version="5.5.5.2" editor="www.draw.io"
type="device">
+<!--
+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.
+-->
+<diagram>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</diagram></mxfile>

http://git-wip-us.apache.org/repos/asf/syncope/blob/5c90dd82/src/main/asciidoc/reference-guide/concepts/concepts.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/concepts/concepts.adoc b/src/main/asciidoc/reference-guide/concepts/concepts.adoc
index b906e0f..5fa9d51 100644
--- a/src/main/asciidoc/reference-guide/concepts/concepts.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/concepts.adoc
@@ -20,18 +20,16 @@
 
 === Data model
 
-==== Schema
+==== Users, Groups and Any objects
 
-==== Attributes
+==== Schema, Classes and Types
 
-==== Users, Groups and Any objects
+===== Mapping
 
 ==== Realms
 
 ==== Domains
 
-=== Tasks
-
 include::provisioning/provisioning.adoc[]
 
 === Policies
@@ -40,14 +38,33 @@ include::provisioning/provisioning.adoc[]
 
 ==== Password
 
-==== Push
-
+[[policies-pull]]
 ==== Pull
 
+[[policies-push]]
+==== Push
+
 === Workflow and Approval
 
 === Notifications
 
+=== Tasks
+
+[[tasks-propagation]]
+==== Propagation
+
+[[tasks-pull]]
+==== Pull
+
+[[tasks-push]]
+==== Push
+
+[[tasks-notification]]
+==== Notification
+
+[[tasks-generic]]
+==== Generic
+
 === Reports
 
 === Audit

http://git-wip-us.apache.org/repos/asf/syncope/blob/5c90dd82/src/main/asciidoc/reference-guide/concepts/provisioning/connectors.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/concepts/provisioning/connectors.adoc b/src/main/asciidoc/reference-guide/concepts/provisioning/connectors.adoc
deleted file mode 100644
index 835d95a..0000000
--- a/src/main/asciidoc/reference-guide/concepts/provisioning/connectors.adoc
+++ /dev/null
@@ -1,32 +0,0 @@
-//
-// 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.
-//
-==== Connectors
-Syncope uses entities like connectors bundles, connector instances and external resources
to synchronize user accounts 
-with and propagate to external systems. This paragraph clarifies what the responsibility
and scope of each of these entities are.
-
-===== Connector bundle
-Connector bundles are the components that are able to connect to classes of systems when
configured correctly and 
-told to do so. They are not bound to Syncope specifically, as they are part of the separate
framework 
-http://connid.tirasa.net/[ConnId], but  they can be plugged into a deployed Syncope system.
-
-===== Connector instance
-Connectors instances are instance of connector bundles, obtained by assigning values to configuration
properties
-defined in bundles.
-For instance, there is only a single "DatabaseTable connector" (the bundle) that can be instantiated
many times, for 
-example if there is need to connect to two different databases.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/syncope/blob/5c90dd82/src/main/asciidoc/reference-guide/concepts/provisioning/propagation.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/concepts/provisioning/propagation.adoc b/src/main/asciidoc/reference-guide/concepts/provisioning/propagation.adoc
index d58ba53..e7dfee4 100644
--- a/src/main/asciidoc/reference-guide/concepts/provisioning/propagation.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/provisioning/propagation.adoc
@@ -17,18 +17,97 @@
 // under the License.
 //
 ==== Propagation
-The propagation is the mechanism to extend provisioning operations on external resources.
-The propagation layer implements remote creation, maintenance, activation and deactivation
of user and role objects 
-and their attributes.
-A propagation towards a specific external resource occurs if and only if the external resource's
connector 
-instance capabilities permit.
-Propagation will be tried on an external resource for each provisioning operation involving
users or roles assigned 
-to that resource.
-
-===== Configuration
-Connectors::
-Connector instances can be configured to create, update and delete operations.
-Propagation tasks::
-When propagation tasks are created, their propagation mode will be set according to the mode
of the external resource.
-Operation::
-When tasks are executed, the execution status will be set to SUCCESS or FAILURE, based on
the actual propagation result.
\ No newline at end of file
+
+Whenever a change is performed via REST on users, groups or any objects:
+
+. a set of <<tasks-propagation,propagation tasks>> is generated, one for each
associated external resource;
+. the generated propagation tasks are executed, e.g. the corresponding operations (create,
update or delete) are sent
+out, via connectors, to the configured identity repositories; the tasks can be saved for
later re-execution.
+
+[TIP]
+.Which external resources?
+====
+Depending on the entity being created / updated / deleted, different external resources are
taken into account by the
+propagation process:
+
+* *group*: only the external resources directly assigned
+* *user*: the external resources directly assigned plus the ones assigned to groups configured
for the user
+* *any object*: the external resources directly assigned plus the ones assigned to groups
configured for the any object
+====
+
+By default, the propagation process is controlled by the
+ifeval::["{snapshotOrRelease}" == "release"]
+https://github.com/apache/syncope/blob/syncope-{docVersion}/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/propagation/PriorityPropagationTaskExecutor.java[PriorityPropagationTaskExecutor^],
+endif::[]
+ifeval::["{snapshotOrRelease}" == "snapshot"]
+https://github.com/apache/syncope/blob/master/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/propagation/PriorityPropagationTaskExecutor.java[PriorityPropagationTaskExecutor^],
+endif::[]
+which implements the following logic:
+
+* sort the tasks according to the related resource's _priority_, then execute sequentially
+* tasks for resources with no priority are executed afterwards, concurrently
+* the execution of a given set of tasks is halted (and global failure is reported) whenever
the first sequential task
+fails
+* status and eventual error message (in case of no resource priority) can be saved for reporting,
in case the related
+external resource was configured with adequate tracing
+* minimize the set of operations to be actually performed onto the identity store by attempting
to read the external
+object corresponding to the internal entity and comparing with the modifications provided
+
+Different implementations of the
+ifeval::["{snapshotOrRelease}" == "release"]
+https://github.com/apache/syncope/blob/syncope-{docVersion}/core/provisioning-api/src/main/java/org/apache/syncope/core/provisioning/api/propagation/PropagationTaskExecutor.java[PropagationTaskExecutor^]
+endif::[]
+ifeval::["{snapshotOrRelease}" == "snapshot"]
+https://github.com/apache/syncope/blob/master/core/provisioning-api/src/main/java/org/apache/syncope/core/provisioning/api/propagation/PropagationTaskExecutor.java[PropagationTaskExecutor^]
+endif::[]
+interface can be provided, in case the required behavior does not fit into the provided implementation.
+
+===== PropagationActions
+
+The propagation process can be decorated with custom logic to be invoked around task execution,
by associating
+external resources to one or more implementations of the
+ifeval::["{snapshotOrRelease}" == "release"]
+https://github.com/apache/syncope/blob/syncope-{docVersion}/core/provisioning-api/src/main/java/org/apache/syncope/core/provisioning/api/propagation/PropagationActions.java[PropagationActions^]
+endif::[]
+ifeval::["{snapshotOrRelease}" == "snapshot"]
+https://github.com/apache/syncope/blob/master/core/provisioning-api/src/main/java/org/apache/syncope/core/provisioning/api/propagation/PropagationActions.java[PropagationActions^]
+endif::[]
+interface.
+
+Some examples are included by default, see table below.
+
+[cols="1,2"]
+|===
+
+| 
+ifeval::["{snapshotOrRelease}" == "release"]
+https://github.com/apache/syncope/blob/syncope-{docVersion}/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/propagation/LDAPMembershipPropagationActions.java[LDAPMembershipPropagationActions^]
+endif::[]
+ifeval::["{snapshotOrRelease}" == "snapshot"]
+https://github.com/apache/syncope/blob/master/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/propagation/LDAPMembershipPropagationActions.java[LDAPMembershipPropagationActions^]
+endif::[]
+| If user is associated to group in Syncope, keeps the corresponding user as member of the
corresponding group on LDAP.
+
+| 
+ifeval::["{snapshotOrRelease}" == "release"]
+https://github.com/apache/syncope/blob/syncope-{docVersion}/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/propagation/LDAPPasswordPropagationActions.java[LDAPPasswordPropagationActions^]
+endif::[]
+ifeval::["{snapshotOrRelease}" == "snapshot"]
+https://github.com/apache/syncope/blob/master/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/propagation/LDAPPasswordPropagationActions.java[LDAPPasswordPropagationActions^]
+endif::[]
+| If no password value was already provided in the propagation task, sends out the internal
password hash value to LDAP;
+the cipher algorithm associated with the password must match the value of `passwordHashAlgorithm`
for the 
+https://connid.atlassian.net/wiki/display/BASE/LDAP#LDAP-Configuration[LDAP connector bundle^].
+
+| 
+ifeval::["{snapshotOrRelease}" == "release"]
+https://github.com/apache/syncope/blob/syncope-{docVersion}/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/propagation/LDAPPasswordPropagationActions.java[DBPasswordPropagationActions^]
+endif::[]
+ifeval::["{snapshotOrRelease}" == "snapshot"]
+https://github.com/apache/syncope/blob/master/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/propagation/DBPasswordPropagationActions.java[DBPasswordPropagationActions^]
+endif::[]
+| If no password value was already provided in the propagation task, sends out the internal
password hash value to DBMS;
+the cipher algorithm associated with the password must match the value of `Password cipher
algorithm` for the 
+https://connid.atlassian.net/wiki/display/BASE/Database+Table#DatabaseTable-ConfigurationProperties[DatabaseTable
connector bundle^].
+
+|===

http://git-wip-us.apache.org/repos/asf/syncope/blob/5c90dd82/src/main/asciidoc/reference-guide/concepts/provisioning/provisioning.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/concepts/provisioning/provisioning.adoc b/src/main/asciidoc/reference-guide/concepts/provisioning/provisioning.adoc
index 4a9c957..eb42f97 100644
--- a/src/main/asciidoc/reference-guide/concepts/provisioning/provisioning.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/provisioning/provisioning.adoc
@@ -17,21 +17,44 @@
 // under the License.
 //
 === Provisioning
-The main purpose of identity management systems is to manage user and role provisioning.
-User and role provisioning refers to the creation, maintenance, activation and deactivation
of user and role objects
-and their attributes. Provisioning operations can act on Apache Syncope only or be propagated
towards external
-resources as well.
-The provisioning operation can be initiated by an authorized user (for instance, working
on Apache Syncope
-administration console) or by an internal task like a pull task.
-A push task can be used to perform a bulk provisioning operation involving either Syncope
and one
-or more external resources.
 
-include::connectors.adoc[]
+As introduced <<provisioning-engines,above>>, provisioning is actually the core
feature provided by Apache Syncope.
 
-include::resources.adoc[]
+Essentially, it can be seen as the process of keeping the identity data, on Syncope and related
external resources, 
+synchronized according to the specifications provided by the <<mapping,mapping>>
by performing create, update and
+delete operations onto the <<persistence,internal storage>> or external resources
via connectors.
 
-include::propagation.adoc[]
+==== Overview
 
-include::push.adoc[]
+The picture below contains an expanded view of the <<architecture,core architecture>>,
with particular reference to the
+components involved in the provisioning process.
+
+[.text-center]
+image::provisioningFlow.png[title="Provisioning flow",alt="Provisioning flow"]
+
+The provisioning operations can be initiated in several different ways:
+
+* by creating, updating or deleting users, groups or any objects via REST (thus involving
the underlying 
+<<logic,logic>> layer)
+* by requesting execution of pull or push tasks via REST
+* by triggering periodic pull or push task execution
+
+==== Connectors and Resources
+
+****
+Connector Bundles:: The components able to connect to Identity Repositories; not specifically
bound to Apache Syncope, 
+as they are part of the http://connid.tirasa.net[ConnId^] project. Custom connectors can
also be 
+https://connid.atlassian.net/wiki/display/BASE/Create+new+connector[made from scratch^].
+Connector Instances:: Instances of connector bundles, obtained by assigning values to the
defined configuration 
+properties. For instance, there is only a single `DatabaseTable` (the bundle) that can be
instantiated
+several times, for example if there is need to connect to different databases.
+External Resources:: Meant to encapsulate all information about how Apache Syncope will use
connector instances for 
+provisioning. For each entity supported by the related connector bundle (user, group, printer,
services, ...),
+<<mapping,mapping>> information can be specified.
+****
+
+include::propagation.adoc[]
 
 include::pull.adoc[]
+
+include::push.adoc[]

http://git-wip-us.apache.org/repos/asf/syncope/blob/5c90dd82/src/main/asciidoc/reference-guide/concepts/provisioning/pull.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/concepts/provisioning/pull.adoc b/src/main/asciidoc/reference-guide/concepts/provisioning/pull.adoc
index bf2157a..fe3491a 100644
--- a/src/main/asciidoc/reference-guide/concepts/provisioning/pull.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/provisioning/pull.adoc
@@ -16,37 +16,100 @@
 // specific language governing permissions and limitations
 // under the License.
 //
+[[provisioning-pull]]
 ==== Pull
-Basically, pull is the mechanism used by Apache Syncope to acquire user, group and any objects
data from external resources.
-Pull can be "full" (full reconciliation) or "incremental".
-In the former case, each pull task execution will take over just of changes from the previous
execution 
-(if exists and connector permits incremental pull).
-In the latter case, each pull task execution will take over of the entire set of data managed
by the external resource.
-
-===== From an external resource to Syncope
-All the entity (user/group) data involved by a pull are retrieved from an external resource
and processed 
-internally by Syncope itself.
-A retrieved entity can be:
-
-. a matching entity, if a corresponding local/internal entity has been found;
-. or an unmatching entity, otherwise.
-
-By default, Syncope will create locally all the unmatching entities (without linking entities
and resources) and will 
-update all the matching ones.
-By the way, a different behaviour can be configured working with matching/unmatching rules.
-
-===== Matching and Unmatching rules
-Unmatching (corresponding user not found on Syncope):
-
-* IGNORE / UNLINK (do not perform any action);
-* ASSIGN (create entity linking the resource);
-* PROVISION (create entity without linking the resource).
-
-Matching (corresponding users found on Syncope):
-
-* IGNORE (do not perform any action);
-* UPDATE (update matching entity);
-* DEPROVISION (delete resource entity);
-* UNASSIGN (unlink resource and delete resource entity) ;
-* UNLINK (just unlink resource without performing any (de-)provisioning operation);
-* LINK (just link resource without performing any (de-)provisioning operation).
\ No newline at end of file
+
+Pull is the mechanism used to acquire identity data from identity repositories; for each
external resource, one or more
+<<tasks-pull,pull tasks>> can be defined, run and scheduled for period execution.
+
+Pull task execution involves querying the external resource and then process each entity
in an isolated transaction; 
+a retrieved entity can be:
+
+. _matching_ if a corresponding internal entity was found, according to the <<policies-pull,pull
policy>> set for the
+enclosing external resource;
+. _unmatching_ otherwise.
+
+Once assessed this, entities are processed according to the matching / unmatching rules specified
for the pull task:
+by default, unmatching entities gets internally created, and matching updated.
+
+.Matching Rules
+****
+* `IGNORE`: do not perform any action;
+* `UPDATE`: update matching entity;
+* `DEPROVISION`: delete external entity;
+* `UNLINK`: remove association with external resource, without performing any (de-)provisioning
operation;
+* `LINK`: associate with external resource, without performing any (de-)provisioning operation.
+* `UNASSIGN`: unlink and delete;
+****
+
+.Unmatching Rules
+****
+* `IGNORE`: do not perform any action;
+* `UNLINK`: do not perform any action;
+* `ASSIGN`: create internally, assign the external resource;
+* `PROVISION`: create internally, do not assign the external resource;
+****
+
+[TIP]
+.Pull Mode
+====
+The identity repository can be queried in different ways, depending on the _pull mode_ specified:
+
+****
+FULL RECONCILIATION:: The complete list of entities available is processed.
+FILTERED RECONCILIATION:: The subset matching the provided filter of all available entities
is processed.
+INCREMENTAL:: Only the actual modifications performed since last pull task execution are
considered. This mode requires
+the underlying connector bundle to implement the ConnId `SYNC` operation - only some of the
available bundles match
+this condition.
+****
+====
+
+===== PullActions
+
+The pull process can be decorated with custom logic to be invoked around task execution,
by associating
+pull tasks to one or more implementations of the
+ifeval::["{snapshotOrRelease}" == "release"]
+https://github.com/apache/syncope/blob/master/syncope-{docVersion}/provisioning-api/src/main/java/org/apache/syncope/core/provisioning/api/pushpull/PullActions.java[PullActions^]
+endif::[]
+ifeval::["{snapshotOrRelease}" == "snapshot"]
+https://github.com/apache/syncope/blob/master/master/provisioning-api/src/main/java/org/apache/syncope/core/provisioning/api/pushpull/PullActions.java[PullActions^]
+endif::[]
+interface.
+
+Some examples are included by default, see table below.
+
+[cols="1,2"]
+|===
+
+| 
+ifeval::["{snapshotOrRelease}" == "release"]
+https://github.com/apache/syncope/blob/master/syncope-{docVersion}/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/pushpull/LDAPMembershipPullActions.java[LDAPMembershipPullActions^]
+endif::[]
+ifeval::["{snapshotOrRelease}" == "snapshot"]
+https://github.com/apache/syncope/blob/master/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/pushpull/LDAPMembershipPullActions.java[LDAPMembershipPullActions^]
+endif::[]
+| If user is associated to group on LDAP, keeps the corresponding user as member of the corresponding
group on Syncope.
+
+| 
+ifeval::["{snapshotOrRelease}" == "release"]
+https://github.com/apache/syncope/blob/master/syncope-{docVersion}/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/pushpull/LDAPPasswordPullActions.java[LDAPPasswordPullActions^]
+endif::[]
+ifeval::["{snapshotOrRelease}" == "snapshot"]
+https://github.com/apache/syncope/blob/master/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/pushpull/LDAPPasswordPullActions.java[LDAPPasswordPullActions^]
+endif::[]
+| Import hashed password values from LDAP;
+the cipher algorithm associated with the password must match the value of `passwordHashAlgorithm`
for the 
+https://connid.atlassian.net/wiki/display/BASE/LDAP#LDAP-Configuration[LDAP connector bundle^].
+
+| 
+ifeval::["{snapshotOrRelease}" == "release"]
+https://github.com/apache/syncope/blob/master/syncope-{docVersion}/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/pushpull/DBPasswordPullActions.java[DBPasswordPullActions^]
+endif::[]
+ifeval::["{snapshotOrRelease}" == "snapshot"]
+https://github.com/apache/syncope/blob/master/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/pushpull/DBPasswordPullActions.java[DBPasswordPullActions^]
+endif::[]
+| Import hashed password values from DBMS;
+the cipher algorithm associated with the password must match the value of `Password cipher
algorithm` for the 
+https://connid.atlassian.net/wiki/display/BASE/Database+Table#DatabaseTable-ConfigurationProperties[DatabaseTable
connector bundle^].
+
+|===

http://git-wip-us.apache.org/repos/asf/syncope/blob/5c90dd82/src/main/asciidoc/reference-guide/concepts/provisioning/push.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/concepts/provisioning/push.adoc b/src/main/asciidoc/reference-guide/concepts/provisioning/push.adoc
index 06ea053..4e043b9 100644
--- a/src/main/asciidoc/reference-guide/concepts/provisioning/push.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/provisioning/push.adoc
@@ -16,36 +16,49 @@
 // specific language governing permissions and limitations
 // under the License.
 //
+[[provisioning-push]]
 ==== Push
-Basically, the push is a sort of synchronization mechanism used by Apache Syncope to propagate
a filtered set of 
-user/role/membership data to external resources.
-Push can be "full" only: all the data matching the configured filter (potentially the same
set of data) will be sent 
-to the external resource at each push task execution.
-
-===== From Syncope to an external resource
-All the entity (user/group) data involved by a push are retrieved locally and compared with
remote ones before sending out.
-An entity to be sent out can be:
-
-. a matching entity, if a corresponding remote entity has been found;
-. or an unmatching entity, otherwise.
-
-By default, Syncope will propagate all the unmatching entities for provisioning (without
linking entities and resources) 
-and will update all the matching ones.
-By the way, a different behaviour can be configured working with matching/unmatching rules.
-
-===== Matching and Unmatching rules
-Unmatching (corresponding user not found on external resource):
-
-* IGNORE (do not perform any action);
-* UNLINK (just unlink resource without performing any (de-)provisioning operation - of course,
if any link is found);
-* ASSIGN (provision entity linking the resource);
-* PROVISION (provision entity without linking the resource).
-
-Matching (corresponding users found on external resource):
-
-* IGNORE (do not perform any action);
-* UPDATE (update matching entity);
-* DEPROVISION (delete resource entity);
-* UNASSIGN (unlink resource and delete resource entity) ;
-* UNLINK (just unlink resource without performing any (de-)provisioning operation);
-* LINK (just link resource without performing any (de-)provisioning operation).
\ No newline at end of file
+
+With push, the matching set of internal entities can be sent to identity repositories - mainly
for
+(re)initialization purposes; for each external resource, one or more <<tasks-push,push
tasks>> can be defined, run and 
+scheduled for period execution.
+
+Push task execution involves querying the internal storage and then process each entity in
an isolated transaction; 
+an internal entity can be:
+
+. _matching_ if a corresponding remote entity was found, according to the <<policies-push,push
policy>> set for the
+enclosing external resource;
+. _unmatching_ otherwise.
+
+Once assessed this, entities are processed according to the matching / unmatching rules specified
for the push task:
+by default, unmatching entities are pushed to identity repositories, and matching updated.
+
+.Matching Rules
+****
+* `IGNORE`: do not perform any action;
+* `UPDATE`: update matching entity;
+* `DEPROVISION`: delete internal entity;
+* `UNLINK`: remove association with external resource, without performing any (de-)provisioning
operation;
+* `LINK`: associate with external resource, without performing any (de-)provisioning operation.
+* `UNASSIGN`: unlink and delete;
+****
+
+.Unmatching Rules
+****
+* `IGNORE`: do not perform any action;
+* `UNLINK`: remove association with external resource, without performing any (de-)provisioning
operation;
+* `ASSIGN`: create externally, assign the external resource;
+* `PROVISION`: create externally, do not assign the external resource;
+****
+
+===== PushActions
+
+The push process can be decorated with custom logic to be invoked around task execution,
by associating
+push tasks to one or more implementations of the
+ifeval::["{snapshotOrRelease}" == "release"]
+https://github.com/apache/syncope/blob/syncope-{docVersion}/core/provisioning-api/src/main/java/org/apache/syncope/core/provisioning/api/pushpull/PushActions.java[PushActions^]
+endif::[]
+ifeval::["{snapshotOrRelease}" == "snapshot"]
+https://github.com/apache/syncope/blob/master/core/provisioning-api/src/main/java/org/apache/syncope/core/provisioning/api/pushpull/PushActions.java[PushActions^]
+endif::[]
+interface.

http://git-wip-us.apache.org/repos/asf/syncope/blob/5c90dd82/src/main/asciidoc/reference-guide/concepts/provisioning/resources.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/concepts/provisioning/resources.adoc b/src/main/asciidoc/reference-guide/concepts/provisioning/resources.adoc
deleted file mode 100644
index 03c78af..0000000
--- a/src/main/asciidoc/reference-guide/concepts/provisioning/resources.adoc
+++ /dev/null
@@ -1,51 +0,0 @@
-//
-// 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.
-//
-==== Resources
-The propagation implements the provisioning on external resources. It depends on the assignment,
directly or indirectly
- (via memberships), of users/roles to external resources.
-Users and roles can be assigned or linked to an external resource in three different ways:
with a soft link, 
-with a hard link, without any link (see below for more details).
-Each provisioning operation involving a certain user/role will be propagated (if permitted
by resource connector 
-instance capabilities) towards each resource linked by the user/role object itself.
-In general, the provisioning won't occur on a certain external resource if any direct/indirect
link exists with 
-that resource.
-
-===== Manage external resource provisioning directly
-Provisioning will occur on a certain external resource every time the operation involves
users or roles assigned 
-to that resource.
-Users and roles can be assigned to an external resource by defining a direct or indirect
link between objects.
-By the way, Apache Syncope empowers the possibility to control the existence of users/roles
on external resources 
-giving the possibility to manage remote provisioning directly.
-In fact, an authorized user (or an internal task - a pull task, for instance) can ask for

-
-* *link / unlink* users/roles to/from specific resources (soft link), 
-* *assign / unassign* users/roles to/from specific resources (hard link),
-* *provision / de-provision* users/roles on/from specific resources (maybe, without any link).
-
-link/unlink::
-Apache Syncope gives the possibility to create and remove a sort of soft linking between
users/roles and resources.
-This kind of link doesn't imply any propagation at link creation/deletion time.
-Provision/De-Provision::
-Apache Syncope gives the possibility to directly provision and de-provision users/roles on/from
resources, without any 
-link in place. This provisioning feature (disjoint from the resource link mechanisms) is
often very useful in case 
-of reclaims.
-Assign/Unassign::
-Apache Syncope gives the possibility to create and remove a sort of hard linking between
users/roles and resources.
-This kind of link implies propagation at link creation/deletion time: it is the composition
between link/unlink and 
-provision/de-provision operations.

http://git-wip-us.apache.org/repos/asf/syncope/blob/5c90dd82/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/extensions.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/extensions.adoc
b/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/extensions.adoc
index 2b67000..63dc080 100644
--- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/extensions.adoc
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/extensions.adoc
@@ -16,7 +16,7 @@
 // specific language governing permissions and limitations
 // under the License.
 //
-
+[[console-extensions]]
 ===== Extensions
 The extensions tab shows the extensions installed on the given Apache Syncope deployment.
 

http://git-wip-us.apache.org/repos/asf/syncope/blob/5c90dd82/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/realms.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/realms.adoc
b/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/realms.adoc
index 3f9d89f..b3d60cd 100644
--- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/realms.adoc
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/realms.adoc
@@ -16,7 +16,7 @@
 // specific language governing permissions and limitations
 // under the License.
 //
-
+[[console-realms]]
 ===== Realms
 The realms tab provides the admin with the power to manage users, groups and any objects,
for all any types defined.
 

http://git-wip-us.apache.org/repos/asf/syncope/blob/5c90dd82/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/reports.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/reports.adoc
b/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/reports.adoc
index 907b9ae..c32f8f2 100644
--- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/reports.adoc
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/adminconsole/reports.adoc
@@ -16,7 +16,7 @@
 // specific language governing permissions and limitations
 // under the License.
 //
-
+[[console-reports]]
 ===== Reports
 The reports tab presents the admin with the reports generated from various jobs run on the
syncope
 deployment. These reports are displayed using report templates which can be defined for FO,
HTML

http://git-wip-us.apache.org/repos/asf/syncope/blob/5c90dd82/src/main/asciidoc/reference-guide/workingwithapachesyncope/workingwithapachesyncope.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/workingwithapachesyncope.adoc
b/src/main/asciidoc/reference-guide/workingwithapachesyncope/workingwithapachesyncope.adoc
index c8777bf..cfcdde5 100644
--- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/workingwithapachesyncope.adoc
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/workingwithapachesyncope.adoc
@@ -36,10 +36,13 @@ include::restfulservices/restful-services.adoc[]
 
 === Customization
 
+[[customization-core]]
 ==== Core
 
+[[customization-console]]
 ==== Console
 
+[[customization-enduser]]
 ==== Enduser
 
 ==== New extensions


Mime
View raw message