From commits-return-10981-archive-asf-public=cust-asf.ponee.io@syncope.apache.org Wed Mar 14 10:32:25 2018 Return-Path: X-Original-To: archive-asf-public@cust-asf.ponee.io Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx-eu-01.ponee.io (Postfix) with SMTP id BE832180718 for ; Wed, 14 Mar 2018 10:32:24 +0100 (CET) Received: (qmail 28254 invoked by uid 500); 14 Mar 2018 09:32:23 -0000 Mailing-List: contact commits-help@syncope.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@syncope.apache.org Delivered-To: mailing list commits@syncope.apache.org Received: (qmail 28237 invoked by uid 99); 14 Mar 2018 09:32:23 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 14 Mar 2018 09:32:23 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id B27A8E96E4; Wed, 14 Mar 2018 09:32:23 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit From: ilgrosso@apache.org To: commits@syncope.apache.org Date: Wed, 14 Mar 2018 09:32:23 -0000 Message-Id: X-Mailer: ASF-Git Admin Mailer Subject: [1/2] syncope git commit: Adding clarification about CREATE / UPDATE generated as Propagation Tasks Repository: syncope Updated Branches: refs/heads/2_0_X 35ce733d1 -> 78827925a refs/heads/master eeb544634 -> aee229951 Adding clarification about CREATE / UPDATE generated as Propagation Tasks Project: http://git-wip-us.apache.org/repos/asf/syncope/repo Commit: http://git-wip-us.apache.org/repos/asf/syncope/commit/78827925 Tree: http://git-wip-us.apache.org/repos/asf/syncope/tree/78827925 Diff: http://git-wip-us.apache.org/repos/asf/syncope/diff/78827925 Branch: refs/heads/2_0_X Commit: 78827925a289af2c2831eeb36e41aef818fdbbc6 Parents: 35ce733 Author: Francesco Chicchiriccò Authored: Wed Mar 14 10:30:21 2018 +0100 Committer: Francesco Chicchiriccò Committed: Wed Mar 14 10:30:21 2018 +0100 ---------------------------------------------------------------------- .../concepts/provisioning/propagation.adoc | 62 ++++++++++++-------- .../workingwithapachesyncope/customization.adoc | 12 ++-- .../restfulservices.adoc | 4 +- 3 files changed, 47 insertions(+), 31 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/syncope/blob/78827925/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 f69b51d..9a4afff 100644 --- a/src/main/asciidoc/reference-guide/concepts/provisioning/propagation.adoc +++ b/src/main/asciidoc/reference-guide/concepts/provisioning/propagation.adoc @@ -24,6 +24,7 @@ Whenever a change is performed via REST on Users, Groups or Any Objects: . the generated propagation tasks are executed, e.g. the corresponding operations (create, update or delete) are sent out, via connectors, to the configured Identity Stores; the tasks can be saved for later re-execution. +[[propagation-resources]] [TIP] .Which external resources? ==== @@ -35,6 +36,7 @@ propagation process: * *Any Object*: the external resources directly assigned plus the ones assigned to Groups configured for the Any Object ==== +[[propagation-capabilities]] [WARNING] .Adequate capabilities to Connectors and External Resources ==== @@ -43,6 +45,28 @@ External Resources for the actual operations to perform, otherwise the Propagati execution status. ==== +[[propagation-password]] +[TIP] +.Propagate password values +==== +Password values are kept in the internal storage according to the `password.cipher.algorithm` +<>, whose value is `SHA1` by default. +`SHA1` is a hash algorithm: this means that, once stored, the cleartext value cannot be reverted any more. + +During propagation, Syncope fetches all data of the given User, then prepares the attributes to propagate, according to +the provided mapping; password has a special treatment: + +* if cleartext value is available (this cannot happen during <>), it is sent to the External Resource +* if `password.cipher.algorithm` is `AES` (the only supported reversible algorithm), then the ciphered password value is + made cleartext again, and sent to the External Resource +* if the <> is set, a random password value is generated + according to the defined password policies, and sent to the External Resource +* otherwise, a `null` value is sent to the External Resource + +Password values are always sent to External Resources wrapped as ConnId +http://connid.tirasa.net/apidocs/1.4/org/identityconnectors/common/security/GuardedString.html[GuardedString^] objects. +==== + 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^], @@ -61,6 +85,20 @@ 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 +[[propagation-createorupdate]] +[WARNING] +.Create or update? +==== +The minimization performed by `PriorityPropagationTaskExecutor` might lead to behaviors which look at first unexpected, +but sound perfectly understandable once explained; in particular: + +* a `CREATE` propagation task might result in an effective `UPDATE` sent to the Connector + + if preliminary read returns an external object matching the same remote key of the object requested to be created +* an `UPDATE` propagation task might result in an effective `CREATE` sent to the Connector + + if preliminary read does not find any external object matching the remote key of the objected requested to be +updated +==== + 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^] @@ -68,29 +106,7 @@ endif::[] ifeval::["{snapshotOrRelease}" == "snapshot"] https://github.com/apache/syncope/tree/2_0_X/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 behaviour does not fit into the provided implementation. - -[[propagation-password]] -[TIP] -.Propagate password values -==== -Password values are kept in the internal storage according to the `password.cipher.algorithm` -<>, whose value is `SHA1` by default. -`SHA1` is a hash algorithm: this means that, once stored, the cleartext value cannot be reverted any more. - -During propagation, Syncope fetches all data of the given User, then prepares the attributes to propagate, according to -the provided mapping; password has a special treatment: - -* if cleartext value is available (this cannot happen during <>), it is sent to the External Resource -* if `password.cipher.algorithm` is `AES` (the only supported reversible algorithm), then the ciphered password value is - made cleartext again, and sent to the External Resource -* if the <> is set, a random password value is generated - according to the defined password policies, and sent to the External Resource -* otherwise, a `null` value is sent to the External Resource - -Password values are always sent to External Resources wrapped as ConnId -http://connid.tirasa.net/apidocs/1.4/org/identityconnectors/common/security/GuardedString.html[GuardedString^] objects. -==== +interface can be provided, in case the required behavior does not fit into the provided implementation. ===== PropagationActions http://git-wip-us.apache.org/repos/asf/syncope/blob/78827925/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc index ccd8e2c..62c4fc2 100644 --- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc +++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc @@ -29,9 +29,9 @@ replaced. Once the project has been created from the provided Maven archetype, the generated source tree is available for either adding new features or replacing existing components. -[[override-behaviour]] +[[override-behavior]] [TIP] -.Override behaviour +.Override behavior ==== As a rule of thumb, any file of the local project will take precedence over a file with the same name in the same directory of the standard Apache Syncope release. @@ -60,7 +60,7 @@ ifeval::["{snapshotOrRelease}" == "snapshot"] https://github.com/apache/syncope/tree/2_0_X/client/console/src/main/resources/org/apache/syncope/client/console/pages/BasePage.html[BasePage.html^]. endif::[] -This general behaviour might have exceptions, as highlighted below. +This general behavior might have exceptions, as highlighted below. ==== In general, the Embedded Mode (see the @@ -177,7 +177,7 @@ When providing custom Java classes implementing the defined interfaces or extend implementations, their package *must* be rooted under `org.apache.syncope.core`, otherwise they will not be available at runtime. -Besides replacing existing classes as explained <>, new implementations can be provided under +Besides replacing existing classes as explained <>, new implementations can be provided under `core/src/main/java` for the following components: * <>, <>, <> and <> actions @@ -234,7 +234,7 @@ By following such conventions, the new REST endpoint will be automatically picke [WARNING] ==== -The <> might have exceptions; if you need to customize one of the +The <> might have exceptions; if you need to customize one of the Spring context definitions. For example, if you want to customize ifeval::["{snapshotOrRelease}" == "release"] https://github.com/apache/syncope/blob/syncope-{docVersion}/core/spring/src/main/resources/securityContext.xml[securityContext.xml^] @@ -498,7 +498,7 @@ Given the nature of the <>, all the files required by the A generated under the local project's `enduser/src/main/webapp/app/` directory and are available for full customization. The files in use by the Apache Wicket-based backend are still subject to the general -<>, instead. +<>, instead. [discrete] ===== Enable the <> extension http://git-wip-us.apache.org/repos/asf/syncope/blob/78827925/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices.adoc index f20b96c..c49f30c 100644 --- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices.adoc +++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices.adoc @@ -67,7 +67,7 @@ endif::[] ifeval::["{snapshotOrRelease}" == "snapshot"] https://github.com/apache/syncope/blob/2_0_X/core/spring/src/main/resources/securityContext.xml[securityContext.xml^]; endif::[] -while normally not needed, this configuration can be anyway customized via the <>. +while normally not needed, this configuration can be anyway customized via the <>. https://en.wikipedia.org/wiki/Basic_access_authentication[HTTP Basic Authentication] is set for use by default. ==== @@ -169,7 +169,7 @@ when communicating with <> with no Some REST endpoints - typically for creating, updating or deleting Users, Groups or Any Objects - return the entity in the response payload by default. + If this is not required, the `Prefer` request header can be set to `return-no-content` (`return-content` will instead -keep the default behaviour). +keep the default behavior). When `Prefer` is specified in the request, the response will feature the `Preference-Applied` header, with value set to the effective preference applied.