//
// 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 
Jakarta EE technology and released under the Apache 2.0 license. 

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.

The two topics are however completely different: each one has its own context, its own rules, its own best practices.

On the other hand, some products provide unorthodox implementations so it is indeed possible to do the same thing with 
both of them.

****
Identity Management:: Tools and practices to keep identity data consistent and synchronized across repositories, data 
formats and models.
Access Management:: 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.
(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
****
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_* (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_*: 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?

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"]

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

*_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/Jakarta_RESTful_Web_Services[Jakarta RESTful Web Services 3.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.

 * *_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.
 * *_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 https://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/Jakarta_Persistence[Jakarta Persistence 3.1] approach. The data is persisted to an underlying 
database, referred to as *_Internal Storage_*. Consistency is ensured via the comprehensive
https://docs.spring.io/spring-framework/reference/6.2/data-access/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: PostgreSQL, MySQL, MariaDB and Oracle 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 and End-user UI) 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. 
****
