<?xml version="1.0" encoding="UTF-8"?>
<!--
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.

-->
<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">

  <properties>
    <title>Architecture</title>
    <author email="dev@syncope.apache.org">Apache Syncope Documentation Team</author>
  </properties>

  <body>
    <section name="Architecture">      
      
      <p style="text-align:center;">
        <img src="docs/images/architecture.png" alt="Syncope architecture" width="600"/>
      </p>
      
      <p>
        <strong>
          <em>Keymaster</em>
        </strong> allows for dynamic service discovery so that other components are able to find each other.
      </p>

      <p>
        <strong>
          <em>Admin UI</em>
        </strong> is the web-based console for configuring and administering running deployments, with full support
        for delegated administration.
      </p>

      <p>
        <strong>
          <em>End-user UI</em>
        </strong> is the web-based application for self-registration, self-service and password reset.
      </p>

      <p>
        <strong>
          <em>Web Access</em>
        </strong> is the Access Management component, based on
        <a target="_blank" href="https://apereo.github.io/cas/">Apereo CAS</a>.
      </p>

      <p>
        <strong>
          <em>Secure Remote Access</em>
        </strong> allows to protect legacy applications by integrating with the Web Access or other third-party
        Access Managers implementing standard protocols as OpenID Connect or SAML.
      </p>

      <p>
        <strong>
          <em>Core</em>
        </strong> is the central component, providing all services offered by Apache Syncope.<br/>
        It exposes a fully-compliant 
        <a target="_blank" href="https://en.wikipedia.org/wiki/Java_API_for_RESTful_Web_Services">JAX-RS 2.1</a>
        <a target="_blank" href="https://en.wikipedia.org/wiki/Representational_state_transfer">RESTful</a> 
        interface which enables third-party applications, written in any programming language, to consume IdM 
        services.
      </p>

      <ul>
        <li>
          <p>
            <strong>
              <em>Logic</em>
            </strong> implements the overall business logic that can be triggered via REST services, and controls some 
            additional features (notifications, reports and audit over all)
          </p>
        </li>
        <li>
          <p>
            <strong>
              <em>Provisioning</em>
            </strong> is involved with managing the internal (via workflow) and external (via specific connectors)
            representation of users, groups and any objects.<br/>
            This component often needs to be tailored to meet the requirements of a specific deployment, as it is the 
            crucial decision point for defining and enforcing the consistency and transformations between internal and 
            external data. The default all-Java implementation can be extended for this purpose.
          </p>
        </li>
        <li>
          <p>
            <strong>
              <em>Workflow</em>
            </strong> is one of the pluggable aspects of Apache Syncope: this lets every deployment choose the preferred 
            engine from a provided list - including the one based on 
            <a target="_blank" href="https://www.flowable.org/">Flowable BPM</a>, the reference open source
            <a target="_blank" href="https://www.bpmn.org/">BPMN 2.0</a> implementation - or define new, custom ones.
          </p>
        </li>
        <li>
          <p>
            <strong>
              <em>Persistence</em>
            </strong> manages all data (users, groups, attributes, resources, …&#8203;) at a high level
            using a standard <a target="_blank" href="https://en.wikipedia.org/wiki/Java_Persistence_API">JPA 2.2</a> 
            approach. The data is persisted to an underlying database, referred to as <strong>
              <em>Internal Storage</em>
            </strong>. Consistency is ensured via the comprehensive
            <a target="_blank" href="https://docs.spring.io/spring-framework/docs/5.3.x/reference/html/data-access.html#transaction">transaction management</a>
            provided by the Spring Framework.<br/>
            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.<br/>
            Domains allow to manage data belonging to different tenants into separate database instances.
          </p>
        </li>
        <li>
          <p>
            <strong>
              <em>Security</em>
            </strong> defines a fine-grained set of entitlements which can be granted to administrators, thus enabling 
            the implementation of delegated administration scenarios
          </p>
        </li>
      </ul>
      
      <p>
        Third-party applications are provided full access to IdM services by leveraging the REST interface, either 
        via the Java <em>SyncopeClient</em> library (the basis of Admin UI and End-user UI) or plain HTTP calls.
      </p>
      
      <subsection name="ConnId">
        <p>The <strong>
            <em>Provisioning</em>
          </strong> layer relies on <a href="http://connid.tirasa.net" target="_blank">ConnId</a>; ConnId is designed 
          to separate the implementation of an application from the dependencies of the system that the application is 
          attempting to connect to.
        </p>

        <p>ConnId is the continuation of The Identity Connectors Framework (Sun ICF), a project that used to be part of
          market leader Sun IdM and has since been released by Sun Microsystems as an Open Source project.
          This makes the connectors layer particularly reliable because most connectors have already been implemented 
          in the framework and widely tested.</p>

        <p>The new ConnId project, featuring contributors from several companies, provides all that is required 
          nowadays for a modern Open Source project, including an Apache Maven driven build, artifacts and mailing 
          lists. Additional connectors – such as for SOAP, CSV, PowerShell and Active Directory – are also provided.</p>
      </subsection>
    </section>
  </body>
</document>
