Preface

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:

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.

Figure 1. 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
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.

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 JAX-RS 2.0RESTful 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 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 Activiti BPM and another based on
Flowable, the reference open source BPMN 2.0 implementations - or
define new, custom ones.

Persistence manages all data (users, groups, attributes, resources, …​) at a high level
using a standard JPA 2.0 approach. The data is persisted to an underlying
database, referred to as Internal Storage. Consistency is ensured via the comprehensive
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 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.

The standalone distribution is the simplest way to start exploring Apache Syncope: it contains a fully working, in-memory
Tomcat-based environment that can be easily grabbed and put at work on any modern laptop, workstation or server.

Target Audience

First approach, especially with administration console and end-user; does not require technical skills.Not meant for any production environment.

The set of provided components, including access URLs and credentials, is the same as reported for
embedded mode, with the exception of log files, available here under $CATALINA_HOME/logs.

Internal Storage

By default, the standalone distribution is configured to use an in-memory database instance.
This means that every time Tomcat is shut down all changes that have been made are lost.

If you want instead to make your changes persistent, replace

jdbc:h2:mem:syncopedb;DB_CLOSE_DELAY=-1

with

jdbc:h2:~/syncopedb;DB_CLOSE_DELAY=-1

in webapps/syncope/WEB-INF/classes/domains/Master.properties (for Master domain) or
webapps/syncope/WEB-INF/classes/domains/Two.properties (for Two domain) from the Apache Tomcat directory.
This will create H2 database files in the home directory of the user running Apache Syncope.

Maven archetypes are templates of projects. Maven can generate a new project from such a template.
In the folder in which the new project folder should be created, type the command shown below.
On Windows, run the command on a single line and leave out the line continuation characters ('\').

The archetype is configured with default values for all required properties; if you want to customize any of these
property values, type 'n' when prompted for confirmation.

You will be asked for:

groupId

something like 'com.mycompany'

artifactId

something like 'myproject'

version number

You can use the default; it is good practice to have 'SNAPSHOT' in the version number during development and the
maven release plugin makes use of that string. But ensure to comply with the desired numbering scheme for your project.

package name

The java package name. A folder structure according to this name will be generated automatically; by default, equal
to the groupId.

secretKey

Provide any pseudo-random string here that will be used in the generated project for AES ciphering.

anonymousKey

Provide any pseudo-random string here that will be used as an authentication key for anonymous requests.

Maven will create a project for you (in a newly created directory named after the value of the artifactId property
specified above) containing four modules: common, core, console and enduser.

You are now able to perform the first build via

mvn clean install

After downloading all of the needed dependencies, three WAR files will be produced:

core/target/syncope.war

console/target/syncope-console.war

enduser/target/syncope-enduser.war

If no failures are encountered, your basic Apache Syncope project is now ready to go.

The first time the plugin is run, it will prompt for connection details:

Once a connection to the given Apache Syncope deployment is established, a panel showing Mail and Report templates will
appear on the left; by double-clicking on each folder, the list of available templates is shown:

To refresh the list of available templates, or to update the connection details, right-click on the
Apache Syncope root node:

To create a new template, right-click on the Mail Templates or Report XSLTs folder and then click on New:

Before creating or editing a template, a modal window will be shown to select the edit format:

To edit a template, double-click on the template name and an editor will appear. On save, the template content will be
uploaded to the configured Apache Syncope deployment.

To delete an existing template, right-click on the template and then click on Delete:

Once you have obtained a working installation of Apache Syncope using one of the methods reported above, you should consider
reading the
Apache Syncope Reference Guide.
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:

adminPassword - The SHA1 hash evaluation of the cleartext password, 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.12 "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 (Syncope 2.0.3 onwards only). See section 4.4.1 "REST Authentication and
Authorization" of the Reference Guide for more information.

If you installed Syncope using either the GUI Installer or the Maven Project methods, then you will have already
supplied custom values for "secretKey" and "anonymousKey".

From Syncope 2.0.4 onwards, both installation methods will also query for "jwsKey", and the GUI Installer will
prompt for the "adminPassword" as well.