//
// 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.
//
=== Core

The *_Core_* is the component providing IdM services and acting as central repository for other components' configuration.

The Core is internally further structured into several layers, each one taking care of specific aspects of the identity
management services.

==== REST

The primary way to consume Core services is the https://en.wikipedia.org/wiki/Representational_state_transfer[RESTful^]
interface, which enables full access to all the features provided.
This interface enables third-party applications, written in any programming language, to consume IdM services.

The rich pre-defined set of endpoints can be <<extensions,extended>> by adding new ones, which might be needed on a
given Apache Syncope deployment to complement the native features with domain-specific operations.

At a technical level, the RESTful interface is a fully-compliant 
https://en.wikipedia.org/wiki/Java_API_for_RESTful_Web_Services[JAX-RS 2.1^] implementation based on 
http://cxf.apache.org[Apache CXF^], natively dealing either with JSON, YAML and XML payloads.

More details are available in the dedicated <<core-usage,usage>> section.

==== Logic

Right below the external interface level, the overall business logic is responsible for orchestrating the other layers, 
by implementing the operations that can be triggered via REST services. It is also responsible for controlling some
additional features (notifications, reports and auditing).

[[provisioning-layer]]
==== Provisioning

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,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>>.

[.text-center]
image::mapping.png[title="Internal / External Mapping",alt="Internal / External Mapping"]

The default implementation can be sometimes 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.

In addition, an https://camel.apache.org/[Apache Camel^]-based implementation is also available as an 
<<apache-camel-provisioning-manager,extension>>, which brings all the power of runtime changes and adaptation.

[[workflow-layer]]
==== Workflow

The Workflow layer is responsible for managing the internal lifecycle of Users, Groups and Any Objects.

Besides the default engine, another engine is available based on https://www.flowable.org/[Flowable^], the 
reference open source http://www.bpmn.org/[BPMN 2.0^] implementation. It enables advanced features such
as approval management and new statuses definitions; a web-based GUI editor, the
https://www.flowable.org/docs/userguide/index.html#flowableModelerApp[Flowable Modeler^], is also available.

[.text-center]
image::userWorkflow.png[title="Default Flowable user workflow",alt="Default Flowable user workflow"] 

Besides Flowable, new workflow engines - possibly integrating with third-party tools as 
https://camunda.org/[Camunda^] or http://jbpm.jboss.org/[jBPM^], can be written and plugged into specific deployments.

==== 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.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-framework/docs/5.3.x/reference/html/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
<<dbms,deployment options>>.

<<domains>> allow to manage data belonging to different https://en.wikipedia.org/wiki/Multitenancy[tenants^] into
separate database instances.

==== Security

Rather than being a separate layer, Security features are triggered throughout incoming request processing.

A fine-grained set of entitlements is defined which can be granted to administrators, thus enabling the 
implementation of <<delegated-administration,delegated administration>> scenarios.