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 2019/10/31 12:42:18 UTC
[syncope] 02/03: Docs review
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 e8949ee905b44373fa42360a1b3e18c75618247a
Author: Francesco Chicchiriccò <il...@apache.org>
AuthorDate: Thu Oct 31 10:39:21 2019 +0100
Docs review
---
pom.xml | 5 ++-
.../asciidoc/getting-started/introduction.adoc | 2 +-
.../getting-started/systemRequirements.adoc | 6 +--
.../reference-guide/architecture/architecture.adoc | 47 ++++++++++++++++++++++
.../reference-guide/architecture/core.adoc | 5 ++-
.../concepts/externalresources.adoc | 5 ++-
.../reference-guide/concepts/implementations.adoc | 4 +-
.../concepts/provisioning/propagation.adoc | 2 +-
.../asciidoc/reference-guide/concepts/tasks.adoc | 6 +--
.../reference-guide/concepts/typemanagement.adoc | 4 ++
.../concepts/usersgroupsandanyobjects.adoc | 47 ----------------------
.../workingwithapachesyncope/customization.adoc | 2 +-
.../systemadministration/dbms.adoc | 10 ++---
13 files changed, 77 insertions(+), 68 deletions(-)
diff --git a/pom.xml b/pom.xml
index 33780c2..fa2376c 100644
--- a/pom.xml
+++ b/pom.xml
@@ -534,7 +534,7 @@ under the License.
<protractor.version>5.4.0</protractor.version>
<docker.postgresql.version>11.5</docker.postgresql.version>
- <docker.mysql.version>8.0</docker.mysql.version>
+ <docker.mysql.version>8.0.18</docker.mysql.version>
<docker.mariadb.version>10.4</docker.mariadb.version>
<jdbc.postgresql.version>42.2.8</jdbc.postgresql.version>
@@ -2572,6 +2572,9 @@ under the License.
<attributes>
<docVersion>${project.version}</docVersion>
<snapshotOrRelease>${snapshotOrRelease}</snapshotOrRelease>
+ <postgresql>${docker.postgresql.version}</postgresql>
+ <mysql>${docker.mysql.version}</mysql>
+ <mariadb>${docker.mariadb.version}</mariadb>
<postgresqlJDBC>${jdbc.postgresql.version}</postgresqlJDBC>
<mysqlJDBC>${jdbc.mysql.version}</mysqlJDBC>
<mariadbJDBC>${jdbc.mariadb.version}</mariadbJDBC>
diff --git a/src/main/asciidoc/getting-started/introduction.adoc b/src/main/asciidoc/getting-started/introduction.adoc
index d9fe3d1..6a1a523 100644
--- a/src/main/asciidoc/getting-started/introduction.adoc
+++ b/src/main/asciidoc/getting-started/introduction.adoc
@@ -119,7 +119,7 @@ implementation is also available as an extension, which brings all the power of
from a provided list - including one based on http://www.flowable.org/[Flowable^], the reference open source
http://www.bpmn.org/[BPMN 2.0^] implementations - or define new, custom ones.
* *_Persistence_* manages all data (users, groups, attributes, resources, ...) at a high level
-using a standard https://en.wikipedia.org/wiki/Java_Persistence_API[JPA 2.0^] approach. The data is persisted to an underlying
+using a standard https://en.wikipedia.org/wiki/Java_Persistence_API[JPA 2.2^] approach. The data is persisted to an underlying
database, referred to as *_Internal Storage_*. Consistency is ensured via the comprehensive
http://docs.spring.io/spring/docs/4.2.x/spring-framework-reference/html/transaction.html[transaction management^]
provided by the Spring Framework. +
diff --git a/src/main/asciidoc/getting-started/systemRequirements.adoc b/src/main/asciidoc/getting-started/systemRequirements.adoc
index dfad95e..d88f1fc 100644
--- a/src/main/asciidoc/getting-started/systemRequirements.adoc
+++ b/src/main/asciidoc/getting-started/systemRequirements.adoc
@@ -45,8 +45,8 @@ Apache Syncope {docVersion} is verified with the following Java EE containers:
Apache Syncope {docVersion} is verified with the recent versions of the following DBMSes, for internal storage:
- . http://www.postgresql.org/[PostgreSQL^] (>= 10.3, JDBC driver >= {postgresqlJDBC})
- . https://mariadb.org/[MariaDB^] (>= 10.3.7, JDBC driver >= {mariadbJDBC})
- . http://www.mysql.com/[MySQL^] (>= 5.7, JDBC driver >= {mysqlJDBC})
+ . http://www.postgresql.org/[PostgreSQL^] (>= {postgresql}, JDBC driver >= {postgresqlJDBC})
+ . https://mariadb.org/[MariaDB^] (>= {mariadb}, JDBC driver >= {mariadbJDBC})
+ . http://www.mysql.com/[MySQL^] (>= {mysql}, JDBC driver >= {mysqlJDBC})
. https://www.oracle.com/database/index.html[Oracle Database^] (>= 11g, JDBC driver >= ojdbc8 12.2.0.1)
. http://www.microsoft.com/en-us/server-cloud/products/sql-server/[MS SQL Server^] (>= 2017, JDBC driver >= {sqlserverJDBC}8)
diff --git a/src/main/asciidoc/reference-guide/architecture/architecture.adoc b/src/main/asciidoc/reference-guide/architecture/architecture.adoc
index ee226c9..64611a9 100644
--- a/src/main/asciidoc/reference-guide/architecture/architecture.adoc
+++ b/src/main/asciidoc/reference-guide/architecture/architecture.adoc
@@ -93,6 +93,53 @@ The End-user UI is the web-based application for self-registration, self-service
The communication between End-user UI and Core is exclusively REST-based.
+==== Password Reset
+
+When users lost their password, a feature is available to help gaining back access to Apache Syncope: password reset.
+
+The process can be outlined as follows:
+
+. user asks for password reset, typically via end-user
+. user is asked to provide an answer to the security question that was selected during self-registration or self-update
+. if the expected answer is provided, a unique token with time-constrained validity is internally generated and an
+e-mail is sent to the configured address for the user with a link - again, typically to the
+end-user - containing such token value
+. user clicks on the received link and provides new password value, typically via end-user
+. user receives confirmation via e-mail
+
+[WARNING]
+====
+The outlined procedure requires a working <<e-mail-configuration,e-mail configuration>>.
+
+In particular:
+
+* the first e-mail is generated from the `requestPasswordReset` <<notification-templates, notification template>>:
+hence, the token-based access link to the end-user is managed there;
+* the second e-mail is generated from the `confirmPasswordReset` <<notification-templates, notification template>>.
+====
+
+[TIP]
+====
+The process above requires the availability of <<console-configuration-security-questions,security questions>> that
+users can pick up and provide answers for.
+
+The usage of security questions can be however disabled by setting the `passwordReset.securityQuestion` value - see
+<<configuration-parameters, below>> for details.
+====
+
+[[password-reset-no-security-answer]]
+[WARNING]
+====
+Once provided via Enduser Application, the answers to security questions are *never* reported, neither via REST or Admin UI to
+administrators, nor to end-users via Enduser Application.
+
+This to avoid any information disclosure which can potentially lead attackers to reset other users' passwords.
+====
+
+[NOTE]
+In addition to the password reset feature, administrators can set a flag on a given user so that he / she is forced to
+update their password value at next login.
+
[[enduser-accessibility]]
==== Accessibility
diff --git a/src/main/asciidoc/reference-guide/architecture/core.adoc b/src/main/asciidoc/reference-guide/architecture/core.adoc
index c91ff53..f4aa66e 100644
--- a/src/main/asciidoc/reference-guide/architecture/core.adoc
+++ b/src/main/asciidoc/reference-guide/architecture/core.adoc
@@ -87,14 +87,15 @@ https://camunda.org/[Camunda^] or http://jbpm.jboss.org/[jBPM^], can be written
==== Persistence
All data (users, groups, attributes, resources, ...) is internally managed at a high level using a standard
-https://en.wikipedia.org/wiki/Java_Persistence_API[JPA 2.0^] approach based on http://openjpa.apache.org[Apache OpenJPA^].
+https://en.wikipedia.org/wiki/Java_Persistence_API[JPA 2.2^] approach based on http://openjpa.apache.org[Apache OpenJPA^].
The data is persisted into an underlying
database, referred to as *_Internal Storage_*. Consistency is ensured via the comprehensive
https://docs.spring.io/spring/docs/5.1.x/spring-framework-reference/data-access.html#transaction[transaction management^]
provided by the Spring Framework.
Globally, this offers the ability to easily scale up to a million entities and at the same time allows great portability
-with no code changes: MySQL, MariaDB, PostgreSQL, Oracle and MS SQL Server are fully supported deployment options.
+with no code changes: MySQL, MariaDB, PostgreSQL, Oracle and MS SQL Server are fully supported
+<<dbms,deployment options>>.
<<domains>> allow to manage data belonging to different https://en.wikipedia.org/wiki/Multitenancy[tenants^] into
separate database instances.
diff --git a/src/main/asciidoc/reference-guide/concepts/externalresources.adoc b/src/main/asciidoc/reference-guide/concepts/externalresources.adoc
index 0afc46a..f47d018 100644
--- a/src/main/asciidoc/reference-guide/concepts/externalresources.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/externalresources.adoc
@@ -148,7 +148,8 @@ endif::[]
* 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 a simple boolean value, such condition allows
complex statements to be expressed such 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?
+* remote key flag - should this item be considered as the key value on the Identity Store, if no
+<<pull-correlation-rules,pull>> or <<push-correlation-rules,push>> correlation rules are applicable?
* password flag (Users only) - should this item be treated as the password value?
* purpose - should this item be considered for <<propagation,propagation>> / <<provisioning-push,push>>,
<<provisioning-pull,pull>>, both or none?
@@ -156,7 +157,7 @@ complex statements to be expressed such as 'be mandatory only if this other attr
Besides the items documented above, some more data needs to be specified for a complete mapping:
* which
-http://connid.tirasa.net/apidocs/1.4/org/identityconnectors/framework/common/objects/ObjectClass.html[object class^]
+http://connid.tirasa.net/apidocs/1.5/org/identityconnectors/framework/common/objects/ObjectClass.html[object class^]
shall be used during communication with the Identity Store; predefined are `\\__ACCOUNT__` for Users and
`\\__GROUP__` for Groups
* whether matches between user / group / any object's attribute values and their counterparts on the Identity Store
diff --git a/src/main/asciidoc/reference-guide/concepts/implementations.adoc b/src/main/asciidoc/reference-guide/concepts/implementations.adoc
index b257a48..8070284 100644
--- a/src/main/asciidoc/reference-guide/concepts/implementations.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/implementations.adoc
@@ -18,8 +18,8 @@
//
=== Implementations
-Starting with Apache Syncope 2.1, it is possible to provide implementations suitable for <<customization,customization>>
-as:
+Starting with Apache Syncope 2.1, it is possible to provide implementations suitable for
+<<customization-core,customization>> as:
. Java classes
. http://www.groovy-lang.org/[Apache Groovy^] classes
diff --git a/src/main/asciidoc/reference-guide/concepts/provisioning/propagation.adoc b/src/main/asciidoc/reference-guide/concepts/provisioning/propagation.adoc
index 633f24c..4636a08 100644
--- a/src/main/asciidoc/reference-guide/concepts/provisioning/propagation.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/provisioning/propagation.adoc
@@ -64,7 +64,7 @@ the provided mapping; password has a special treatment:
* 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.
+http://connid.tirasa.net/apidocs/1.5/org/identityconnectors/common/security/GuardedString.html[GuardedString^] objects.
====
By default, the propagation process is controlled by the
diff --git a/src/main/asciidoc/reference-guide/concepts/tasks.adoc b/src/main/asciidoc/reference-guide/concepts/tasks.adoc
index f2a22bd..18c79a4 100644
--- a/src/main/asciidoc/reference-guide/concepts/tasks.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/tasks.adoc
@@ -31,16 +31,16 @@ update or delete a given User, Group or Any Object, to / from a certain Identity
* operation - `CREATE`, `UPDATE` or `DELETE`
* connObjectKey - value for ConnId
-http://connid.tirasa.net/apidocs/1.4/org/identityconnectors/framework/common/objects/Uid.html[unique identifier^]
+http://connid.tirasa.net/apidocs/1.5/org/identityconnectors/framework/common/objects/Uid.html[unique identifier^]
on the Identity Store
* oldConnObjectKey - the former unique identifier on the Identity Store: bears value only during updates involving the
unique identifier
* attributes - set of ConnId
-http://connid.tirasa.net/apidocs/1.4/org/identityconnectors/framework/common/objects/Attribute.html[attributes^] built
+http://connid.tirasa.net/apidocs/1.5/org/identityconnectors/framework/common/objects/Attribute.html[attributes^] built
upon internal identity data and configured mapping
* resource - related <<external-resources,external resource>>
* objectClass - ConnId
-http://connid.tirasa.net/apidocs/1.4/org/identityconnectors/framework/common/objects/ObjectClass.html[object class^]
+http://connid.tirasa.net/apidocs/1.5/org/identityconnectors/framework/common/objects/ObjectClass.html[object class^]
* entity - reference to the internal identity: User, Group or Any Object
[NOTE]
diff --git a/src/main/asciidoc/reference-guide/concepts/typemanagement.adoc b/src/main/asciidoc/reference-guide/concepts/typemanagement.adoc
index 7ee7e7d..0e77562 100644
--- a/src/main/asciidoc/reference-guide/concepts/typemanagement.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/typemanagement.adoc
@@ -22,6 +22,10 @@ In order to manage which attributes can be owned by Users, Groups and any object
Apache Syncope defines a simple yet powerful type management system, vaguely inspired by the LDAP/X.500 information
model.
+[NOTE]
+Starting with Apache Syncope 2.1, it is possible to define i18n labels for each schema, with purpose of improving
+presentation with Admin and End-user UIs.
+
==== Schema
A schema instance describes the values that attributes with that schema will hold; it can be defined plain, derived or
diff --git a/src/main/asciidoc/reference-guide/concepts/usersgroupsandanyobjects.adoc b/src/main/asciidoc/reference-guide/concepts/usersgroupsandanyobjects.adoc
index 09e9a3b..2294068 100644
--- a/src/main/asciidoc/reference-guide/concepts/usersgroupsandanyobjects.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/usersgroupsandanyobjects.adoc
@@ -76,50 +76,3 @@ _dynamic_ members of the group. +
Dynamic memberships have some limitations: for example, <<type-extensions,type extensions>> do not apply;
group-based provisioning is still effective.
====
-
-==== Password Reset
-
-When users lost their password, a feature is available to help gaining back access to Apache Syncope: password reset.
-
-The process can be outlined as follows:
-
-. user asks for password reset, typically via <<enduser-component,end-user>>
-. user is asked to provide an answer to the security question that was selected during self-registration or self-update
-. if the expected answer is provided, a unique token with time-constrained validity is internally generated and an
-e-mail is sent to the configured address for the user with a link - again, typically to the
-<<enduser-component,end-user>> - containing such token value
-. user clicks on the received link and provides new password value, typically via <<enduser-component,end-user>>
-. user receives confirmation via e-mail
-
-[WARNING]
-====
-The outlined procedure requires a working <<e-mail-configuration,e-mail configuration>>.
-
-In particular:
-
-* the first e-mail is generated from the `requestPasswordReset` <<notification-templates, notification template>>:
-hence, the token-based access link to the <<enduser-component,end-user>> is managed there;
-* the second e-mail is generated from the `confirmPasswordReset` <<notification-templates, notification template>>.
-====
-
-[TIP]
-====
-The process above requires the availability of <<console-configuration-security-questions,security questions>> that
-users can pick up and provide answers for.
-
-The usage of security questions can be however disabled by setting the `passwordReset.securityQuestion` value - see
-<<configuration-parameters, below>> for details.
-====
-
-[[password-reset-no-security-answer]]
-[WARNING]
-====
-Once provided via Enduser Application, the answers to security questions are *never* reported, neither via REST or Admin UI to
-administrators, nor to end-users via Enduser Application.
-
-This to avoid any information disclosure which can potentially lead attackers to reset other users' passwords.
-====
-
-[NOTE]
-In addition to the password reset feature, administrators can set a flag on a given user so that he / she is forced to
-update their password value at next login.
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc
index ae63c4b..1d4b69d 100644
--- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc
@@ -1086,5 +1086,5 @@ In case it is necessary to change those identifiers, remember to edit all refere
<<extensions>> can be part of a local project, to encapsulate special features which are specific to a given deployment.
For example, the http://www.chorevolution.eu/[CHOReVOLUTION^] IdM - based on Apache Syncope - provides
-https://gitlab.ow2.org/chorevolution/syncope/tree/2_1_X/ext/choreography[an extension^]
+https://gitlab.ow2.org/chorevolution/syncope/tree/master/ext/choreography[an extension^]
for managing via the <<core>> and visualizing via the <<admin-console-component>> the running choreography instances.
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/dbms.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/dbms.adoc
index 7013944..b0c71f6 100644
--- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/dbms.adoc
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/dbms.adoc
@@ -25,7 +25,7 @@ updated.
===== PostgreSQL
[NOTE]
-Apache Syncope {docVersion} is verified with PostgreSQL server >= 10.3 and JDBC driver >= {postgresqlJDBC}.
+Apache Syncope {docVersion} is verified with PostgreSQL server >= {postgresql} and JDBC driver >= {postgresqlJDBC}.
In `provisioning.properties`, replace as follows:
@@ -66,7 +66,7 @@ With the configurations reported below, Apache Syncope will leverage the
https://www.postgresql.org/docs/current/datatype-json.html[JSONB^] column type for attribute storage.
[NOTE]
-Apache Syncope {docVersion} is verified with PostgreSQL server >= 10.3 and JDBC driver >= {postgresqlJDBC}.
+Apache Syncope {docVersion} is verified with PostgreSQL server >= {postgresql} and JDBC driver >= {postgresqlJDBC}.
Add the following dependency to `core/pom.xml`:
@@ -153,7 +153,7 @@ and save it under `core/src/test/resources/domains/`.
===== MySQL
[NOTE]
-Apache Syncope {docVersion} is verified with MySQL server >= 8.0 and JDBC driver >= {mysqlJDBC}.
+Apache Syncope {docVersion} is verified with MySQL server >= {mysql} and JDBC driver >= {mysqlJDBC}.
In `provisioning.properties`, replace as follows:
@@ -197,7 +197,7 @@ With the configurations reported below, Apache Syncope will leverage the
https://dev.mysql.com/doc/refman/8.0/en/json-table-functions.html[JSON_TABLE^] function.
[NOTE]
-Apache Syncope {docVersion} is verified with MySQL server >= 8.0 and JDBC driver >= {mysqlJDBC}.
+Apache Syncope {docVersion} is verified with MySQL server >= {mysql} and JDBC driver >= {mysqlJDBC}.
Add the following dependency to `core/pom.xml`:
@@ -282,7 +282,7 @@ and save it under `core/src/test/resources/domains/`.
===== MariaDB
[NOTE]
-Apache Syncope {docVersion} is verified with MariaDB server >= 10.3.7 and JDBC driver >= {mariadbJDBC}.
+Apache Syncope {docVersion} is verified with MariaDB server >= {mariadb} and JDBC driver >= {mariadbJDBC}.
In `provisioning.properties`, replace as follows: