You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@syncope.apache.org by il...@apache.org on 2016/08/03 16:34:21 UTC
syncope git commit: [SYNCOPE-700] External resources and mapping
Repository: syncope
Updated Branches:
refs/heads/master 343b3d400 -> acb803e04
[SYNCOPE-700] External resources and mapping
Project: http://git-wip-us.apache.org/repos/asf/syncope/repo
Commit: http://git-wip-us.apache.org/repos/asf/syncope/commit/acb803e0
Tree: http://git-wip-us.apache.org/repos/asf/syncope/tree/acb803e0
Diff: http://git-wip-us.apache.org/repos/asf/syncope/diff/acb803e0
Branch: refs/heads/master
Commit: acb803e0478dcf005d88fd0f67c3b9773f334520
Parents: 343b3d4
Author: Francesco Chicchiricc� <il...@apache.org>
Authored: Wed Aug 3 18:33:58 2016 +0200
Committer: Francesco Chicchiricc� <il...@apache.org>
Committed: Wed Aug 3 18:34:03 2016 +0200
----------------------------------------------------------------------
.../test/resources/domains/MasterContent.xml | 9 +-
.../reference-guide/architecture/core.adoc | 2 +-
.../reference-guide/concepts/concepts.adoc | 14 +-
.../concepts/externalresources.adoc | 174 +++++++++++++++++++
.../concepts/provisioning/provisioning.adoc | 14 --
.../concepts/provisioning/pull.adoc | 11 +-
6 files changed, 195 insertions(+), 29 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/syncope/blob/acb803e0/core/persistence-jpa/src/test/resources/domains/MasterContent.xml
----------------------------------------------------------------------
diff --git a/core/persistence-jpa/src/test/resources/domains/MasterContent.xml b/core/persistence-jpa/src/test/resources/domains/MasterContent.xml
index 6035cf8..50c5388 100644
--- a/core/persistence-jpa/src/test/resources/domains/MasterContent.xml
+++ b/core/persistence-jpa/src/test/resources/domains/MasterContent.xml
@@ -961,13 +961,16 @@ under the License.
<Provision id="20a75199-3f2e-4b9a-9510-c68dd7fc7b3d" resource_id="resource-ldap" anyType_id="GROUP" objectClass="__GROUP__"/>
<Mapping id="128412c8-be4f-4d7b-8bed-5ab89134f718" provision_id="20a75199-3f2e-4b9a-9510-c68dd7fc7b3d"
connObjectLink="'cn=' + name + ',ou=groups,o=isp'"/>
- <MappingItem id="1" connObjectKey="1" password="0" mapping_id="128412c8-be4f-4d7b-8bed-5ab89134f718"
+ <MappingItem id="a2bf43c8-74cb-4250-92cf-fb8889409ac1"
+ connObjectKey="1" password="0" mapping_id="128412c8-be4f-4d7b-8bed-5ab89134f718"
extAttrName="cn" intAttrName="name"
mandatoryCondition="true" purpose="BOTH"/>
- <MappingItem id="2" connObjectKey="0" password="0" mapping_id="128412c8-be4f-4d7b-8bed-5ab89134f718"
+ <MappingItem id="da2a69bc-5ca0-4657-9a18-ec1f8c986046"
+ connObjectKey="0" password="0" mapping_id="128412c8-be4f-4d7b-8bed-5ab89134f718"
extAttrName="owner" intAttrName="userOwner"
mandatoryCondition="false" purpose="BOTH"/>
- <MappingItem id="3" connObjectKey="0" password="0" mapping_id="128412c8-be4f-4d7b-8bed-5ab89134f718"
+ <MappingItem id="9dde8bd5-f158-499e-9d81-3d7fcf9ea1e8"
+ IconnObjectKey="0" password="0" mapping_id="128412c8-be4f-4d7b-8bed-5ab89134f718"
extAttrName="description" intAttrName="title"
mandatoryCondition="false" purpose="BOTH"/>
http://git-wip-us.apache.org/repos/asf/syncope/blob/acb803e0/src/main/asciidoc/reference-guide/architecture/core.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/architecture/core.adoc b/src/main/asciidoc/reference-guide/architecture/core.adoc
index 4b65041..2d4ab54 100644
--- a/src/main/asciidoc/reference-guide/architecture/core.adoc
+++ b/src/main/asciidoc/reference-guide/architecture/core.adoc
@@ -53,7 +53,7 @@ reports and audit over all).
The Provisioning layer is involved with managing the internal (via workflow) and external (via specific connectors)
representation of users, groups and any objects.
-One of the most important features provided is the _mapping_ definition: internal data (users, for example)
+One of the most important features provided is the <<mapping,mapping>> definition: internal data (users, for example)
representation is correlated with information available on the available identity stores. +
Such definitions constitute the pillars of inbound (pull) and outbound (propagation / push)
<<provisioning,provisioning>>.
http://git-wip-us.apache.org/repos/asf/syncope/blob/acb803e0/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 3184701..3bea53f 100644
--- a/src/main/asciidoc/reference-guide/concepts/concepts.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/concepts.adoc
@@ -22,9 +22,7 @@ include::usersgroupsandanyobjects.adoc[]
include::typemanagement.adoc[]
-=== External Resources
-
-==== Mapping
+include::externalresources.adoc[]
=== Realms
@@ -36,8 +34,12 @@ include::provisioning/provisioning.adoc[]
=== Policies
+[[policies-account]]
==== Account
+===== Pass-through Authentication
+
+[[policies-password]]
==== Password
[[policies-pull]]
@@ -86,9 +88,8 @@ in one of super-realms of the realm of A~1~
The rationale behind such conditions is to allow the definition of common groups and any objects (to enter in
relationship with) at the topmost position in the realm tree, so that they can be shared by various realm sub-trees.
-[discrete]
-==== Example
-
+.Authorization
+====
Let's suppose that we want to implement the following scenario:
****
@@ -108,3 +109,4 @@ above:
* A: `USER_CREATE` on R~5~
* B: `USER_UPDATE` on R~6~ and R~8~
* C: `GROUP_UPDATE` on R~8~
+====
http://git-wip-us.apache.org/repos/asf/syncope/blob/acb803e0/src/main/asciidoc/reference-guide/concepts/externalresources.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/concepts/externalresources.adoc b/src/main/asciidoc/reference-guide/concepts/externalresources.adoc
new file mode 100644
index 0000000..7720a4a
--- /dev/null
+++ b/src/main/asciidoc/reference-guide/concepts/externalresources.adoc
@@ -0,0 +1,174 @@
+//
+// 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.
+//
+=== External Resources
+
+****
+Connector Bundles:: The components able to connect to identity stores; not specifically bound to Apache Syncope,
+as they are part of the http://connid.tirasa.net[ConnId^] project.
+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.
+****
+
+==== Connector Instance details
+
+When defining a connector instance, the following information is to be provided:
+
+* connector bundle - one of the several
+https://github.com/Tirasa/ConnId/blob/master/README.md#available-connectors[already available^], or some to be
+https://connid.atlassian.net/wiki/display/BASE/Create+new+connector[made from scratch^], in order to fulfill specific
+requirements
+* pooling information
+* configuration - dependening on the selected bundle, these are properties with configuration values: for example,
+with https://connid.atlassian.net/wiki/display/BASE/LDAP#LDAP-Configuration[LDAP^] this means host, port, bind DN,
+object classes while with
+https://connid.atlassian.net/wiki/display/BASE/Database+Table#DatabaseTable-ConfigurationProperties[DBMS^] it would
+be JDBC URL, table name, etc.
+* capabilities - define what operations are allowed on this connector: during <<provisioning,provisioning>>, if a
+certain operation is invoked but the corresponding capability is not set on the related connector instance, no actual
+action is performed on the underlying connector; the capabilities are:
+** `AUTHENTICATE` - consent <<pass-through-authentication, pass-through authentication>>
+** `CREATE` - create objects on the underlying connector
+** `UPDATE` - update objects on the underlying connector
+** `DELETE` - delete objects on the underlying connector
+** `SEARCH` - search / read objects from the underlying connector; used during <<provisioning-pull,pull>> with
+`FULL RECONCILIATION` or `FILTERED RECONCILIATION` <<pull-mode,mode>>
+** `SYNC` - synchronize objects from the underlying connector; used during <<provisioning-pull,pull>> with
+`INCREMENTAL` <<pull-mode,mode>>
+
+[TIP]
+.Configuration and capability override
+====
+Capabilities and individual configuration properties can be set for _override_: in this case, all the external resources
+using the given connector instance will have the chance to override some configuration values, or the capabilities set.
+
+This can be useful when the same connector instance is shared among different resources, with small difference in the
+required configuration or capabilities.
+====
+
+==== External Resource details
+
+Given a selected connector instance, the following information is required for defining an external resource:
+
+* priority - integer value, in use by the default <<propagation,propagation task executor>>
+* generate random password flag - under some circumstances, password might be mandatory but no actual value could be
+available: with this flag set, a random value will be generated, compliant with the defined
+<<policies-password,password policy>> (if set)
+* propagation actions - which <<propagationactions,actions>> shall be execute during propagation
+* trace levels - control how much tracing (including logs and execution details) shall be carried over during
+<<propagation,propagation>>, <<provisioning-pull,pull>> and <<provisioning-push,push>>
+* configuration - see <<connector-instance-details,above>>
+* capabilities - see <<connector-instance-details,above>>
+* account policy - which <<policies-account,account policy>> to enforce on users, groups and any objects assigned to
+this external resource
+* password policy - which <<policies-password,password policy>> to enforce on users, groups and any objects assigned to
+this external resource
+* pull policy - which <<policies-pull,pull policy>> to apply during <<provisioning-pull,pull>> on this external
+resource
+* push policy - which <<policies-push,push policy>> to apply during <<provisioning-push,push>> on this external
+resource
+
+==== Mapping
+
+One of the most crucial information to provide, when configuring an external resource, is the mapping between internal
+and external data. Such information, in fact, plays a key role for <<provisioning,provisioning>>.
+
+[.text-center]
+image::mapping.png[title="Sample mapping",alt="Sample mapping"]
+
+For each of the <<anytype,any types>> supported by the underlying connector, a different mapping is provided.
+
+Mapping is essentially a collection of _mapping items_ describing the correspondance between an user / group / any
+object attribute and its counterpart on the identity store represented by the current external resource; each item
+specifies:
+
+* internal attribute - the <<schema, schema>> acting as source or destination of provisioning operations; must be
+specified by an expression matching one of the following models:
+** `schema` - resolves to the attribute for the given `schema`, owned by the mapped entity (user, group, any object)
+** `groups[groupName].schema` - resolves to the attribute for the given `schema`, owned by the group with name
+`groupName`, if a membership for the mapped entity exists
+** `anyObjects[anyObjectName].schema` - resolves to the attribute for the given `schema`, owned by the any object with
+name `anyObjectName`, if a relationship with the mapped entity exists
+** `memberships[groupName].schema` - resolves to the attribute for the given `schema`, owned by the membership for group
+`groupName` of the mapped entity (user, any object), if such membership exists
+* external attribute - the name of the attribute on the identity store
+* transformers - http://commons.apache.org/proper/commons-jexl/[JEXL^] expression or Java class implementing
+ifeval::["{snapshotOrRelease}" == "release"]
+https://github.com/apache/syncope/blob/syncope-{docVersion}/core/provisioning-api/src/main/java/org/apache/syncope/core/provisioning/api/data/MappingItemTransformer.java[MappingItemTransformer^]
+endif::[]
+ifeval::["{snapshotOrRelease}" == "snapshot"]
+https://github.com/apache/syncope/blob/master/core/provisioning-api/src/main/java/org/apache/syncope/core/provisioning/api/data/MappingItemTransformer.java[MappingItemTransformer^]
+endif::[]
+; the purpose is to transform values before they are sent to or received from the underlying connector
+* mandatory condition - http://commons.apache.org/proper/commons-jexl/[JEXL^] expression indicating whether values for
+this mapping item must be necessarily available or not; compared to simple boolean value, such condition allows to
+express complex statements like as 'be mandatory only if this other attribute value is above 14', and so on
+* remote key flag - should this item be considered as the key value on the identity store?
+* password flag (users only) - should this item be treated as password value?
+* purpose - should this item be considered for <<propagation,propagation>> / <<push,push>>, <<pull,pull>>, both or none?
+
+Besides items, some more data needs to be specified for a complete mapping:
+
+* ConnId `objectClass` - which
+http://connid.tirasa.net/apidocs/1.4/org/identityconnectors/framework/common/objects/ObjectClass.html[object class^]
+shall be used during communication with identity store
+* Object link - only required by some connector bundles as
+https://connid.atlassian.net/wiki/display/BASE/LDAP[LDAP^] and
+https://connid.atlassian.net/wiki/pages/viewpage.action?pageId=360482[Active Directory^], generally specifies the model
+for generating the DN (distinguished name) values
+
+.Mapping items
+====
+The following mapping item binds mandatory the internal `name` schema with external attribute `cn` for both
+propagation / push and pull.
+
+[source,json]
+----
+{
+ "key": "a2bf43c8-74cb-4250-92cf-fb8889409ac1",
+ "intAttrName": "name",
+ "extAttrName": "cn",
+ "connObjectKey": true,
+ "password": false,
+ "mandatoryCondition": "true",
+ "purpose": "BOTH"
+}
+----
+
+The following mapping item binds optional the internal `aLong` schema for the membership of the `additional` group
+with external attribute `age` for propagation / push only; moreover, specifies JEXL expression which appends `.0`
+to the selected `aLong` value before sending out to the underlying connector.
+
+[source,json]
+----
+{
+ "key": "9dde8bd5-f158-499e-9d81-3d7fcf9ea1e8",
+ "intAttrName": "memberships[additional].aLong",
+ "extAttrName": "age",
+ "connObjectKey": false,
+ "password": false,
+ "mandatoryCondition": "false",
+ "purpose": "PROPAGATION",
+ "propagationJEXLTransformer": "value + '.0'"
+}
+----
+====
http://git-wip-us.apache.org/repos/asf/syncope/blob/acb803e0/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 3409f55..358f879 100644
--- a/src/main/asciidoc/reference-guide/concepts/provisioning/provisioning.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/provisioning/provisioning.adoc
@@ -39,20 +39,6 @@ The provisioning operations can be initiated in several different ways:
* 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 stores; 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[]
http://git-wip-us.apache.org/repos/asf/syncope/blob/acb803e0/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 48eae48..92fff96 100644
--- a/src/main/asciidoc/reference-guide/concepts/provisioning/pull.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/provisioning/pull.adoc
@@ -50,6 +50,7 @@ by default, unmatching entities gets internally created, and matching updated.
* `PROVISION`: create internally, do not assign the external resource;
****
+[[pull-mode]]
[TIP]
.Pull Mode
====
@@ -70,10 +71,10 @@ this condition. +
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^]
+https://github.com/apache/syncope/blob/syncope-{docVersion}/core/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^]
+https://github.com/apache/syncope/blob/master/core/provisioning-api/src/main/java/org/apache/syncope/core/provisioning/api/pushpull/PullActions.java[PullActions^]
endif::[]
interface.
@@ -84,7 +85,7 @@ Some examples are included by default, see table below.
|
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^]
+https://github.com/apache/syncope/blob/syncope-{docVersion}/core/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^]
@@ -93,7 +94,7 @@ endif::[]
|
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^]
+https://github.com/apache/syncope/blob/syncope-{docVersion}/core/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^]
@@ -104,7 +105,7 @@ https://connid.atlassian.net/wiki/display/BASE/LDAP#LDAP-Configuration[LDAP conn
|
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^]
+https://github.com/apache/syncope/blob/syncope-{docVersion}/core/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^]