Getting Started Guide: reviewed for 3.0

CONTRIBUTING.md

@@ -19,4 +19,4 @@ under the License.
 **Apache Syncope** is an Open Source system for managing digital identities in enterprise environments, 
 implemented in Java EE technology and released under Apache 2.0 license.
 
-Would you like to contribute? Visit http://syncope.apache.org/contributing.html
+Would you like to contribute? Visit https://syncope.apache.org/contributing.html

README.md

@@ -19,7 +19,7 @@ under the License.
 **Apache Syncope** is an Open Source system for managing digital identities in enterprise environments, 
 implemented in Java EE technology and released under Apache 2.0 license.
 
-More information at http://syncope.apache.org
+More information at https://syncope.apache.org
 
 <a href="https://bestpractices.coreinfrastructure.org/projects/154">
   <img src="https://bestpractices.coreinfrastructure.org/projects/154/badge"/>

SECURITY.md

@@ -24,7 +24,7 @@ under the License.
 | ------- | ------------------ |
 | 3.0.x   | :white_check_mark: |
 | 2.1.x   | :white_check_mark: |
-| 2.0.x   | :white_check_mark: |
+| 2.0.x   | :x:                |
 | 1.2.x   | :x:                |
 | 1.1.x   | :x:                |
 

common/idrepo/rest-api/src/main/java/org/apache/syncope/common/rest/api/beans/AnyQuery.java

@@ -68,7 +68,7 @@ public Builder fiql(final String fiql) {
             + "primarily meant for containing Users, Groups and Any Objects", schema =
             @Schema(implementation = String.class, defaultValue = SyncopeConstants.ROOT_REALM, externalDocs =
                     @ExternalDocumentation(description = "Apache Syncope Reference Guide",
-                            url = "http://syncope.apache.org/docs/2.1/reference-guide.html#realms")))
+                            url = "https://syncope.apache.org/docs/3.0/reference-guide.html#realms")))
     public String getRealm() {
         return realm;
     }
@@ -102,7 +102,7 @@ public String getFiql() {
             + "feed.", example = "username==rossini", schema =
             @Schema(implementation = String.class, externalDocs =
                     @ExternalDocumentation(description = "Apache Syncope Reference Guide",
-                            url = "http://syncope.apache.org/docs/2.1/reference-guide.html#search")))
+                            url = "https://syncope.apache.org/docs/3.0/reference-guide.html#search")))
     @QueryParam(JAXRSService.PARAM_FIQL)
     public void setFiql(final String fiql) {
         this.fiql = fiql;

core/idrepo/logic/src/main/java/org/apache/syncope/core/logic/init/ClassPathScanImplementationLookup.java

@@ -95,7 +95,7 @@ public class ClassPathScanImplementationLookup implements ImplementationLookup {
 
     @Override
     public int getOrder() {
-        return Ordered.HIGHEST_PRECEDENCE;
+        return Ordered.HIGHEST_PRECEDENCE + 1;
     }
 
     /**

core/idrepo/rest-cxf/src/main/java/org/apache/syncope/core/rest/cxf/IdRepoRESTCXFContext.java

@@ -258,7 +258,7 @@ public OpenApiFeature openapiFeature() {
         openapiFeature.setDescription("Apache Syncope " + version());
         openapiFeature.setContactName("The Apache Syncope community");
         openapiFeature.setContactEmail("dev@syncope.apache.org");
-        openapiFeature.setContactUrl("http://syncope.apache.org");
+        openapiFeature.setContactUrl("https://syncope.apache.org");
         openapiFeature.setScan(false);
         openapiFeature.setResourcePackages(Set.of("org.apache.syncope.common.rest.api.service"));
 

core/idrepo/rest-cxf/src/main/java/org/apache/syncope/core/rest/cxf/SyncopeOpenApiCustomizer.java

@@ -125,7 +125,7 @@ protected void addParameters(final List<Parameter> parameters) {
 
             ExternalDocumentation extDoc = new ExternalDocumentation();
             extDoc.setDescription("Apache Syncope Reference Guide");
-            extDoc.setUrl("http://syncope.apache.org/docs/3.0/reference-guide.html#domains");
+            extDoc.setUrl("https://syncope.apache.org/docs/3.0/reference-guide.html#domains");
 
             Schema<String> schema = new Schema<>();
             schema.setDescription("Domains are built to facilitate multitenancy.");
@@ -146,7 +146,7 @@ protected void addParameters(final List<Parameter> parameters) {
 
             ExternalDocumentation extDoc = new ExternalDocumentation();
             extDoc.setDescription("Apache Syncope Reference Guide");
-            extDoc.setUrl("http://syncope.apache.org/docs/3.0/reference-guide.html#delegation");
+            extDoc.setUrl("https://syncope.apache.org/docs/3.0/reference-guide.html#delegation");
 
             Schema<String> schema = new Schema<>();
             schema.setDescription("Acton behalf of someone else");

core/starter/src/main/java/org/apache/syncope/core/starter/SyncopeCoreStart.java

@@ -26,15 +26,13 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.aop.support.AopUtils;
-import org.springframework.context.ApplicationListener;
 import org.springframework.context.event.ContextRefreshedEvent;
 import org.springframework.core.Ordered;
 
 /**
  * Take care of all initializations needed by Syncope Core to run up and safe.
  */
-public class SyncopeCoreStart extends KeymasterStart
-        implements ApplicationListener<ContextRefreshedEvent>, Ordered {
+public class SyncopeCoreStart extends KeymasterStart implements Ordered {
 
     private static final Logger LOG = LoggerFactory.getLogger(SyncopeCoreStart.class);
 
@@ -70,6 +68,6 @@ public void onApplicationEvent(final ContextRefreshedEvent event) {
                     LOG.debug("[{}] Initialization completed", loaderName);
                 });
 
-        serviceOps.register(getNetworkService());
+        super.onApplicationEvent(event);
     }
 }

docker/src/main/resources/docker-compose/docker-compose-ha.yml

@@ -16,7 +16,7 @@
 # under the License.
 
 # Full deployment (Core, Console, Enduser) on PostgreSQL, with high-availability set for Core
-# http://syncope.apache.org/docs/reference-guide.html#high-availability
+# https://syncope.apache.org/docs/reference-guide.html#high-availability
 
 version: '3.3'
 

pom.xml

@@ -36,7 +36,7 @@ under the License.
     <relativePath />
   </parent>
 
-  <url>http://syncope.apache.org/</url>
+  <url>https://syncope.apache.org/</url>
 
   <inceptionYear>2010</inceptionYear>
 
@@ -81,8 +81,7 @@ under the License.
       <post>user@syncope.apache.org</post>
       <archive>https://lists.apache.org/list.html?user@syncope.apache.org</archive>
       <otherArchives>
-        <otherArchive>http://syncope.markmail.org/</otherArchive>
-        <otherArchive>http://syncope-user.1051894.n5.nabble.com/</otherArchive>
+        <otherArchive>https://syncope.markmail.org/</otherArchive>
         <otherArchive>http://www.mail-archive.com/user@syncope.apache.org/</otherArchive>
       </otherArchives>
     </mailingList>
@@ -93,8 +92,7 @@ under the License.
       <post>dev@syncope.apache.org</post>
       <archive>https://lists.apache.org/list.html?dev@syncope.apache.org</archive>
       <otherArchives>
-        <otherArchive>http://syncope.markmail.org/</otherArchive>
-        <otherArchive>http://syncope-dev.1063484.n5.nabble.com/</otherArchive>
+        <otherArchive>https://syncope.markmail.org/</otherArchive>
         <otherArchive>http://www.mail-archive.com/dev@syncope.apache.org/</otherArchive>
       </otherArchives>
     </mailingList>
@@ -105,7 +103,7 @@ under the License.
       <post>commits@syncope.apache.org</post>
       <archive>https://lists.apache.org/list.html?commits@syncope.apache.org</archive>
       <otherArchives>
-        <otherArchive>http://syncope.markmail.org/</otherArchive>
+        <otherArchive>https://syncope.markmail.org/</otherArchive>
         <otherArchive>http://www.mail-archive.com/commits@syncope.apache.org/</otherArchive>
       </otherArchives>
     </mailingList>
@@ -2550,12 +2548,12 @@ under the License.
             <link>http://www.slf4j.org/api/</link>
             <link>http://connid.tirasa.net/apidocs/1.5/</link>
             <link>http://cxf.apache.org/javadoc/latest/</link>
-            <link>http://fasterxml.github.io/jackson-core/javadoc/2.12/</link>
-            <link>http://fasterxml.github.io/jackson-databind/javadoc/2.12/</link>
-            <link>http://fasterxml.github.io/jackson-annotations/javadoc/2.12/</link>
-            <link>http://fasterxml.github.io/jackson-dataformat-xml/javadoc/2.12/</link>
-            <link>http://fasterxml.github.io/jackson-dataformats-text/javadoc/yaml/2.12/</link>
-            <link>http://fasterxml.github.io/jackson-dataformats-text/javadoc/csv/2.12/</link>
+            <link>http://fasterxml.github.io/jackson-core/javadoc/2.13/</link>
+            <link>http://fasterxml.github.io/jackson-databind/javadoc/2.13/</link>
+            <link>http://fasterxml.github.io/jackson-annotations/javadoc/2.13/</link>
+            <link>http://fasterxml.github.io/jackson-dataformat-xml/javadoc/2.13/</link>
+            <link>http://fasterxml.github.io/jackson-dataformats-text/javadoc/yaml/2.13/</link>
+            <link>http://fasterxml.github.io/jackson-dataformats-text/javadoc/csv/2.13/</link>
             <link>https://www.javadoc.io/doc/org.apache.camel/camel-core/latest/</link>
             <link>https://www.javadoc.io/doc/org.apache.camel/camel-spring/latest/</link>
             <link>https://ci.apache.org/projects/wicket/apidocs/9.x/</link>

src/main/asciidoc/getting-started/getting-started.adoc

@@ -21,7 +21,7 @@
 // User manual: http://asciidoctor.org/docs/user-manual/
 // Tricks: https://leanpub.com/awesomeasciidoctornotebook/read
 
-:homepage: http://syncope.apache.org
+:homepage: https://syncope.apache.org
 :description: Several ways to get started with Apache Syncope
 :keywords: Apache Syncope, IdM, provisioning, identity management, getting started, tutorial
 
@@ -41,16 +41,19 @@ image::http://syncope.apache.org/images/apache-syncope-logo-small.jpg[Apache Syn
 [NOTE]
 .This document is under active development and discussion!
 If you find errors or omissions in this document, please don’t hesitate to 
-http://syncope.apache.org/issue-management.html[submit an issue] or
+https://syncope.apache.org/issue-management.html[submit an issue] or
 https://github.com/apache/syncope/pulls[open a pull request] with 
 a fix. We also encourage you to ask questions and discuss any aspects of the project on the 
-http://syncope.apache.org/mailing-lists.html[mailing lists or IRC]. 
+https://syncope.apache.org/mailing-lists.html[mailing lists or IRC]. 
 New contributors are always welcome!
 
 [discrete] 
 == Preface
-This guide shows you how to get started with Apache Syncope services for identity management, provisioning, and 
-compliance.
+This guide shows you how to get started with Apache Syncope services for:
+
+* identity management, provisioning and compliance; 
+* access management, single sign-on, authentication and authorization;
+* API gateway, secure proxy, service mesh, request routing.
 
 include::introduction.adoc[]
 

src/main/asciidoc/getting-started/introduction.adoc

@@ -22,18 +22,26 @@
 *Apache Syncope* is an Open Source system for managing digital identities in enterprise environments, implemented in 
 Java EE technology and released under the Apache 2.0 license. 
 
-*Identity Management* (or IdM) means to manage user data on systems and applications, using the combination of
-business processes and IT. IdM involves considering user attributes, roles, resources and entitlements in trying to answer the
-following thorny question:
+Often, Identity Management and Access Management are jointly referred, mainly because their two management worlds likely
+coexist in the same project or in the same environment.
 
-[.text-center]
-_Who has access to What, When, How, and Why?_ 
+The two topics are however completely different: each one has its own context, its own rules, its own best practices.
+
+*Identity Management* (or IdM) consists of tools and practices to keep identity data consistent and synchronized across
+repositories, data formats and models.
+
+*Access Management* (or AM) is about systems, protocols and technologies supporting user _authentication_
+(how users are let accessing a given system) and __authorization__ (which capabilities each user owns on a given system).
+
+From the definitions above, Identity Management and Access Management can be seen as complementary: very often, the
+data synchronized by the former are then used by the latter to provide its features - e.g. authentication and
+authorization.
 
 === What is Identity Management, anyway?
 
 ****
-Account:: Computers work with records of data about people. Such records contain technical information needed by the system for 
-which the account is created and managed.
+Account:: Computers work with records of data about people. Such records contain technical information needed by the
+system for  which the account is created and managed.
 (Digital) Identity:: A representation of a set of claims made by one digital subject about itself. *It's you!*
 ****
 
@@ -52,30 +60,42 @@ image::identityLifecycle.png[title="Identity Lifecycle",alt="Identity Lifecycle"
 
 .Users, Groups and Any Objects
 ****
-With Apache Syncope 2.0.0, the managed identities are not limited anymore to Users and Groups. New object types can be
+Since Apache Syncope 2.0.0, the managed identities are not limited anymore to Users and Groups. New object types can be
 defined so that Any Object's data can be managed through Syncope: workstations, printers, folders, sensors, services,
 and so on. This positions Apache Syncope at the forefront for bringing Identity Management to the IoT world.
 ****
 
+=== What is Access Management, anyway?
+
+Authenticate, authorize and audit access to applications and IT systems: access management solutions help strengthen
+security and reduce risk by tightly controlling access to on-premises and cloud-based applications, services, and IT
+infrastructure. +
+Access Management help ensure the right users have access to the right resources at the right times for the right
+reasons.
+
+Single sign-on (SSO) is an authentication scheme that allows a user to access multiple, independent applications with a
+single set of login credentials, without re-entering authentication factors. +
+Very often, SSO is achieved by implementing some of the most popular protocols as
+https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language[SAML^] and http://openid.net/connect/[OpenID Connect^].
+
+Social login, designed to simplify logins, is a form of single sign-on using existing information from a social
+networking service to sign into a third party website instead of creating a new login account specifically for that
+website.
+
 === Identity and Access Management - Reference Scenario
 
 [.text-center]
 image::iam-scenario.png[title="IAM Scenario",alt="IAM Scenario"]
 
 The picture above shows the technologies involved in a complete IAM solution:
 
-* *_Identity Store_* (as RDBMS, LDAP, Active Directory, meta- and virtual-directories) - the repository for account data
-* *_Provisioning Engine_* - synchronizes account data across Identity Stores and a broad range of data formats, models, 
+* *_Identity Store_* (examples are relational databases, LDAP, Active Directory, meta- and virtual-directories, 
+cloud resources, ...): the repository for account data
+* *_Identity Manager_*: synchronizes account data across Identity Stores and a broad range of data formats, models, 
 meanings and purposes
-* *_Access Manager_* - access mediator to all applications, focused on application front-end, taking care of
-authentication (https://en.wikipedia.org/wiki/Single_sign-on[Single Sign-On^]), authorization
-(http://oauth.net/[OAuth^], https://en.wikipedia.org/wiki/XACML[XACML^]) and federation
-(https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language[SAML^], http://openid.net/connect/[OpenID Connect^]).
-
-[NOTE]
-====
-From a technology point of view, *Apache Syncope* is primarily a *Provisioning Engine*.
-====
+* *_Access Manager_*: security mediator to all applications, focused on application front-end, taking care of
+authentication, authorization and federation
+* *_Secure Proxy_*: enforces security policies on API and legacy applications
 
 ==== Aren't Identity Stores enough?
 
@@ -94,13 +114,19 @@ are a few drawbacks with this approach:
 [.text-center]
 image::architecture.png[title="Architecture",alt="Architecture"]
 
+*_Keymaster_* allows for dynamic service discovery so that other components are able to find each other.
+
 *_Admin UI_* is the web-based console for configuring and administering running deployments, with full support
 for delegated administration.
 
 *_End-user UI_* is the web-based application for self-registration, self-service and password reset.
 
-*_Core_* is the central component, providing all services offered by Apache Syncope. +
-It exposes a fully-compliant https://en.wikipedia.org/wiki/Java_API_for_RESTful_Web_Services[JAX-RS 2.0^] 
+*_Web Access_* or *_WA_* is the central hub for authentication, authorization and single sign-on.
+
+*_Secure Remote Access_* or *_SRA_* is a security-enabled API gateway with HTTP reverse proxying capabilities.
+
+*_Core_* is the component providing IdM services and acting as central repository for other components' configuration. +
+It exposes a fully-compliant https://en.wikipedia.org/wiki/Java_API_for_RESTful_Web_Services[JAX-RS 2.1^] 
 https://en.wikipedia.org/wiki/Representational_state_transfer[RESTful^] interface which enables third-party applications,
 written in any programming language, to consume IdM services.
 

src/main/asciidoc/getting-started/movingForward.adoc

@@ -22,23 +22,24 @@
 Once you have obtained a working installation of Apache Syncope using one of the methods reported above, you should consider 
 reading the
 ifeval::["{backend}" == "html5"]
-http://syncope.apache.org/docs/reference-guide.html[Apache Syncope Reference Guide.]
+https://syncope.apache.org/docs/reference-guide.html[Apache Syncope Reference Guide.]
 endif::[]
 ifeval::["{backend}" == "pdf"]
-http://syncope.apache.org/docs/reference-guide.pdf[Apache Syncope Reference Guide.]
+https://syncope.apache.org/docs/reference-guide.pdf[Apache Syncope Reference Guide.]
 endif::[]
 to understand how to configure, extend, customize and deploy your new Apache Syncope project.
 
 Before deploying your Apache Syncope installation into production, it is essential to ensure that the default values for 
 various security properties have been changed to values specific to your deployment. 
 
-The following values must be changed from the defaults in the `security.properties` file:
+The following values must be changed from the defaults in the `core.properties` file:
 
-* *adminPassword* - The cleartext password as encoded per the "adminPasswordAlgorithm" value (SSHA256 by default), the default value of which is "password".
+* *adminPassword* - The cleartext password as encoded per the `adminPasswordAlgorithm` value (SSHA256 by default), the
+default value of which is "password".
 * *secretKey* - The secret key value used for AES ciphering. Only required if either:
 ** the value for "*adminPasswordAlgorithm*" is "AES" or
-** the configuration parameter "password.cipher.algorithm" is changed to "AES" (See section 4.6.14 "Configuration Parameters" of
-the Reference Guide for more information).
+** the configuration parameter "password.cipher.algorithm" is changed to "AES" (See section 4.6.14 "Configuration
+Parameters" of the Reference Guide for more information).
 * *anonymousKey* - The key value to use for anonymous requests.
 * *jwsKey* - The symmetric signing key used to sign access tokens. See section 4.4.1 "REST Authentication and 
 Authorization" of the Reference Guide for more information.