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

== Introduction

*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:

[.text-center]
_Who has access to What, When, How, and Why?_ 

=== 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.
(Digital) Identity:: A representation of a set of claims made by one digital subject about itself. *It's you!*
****

Have you ever been hired by a company, entered an organization or just created a new Google account?
Companies, organizations and cloud entities work with applications that need your data to function properly: 
username, password, e-mail, first name, surname, and more.

Where is this information going to come from? And what happens when you need to be enabled for more applications? And what if
you get promoted and acquire more rights on the applications you already had access to?
Most important, what happens when you quit or they gently let you go?

In brief, Identity Management takes care of managing identity data throughout what is called the *Identity Lifecycle*.

[.text-center]
image::identityLifecycle.png[title="Identity Lifecycle",alt="Identity Lifecycle",width="505",height="324"]

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

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

==== Aren't Identity Stores enough?

One might suppose that a single Identity Store can solve all the identity needs inside an organization, but there
are a few drawbacks with this approach:

. Heterogeneity of systems
. Lack of a single source of information (HR for corporate id, Groupware for mail address, ...)
. Often applications require a local user database
. Inconsistent policies across the infrastructure
. Lack of workflow management
. Hidden infrastructure management cost, growing with the size of the organization

=== A bird's eye view on the Architecture

[.text-center]
image::architecture.png[title="Architecture",alt="Architecture"]

*_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.

*_CLI_* is the command-line application for interacting with Apache Syncope from scripts, particularly useful for 
system administrators.

*_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^] 
https://en.wikipedia.org/wiki/Representational_state_transfer[RESTful^] interface which enables third-party applications,
written in any programming language, to consume IdM services.

 * *_Logic_* implements the overall business logic that can be triggered via REST services, and controls some additional
features (notifications, reports and auditing)
 * *_Provisioning_* is involved with managing the internal (via workflow) and external (via specific connectors) 
representation of Users, Groups and Any Objects. +
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. In addition, an http://camel.apache.org/[Apache Camel^]-based 
implementation is also available as an extension, which brings all the power of runtime changes and adaptation.
 * *_Workflow_*  is one of the pluggable aspects of Apache Syncope: this lets every deployment choose the preferred engine
from a provided list - including one based on http://www.activiti.org/[Activiti BPM^] and another 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 
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. +
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.
 * *_Security_* defines a fine-grained set of entitlements which can be granted to administrators, thus enabling the 
implementation of delegated administration scenarios.

Third-party applications are provided full access to IdM services by leveraging the REST interface, either via the 
Java Client Library (the basis of Admin UI, End-user UI and CLI) or plain HTTP calls.

.ConnId
****
The *_Provisioning_* layer relies on http://connid.tirasa.net[ConnId^]; ConnId is designed to separate the 
implementation of an application from the dependencies of the system that the application is attempting to connect to.

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.

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