Repository: syncope Updated Branches: refs/heads/master 9c9443ab3 -> 550145f8e
[SYNCOPE-700] Architecture: done Project: http://git-wip-us.apache.org/repos/asf/syncope/repo Commit: http://git-wip-us.apache.org/repos/asf/syncope/commit/550145f8 Tree: http://git-wip-us.apache.org/repos/asf/syncope/tree/550145f8 Diff: http://git-wip-us.apache.org/repos/asf/syncope/diff/550145f8 Branch: refs/heads/master Commit: 550145f8ef979a69ecb2e6197fb4d3a727dcf388 Parents: 9c9443a Author: Francesco Chicchiriccò <[email protected]> Authored: Fri Jul 29 15:22:31 2016 +0200 Committer: Francesco Chicchiriccò <[email protected]> Committed: Fri Jul 29 15:22:31 2016 +0200 ---------------------------------------------------------------------- .../asciidoc/getting-started/introduction.adoc | 6 +- src/main/asciidoc/images/mapping.png | Bin 0 -> 136027 bytes src/main/asciidoc/images/userWorkflow.png | Bin 0 -> 28208 bytes .../architecture/3rdpartyapp.adoc | 21 ------ .../architecture/architecture.adoc | 39 ++++++++-- .../reference-guide/architecture/cli.adoc | 19 ----- .../reference-guide/architecture/console.adoc | 19 ----- .../reference-guide/architecture/core.adoc | 72 +++++++++++++++++++ .../reference-guide/architecture/enduser.adoc | 19 ----- .../reference-guide/concepts/concepts.adoc | 36 ++++++++++ .../reference-guide/extensions/extensions.adoc | 41 ++++++++++- .../restfulservices/restful-reference.adoc | 40 ----------- 12 files changed, 186 insertions(+), 126 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/syncope/blob/550145f8/src/main/asciidoc/getting-started/introduction.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/getting-started/introduction.adoc b/src/main/asciidoc/getting-started/introduction.adoc index 497d709..63a8f8f 100644 --- a/src/main/asciidoc/getting-started/introduction.adoc +++ b/src/main/asciidoc/getting-started/introduction.adoc @@ -89,7 +89,7 @@ drawbacks are just around the corner: . Lack of workflow management . Hidden infrastructure management cost, growing with organization -=== A bird's eye view on the Architecture of Apache Syncope +=== A bird's eye view on the Architecture [.text-center] image::architecture.png[title="Architecture",alt="Architecture"] @@ -114,7 +114,7 @@ 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. +implementation is also available as 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 the one based on http://www.activiti.org/[Activiti BPM^], the reference open source http://www.bpmn.org/[BPMN 2.0^] implementation - or define new, custom ones. @@ -129,7 +129,7 @@ changes: MySQL, MariaDB, PostgreSQL, Oracle and MS SQL Server are fully supporte implementation of delegated administration scenarios. Third-party applications are provided full access to IdM services by leveraging the REST interface, either via the -Java _SyncopeClient_ library (the basis of Admin UI, End-user UI and CLI) or plain HTTP calls. +Java Client Library (the basis of Admin UI, End-user UI and CLI) or plain HTTP calls. .ConnId **** http://git-wip-us.apache.org/repos/asf/syncope/blob/550145f8/src/main/asciidoc/images/mapping.png ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/images/mapping.png b/src/main/asciidoc/images/mapping.png new file mode 100644 index 0000000..bdc5936 Binary files /dev/null and b/src/main/asciidoc/images/mapping.png differ http://git-wip-us.apache.org/repos/asf/syncope/blob/550145f8/src/main/asciidoc/images/userWorkflow.png ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/images/userWorkflow.png b/src/main/asciidoc/images/userWorkflow.png new file mode 100644 index 0000000..04c6372 Binary files /dev/null and b/src/main/asciidoc/images/userWorkflow.png differ http://git-wip-us.apache.org/repos/asf/syncope/blob/550145f8/src/main/asciidoc/reference-guide/architecture/3rdpartyapp.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/architecture/3rdpartyapp.adoc b/src/main/asciidoc/reference-guide/architecture/3rdpartyapp.adoc deleted file mode 100644 index b0abdce..0000000 --- a/src/main/asciidoc/reference-guide/architecture/3rdpartyapp.adoc +++ /dev/null @@ -1,21 +0,0 @@ -// -// 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. -// -=== Third Party Applications - -==== Eclipse IDE Plugin http://git-wip-us.apache.org/repos/asf/syncope/blob/550145f8/src/main/asciidoc/reference-guide/architecture/architecture.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/architecture/architecture.adoc b/src/main/asciidoc/reference-guide/architecture/architecture.adoc index a3243a4..9fc1c6c 100644 --- a/src/main/asciidoc/reference-guide/architecture/architecture.adoc +++ b/src/main/asciidoc/reference-guide/architecture/architecture.adoc @@ -19,15 +19,46 @@ == 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[] -include::console.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. + +[[enduser-component]] +=== End-user UI + +The End-user UI is the web-based application for self-registration, self-service and password reset. + +The communication between End-user UI and Core is exclusively REST-based. + +[[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. + +=== Third Party Applications -include::enduser.adoc[] +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. -include::cli.adoc[] +==== Eclipse IDE Plugin -include::3rdpartyapp.adoc[] +The Eclipse IDE plugin allows remote management of notification e-mail and report templates and constitutes an example +of Java application relying on the Client Library for interacting with Core via REST. http://git-wip-us.apache.org/repos/asf/syncope/blob/550145f8/src/main/asciidoc/reference-guide/architecture/cli.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/architecture/cli.adoc b/src/main/asciidoc/reference-guide/architecture/cli.adoc deleted file mode 100644 index 86569ff..0000000 --- a/src/main/asciidoc/reference-guide/architecture/cli.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// -// 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. -// -=== CLI \ No newline at end of file http://git-wip-us.apache.org/repos/asf/syncope/blob/550145f8/src/main/asciidoc/reference-guide/architecture/console.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/architecture/console.adoc b/src/main/asciidoc/reference-guide/architecture/console.adoc deleted file mode 100644 index 0c165c3..0000000 --- a/src/main/asciidoc/reference-guide/architecture/console.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// -// 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. -// -=== Admin Console UI \ No newline at end of file http://git-wip-us.apache.org/repos/asf/syncope/blob/550145f8/src/main/asciidoc/reference-guide/architecture/core.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/architecture/core.adoc b/src/main/asciidoc/reference-guide/architecture/core.adoc index 22a1e46..4b65041 100644 --- a/src/main/asciidoc/reference-guide/architecture/core.adoc +++ b/src/main/asciidoc/reference-guide/architecture/core.adoc @@ -18,12 +18,84 @@ // === Core +All the services provided by Apache Syncope are defined, elaborated and served by the *_Core_*. + +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 extended by adding new ones, which might be needed on a given Apache +Syncope deployment to complement the native features with domain-specific operations. + +An <<swagger-ui,extension>> is available, providing full http://swagger.io/[Swagger^] features, +which enables in-browser access to all the REST endpoints defined. + +At technical level, the RESTful interface is a fully-compliant +https://en.wikipedia.org/wiki/Java_API_for_RESTful_Web_Services[JAX-RS 2.0^] implementation based on +http://cxf.apache.org[Apache CXF^], natively dealing both with JSON and XML payloads. + +More details are available in the dedicated <<restful-services,usage>> section. + ==== Logic +Right below the external interface level, the overall business logic, orchestrating the other layers for implementing +the operations that can be triggered via REST services, and controling some additional features (notifications, +reports and audit over all). + +[[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_ 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 http://camel.apache.org/[Apache Camel^]-based implementation is also available as +<<apache-camel-provisioning-engine,extension>>, which brings all the power of runtime changes and adaptation. + ==== Workflow +The Workflow layer is responsible for managing the internal lifecycle of users, groups and any objects. + +Besides the default engine, another based on http://www.activiti.org/[Activiti BPM^], the +reference open source http://www.bpmn.org/[BPMN 2.0^] implementation, is available for users, enabling advanced features +as approval management and new statuses definition. An optional web-based GUI editor is also available. + +[.text-center] +image::userWorkflow.png[title="Default Activiti user workflow",alt="Default Activiti user workflow"] + +Besides Activiti, 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 high level using a standard +https://en.wikipedia.org/wiki/Java_Persistence_API[JPA 2.0^] approach. The data is persisted into 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 + +Rather than being a separated 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. http://git-wip-us.apache.org/repos/asf/syncope/blob/550145f8/src/main/asciidoc/reference-guide/architecture/enduser.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/architecture/enduser.adoc b/src/main/asciidoc/reference-guide/architecture/enduser.adoc deleted file mode 100644 index 6dfa776..0000000 --- a/src/main/asciidoc/reference-guide/architecture/enduser.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// -// 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. -// -=== Enduser UI \ No newline at end of file http://git-wip-us.apache.org/repos/asf/syncope/blob/550145f8/src/main/asciidoc/reference-guide/concepts/concepts.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/concepts/concepts.adoc b/src/main/asciidoc/reference-guide/concepts/concepts.adoc index 2e63820..b906e0f 100644 --- a/src/main/asciidoc/reference-guide/concepts/concepts.adoc +++ b/src/main/asciidoc/reference-guide/concepts/concepts.adoc @@ -53,3 +53,39 @@ include::provisioning/provisioning.adoc[] === Audit === Delegated Administration + +The idea is that any user U assigned to a role R, which provides entitlements E~1~...E~n~ for realms Re~1~...Re~k~ can +exercise E~i~ on entities (users or groups, depending on the type of E~i~) under any Re~j~ or related sub-realms. + +About group membership and any relationships: + +* User U can be member of group G either if U and G are in the same realm, or G is in one of super-realms of the realm +of U +* Any object A~1~ can be in relationship with any object A~2~ either if A~1~ and A~2~ are in the same realm, or A~2~ is +in one of super-realms of the realm of A~1~ + +The rationale behind such conditions is to allow the definition of common groups and any objects (to enter in +relationship with) at the topmost position in the realm tree, so that they can be shared by various realm sub-trees. + +[discrete] +==== Example + +Let's suppose that we want to implement the following scenario: + +**** +Administrator A can create users under realm R~5~ but not under realm R~7~, administrator B can update users under +realm R~6~ and R~8~, administrator C can update groups under realm R~8~. +**** + +As default, Syncope will have defined the following entitlements, among others: + +* `USER_CREATE` +* `USER_UPDATE` +* `GROUP_UPDATE` + +Here it follows how entitlements should be assigned (via roles) to administrators in order to implement the scenario +above: + +* A: `USER_CREATE` on R~5~ +* B: `USER_UPDATE` on R~6~ and R~8~ +* C: `GROUP_UPDATE` on R~8~ http://git-wip-us.apache.org/repos/asf/syncope/blob/550145f8/src/main/asciidoc/reference-guide/extensions/extensions.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/extensions/extensions.adoc b/src/main/asciidoc/reference-guide/extensions/extensions.adoc index 7da12d7..40e2be3 100644 --- a/src/main/asciidoc/reference-guide/extensions/extensions.adoc +++ b/src/main/asciidoc/reference-guide/extensions/extensions.adoc @@ -18,4 +18,43 @@ // == Extensions -=== Apache Camel \ No newline at end of file +=== Apache Camel Provisioning Engine + +=== Swagger UI + +The Swagger installation is really simple because you just add the Maven dependency to your core pom.xml file generated +from the archetype operation; the dependency is: +[source, xml] +---- +<dependency> + <groupId>org.apache.syncope.ext</groupId> + <artifactId>syncope-ext-swagger-ui</artifactId> + <version>${syncope.version}</version> +</dependency> +---- + +The swagger interface is available going to the URL +[source] +-- +http://localhost:9080/syncope/swagger/#/ +-- + +Reading from the Swagger http://swagger.io/[website] + +.Swagger +**** +Swagger is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on +the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment +environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability. + +We created Swagger to help fulfill the promise of APIs. Swagger helps companies like Apigee, Getty Images, Intuit, +LivingSocial, McKesson, Microsoft, Morningstar, and PayPal build the best possible services with RESTful APIs. + +Now in version 2.0, Swagger is more enabling than ever. And it's 100% open source software. + +**** + +To be consistent with the example, below the image shows the Swagger UI used to read the configuration +of _org.apache.syncope.core.rest_ + +image::swaggerLoggerRead.png[swaggerLoggerRead] \ No newline at end of file http://git-wip-us.apache.org/repos/asf/syncope/blob/550145f8/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices/restful-reference.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices/restful-reference.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices/restful-reference.adoc index 3c9c145..c19ef19 100644 --- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices/restful-reference.adoc +++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices/restful-reference.adoc @@ -32,43 +32,3 @@ image::restReferenceLoggerRead.png[restReferenceLoggerRead] image::restReferenceLoggerUpdate.png[restReferenceLoggerUpdate] image::restSchemaReferenceLogger.png[restSchemaReferenceLogger] - -===== Swagger UI -From the 2.0 version, Syncope offers also the Swagger UI to work with its services. - -The Swagger installation is really simple because you just add the Maven dependency to your core pom.xml file generated -from the archetype operation; the dependency is: -[source, xml] ----- -<dependency> - <groupId>org.apache.syncope.ext</groupId> - <artifactId>syncope-ext-swagger-ui</artifactId> - <version>${syncope.version}</version> -</dependency> ----- - -The swagger interface is available going to the URL -[source] --- -http://localhost:9080/syncope/swagger/#/ --- - -Reading from the Swagger http://swagger.io/[website] - -.Swagger -**** -Swagger is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on -the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment -environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability. - -We created Swagger to help fulfill the promise of APIs. Swagger helps companies like Apigee, Getty Images, Intuit, -LivingSocial, McKesson, Microsoft, Morningstar, and PayPal build the best possible services with RESTful APIs. - -Now in version 2.0, Swagger is more enabling than ever. And it's 100% open source software. - -**** - -To be consistent with the example, below the image shows the Swagger UI used to read the configuration -of _org.apache.syncope.core.rest_ - -image::swaggerLoggerRead.png[swaggerLoggerRead] \ No newline at end of file
