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

== Architecture

Apache Syncope is made of several components, which are logically summarized in the picture below.

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

include::core.adoc[]

[[admin-console-component]]
=== Admin UI

The Admin UI is the web-based console for configuring and administering running deployments, with full support
for delegated administration.

The communication between Admin UI and Core is exclusively REST-based.

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

[[admin-console-accessibility]]
==== Accessibility

The Admin Console UI is accessible to the visually impaired.

Two icons are present in the main login page and in the menu on the right:

[.text-center]
image::accessibility-console01.png[title="Admin Console accessibility buttons",alt="Admin Console accessibility buttons"]

By clicking the top right corner icon image:accessibility-icon01.png[Accessibility HC mode,30,30] it is possible to 
toggle the "High contrast mode".
In this mode, the website colors are switched to a higher contrast color schema.

[TIP]
====
The `H` https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/accesskey[accesskey^] shortcut can
be used to easily toggle "High contrast mode" by using the keyboard.

E.g. 
|===
|Shortcut |Purpose

|`Alt` + `Shift` + `H`
|Toggle "High contrast mode" on Firefox and Chrome browsers on Linux
|===

====

By clicking the second icon image:accessibility-icon02.png[Accessibility Increased Font mode,30,30] it is possible 
to toggle the "Increased font mode".
In this mode, the website font size is increased.

[TIP]
====
The `F` https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/accesskey[accesskey^] shortcut can
be used to easily toggle "Increased font mode" by using the keyboard.

E.g. 
|===
|Shortcut |Purpose

|`Alt` + `Shift` + `F`
|Toggle "Increased font mode" on Firefox and Chrome browsers on Linux
|===

====

To reset to the default mode, it is enough to click again on the specific icon.

[[enduser-component]]
=== End-user UI

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

The communication between End-user UI and Core is exclusively REST-based.

==== Password Reset

When users lost their password, a feature is available to help gaining back access to Apache Syncope: password reset.

The process can be outlined as follows:

. user asks for password reset, typically via end-user
. user is asked to provide an answer to the security question that was selected during self-registration or self-update
. if the expected answer is provided, a unique token with time-constrained validity is internally generated and an
e-mail is sent to the configured address for the user with a link - again, typically to the
end-user - containing such token value
. user clicks on the received link and provides new password value, typically via end-user
. user receives confirmation via e-mail

[WARNING]
====
The outlined procedure requires a working <<e-mail-configuration,e-mail configuration>>.

In particular:

* the first e-mail is generated from the `requestPasswordReset` <<notification-templates, notification template>>:
hence, the token-based access link to the end-user is managed there;
* the second e-mail is generated from the `confirmPasswordReset` <<notification-templates, notification template>>.
====

[TIP]
====
The process above requires the availability of <<console-configuration-security-questions,security questions>> that
users can pick up and provide answers for.

The usage of security questions can be however disabled by setting the `passwordReset.securityQuestion` value - see
<<configuration-parameters, below>> for details.
====

[[password-reset-no-security-answer]]
[WARNING]
====
Once provided via Enduser Application, the answers to security questions are *never* reported, neither via REST or Admin UI to
administrators, nor to end-users via Enduser Application.

This to avoid any information disclosure which can potentially lead attackers to reset other users' passwords.
====

[NOTE]
In addition to the password reset feature, administrators can set a flag on a given user so that he / she is forced to
update their password value at next login.

[[enduser-accessibility]]
==== Accessibility

The End-user UI is accessible to the visually impaired.

Two icons are present in the main page, in the right corner:

[.text-center]
image::accessibility-enduser01.png[title="Enduser accessibility icons",alt="Enduser accessibility icons"]

By clicking the top right corner icon image:accessibility-icon01.png[Accessibility HC mode,30,30] it is possible to 
toggle the "High contrast mode".
In this mode, the website colors are switched to a higher contrast color schema.

[TIP]
====
The `H` https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/accesskey[accesskey^] shortcut can
be used to easily toggle "High contrast mode" by using the keyboard.

E.g. 
|===
|Shortcut |Purpose

|`Alt` + `Shift` + `H`
|Toggle "High contrast mode" on Firefox and Chrome browsers on Linux
|===

====

By clicking the second icon image:accessibility-icon02.png[Accessibility Increased Font mode,30,30] it is possible 
to toggle the "Increased font mode".
In this mode, the website font size is increased.

[TIP]
====
The `F` https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/accesskey[accesskey^] shortcut can
be used to easily toggle "Increased font mode" by using the keyboard.

E.g. 
|===
|Shortcut |Purpose

|`Alt` + `Shift` + `F`
|Toggle "Increased font mode" on Firefox and Chrome browsers on Linux
|===

====

To reset to the default mode, it is enough to click again on the specific icon.

[[cli-component]]
=== CLI

The command-line interface (CLI) client is an utility tool meant for interacting with Apache Syncope deployments from 
shell scripts.

The communication between CLI and Core is exclusively REST-based.

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

[WARNING]
.Deprecation
====
Syncope 2.1 is the last major version providing CLI.

As an alternative you can consider using the popular http://curl.haxx.se/[curl^] tool to invoke the
Syncope Core REST API services. +
For reference, the Swagger UI extension, when enabled, will provide for each request the corresponding `curl` command
with all parameters.
====

=== Third Party Applications

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

==== Eclipse IDE Plugin

The Eclipse IDE plugin allows remote management of <<notification-templates,notification e-mail>> and
<<report-templates,report>> templates, and constitutes an example of a Java application relying on the Client Library
for interacting with the Core via REST.

==== Netbeans IDE Plugin

The Netbeans IDE plugin allows remote management of <<notification-templates,notification e-mail>> and
<<report-templates,report>> templates, and remote editing of Apache Groovy <<implementations,implementations>>. +
It constitutes an example of a Java application relying on the Client Library for interacting with the Core via REST.
