[SYNCOPE-700] Finalizing getting started, moving on reference guide
Project: http://git-wip-us.apache.org/repos/asf/syncope/repo Commit: http://git-wip-us.apache.org/repos/asf/syncope/commit/c95b6ff5 Tree: http://git-wip-us.apache.org/repos/asf/syncope/tree/c95b6ff5 Diff: http://git-wip-us.apache.org/repos/asf/syncope/diff/c95b6ff5 Branch: refs/heads/2_0_NO_JAXB Commit: c95b6ff57a15f984640689601466d9b99c06556e Parents: e74a10a Author: Francesco Chicchiriccò <[email protected]> Authored: Tue Jul 5 17:33:37 2016 +0200 Committer: Francesco Chicchiriccò <[email protected]> Committed: Tue Jul 5 17:33:37 2016 +0200 ---------------------------------------------------------------------- pom.xml | 9 +- .../asciidoc/architecture/architecture.adoc | 24 - .../asciidoc/architecture/designprinciples.adoc | 19 - .../architecture/implementationguidelines.adoc | 19 - src/main/asciidoc/commondocs/debpackages.adoc | 105 ---- src/main/asciidoc/commondocs/guiinstaller.adoc | 129 ----- src/main/asciidoc/commondocs/maven.adoc | 124 ----- src/main/asciidoc/concepts/concepts.adoc | 55 --- .../concepts/provisioning/connectors.adoc | 32 -- .../concepts/provisioning/propagation.adoc | 34 -- .../concepts/provisioning/provisioning.adoc | 37 -- .../asciidoc/concepts/provisioning/pull.adoc | 52 -- .../asciidoc/concepts/provisioning/push.adoc | 51 -- .../concepts/provisioning/resources.adoc | 51 -- src/main/asciidoc/extensions/extensions.adoc | 21 - src/main/asciidoc/getting-started.adoc | 59 --- .../getting-started/getting-started.adoc | 61 +++ .../asciidoc/getting-started/introduction.adoc | 146 ++++++ .../asciidoc/getting-started/movingForward.adoc | 30 ++ src/main/asciidoc/getting-started/obtain.adoc | 489 +++++++++++++++++++ .../getting-started/systemRequirements.adoc | 52 ++ .../iam/accessmanager/accessmanager.adoc | 25 - .../iam/accessmanager/authentication.adoc | 69 --- src/main/asciidoc/iam/iam.adoc | 36 -- src/main/asciidoc/iam/identitystores.adoc | 35 -- src/main/asciidoc/iam/provisioningengines.adoc | 32 -- src/main/asciidoc/iam/thecompletepicture.adoc | 19 - src/main/asciidoc/introduction.adoc | 146 ------ .../asciidoc/introduction/digitalidentity.adoc | 43 -- src/main/asciidoc/introduction/history.adoc | 31 -- .../asciidoc/introduction/introduction.adoc | 26 - src/main/asciidoc/obtain.adoc | 192 -------- src/main/asciidoc/reference-guide.adoc | 73 --- .../architecture/architecture.adoc | 24 + .../architecture/designprinciples.adoc | 19 + .../architecture/implementationguidelines.adoc | 19 + .../reference-guide/concepts/concepts.adoc | 55 +++ .../concepts/provisioning/connectors.adoc | 32 ++ .../concepts/provisioning/propagation.adoc | 34 ++ .../concepts/provisioning/provisioning.adoc | 37 ++ .../concepts/provisioning/pull.adoc | 52 ++ .../concepts/provisioning/push.adoc | 51 ++ .../concepts/provisioning/resources.adoc | 51 ++ .../reference-guide/extensions/extensions.adoc | 21 + .../reference-guide/iam/accessmanagers.adoc | 23 + src/main/asciidoc/reference-guide/iam/iam.adoc | 36 ++ .../reference-guide/iam/identitystores.adoc | 35 ++ .../iam/provisioningengines.adoc | 32 ++ .../reference-guide/iam/thecompletepicture.adoc | 22 + .../reference-guide/reference-guide.adoc | 77 +++ .../reference-guide/usecases/usecases.adoc | 19 + .../adminconsole/adminconsole.adoc | 46 ++ .../adminconsole/configuration.adoc | 60 +++ .../adminconsole/dashboard.adoc | 56 +++ .../adminconsole/extensions.adoc | 26 + .../adminconsole/realms.adoc | 63 +++ .../adminconsole/reports.adoc | 32 ++ .../adminconsole/topology.adoc | 26 + .../workingwithapachesyncope/cli/cli.adoc | 64 +++ .../cli/configuration.adoc | 54 ++ .../workingwithapachesyncope/cli/connector.adoc | 55 +++ .../workingwithapachesyncope/cli/domain.adoc | 46 ++ .../cli/entitlement.adoc | 53 ++ .../workingwithapachesyncope/cli/group.adoc | 56 +++ .../workingwithapachesyncope/cli/info.adoc | 53 ++ .../cli/installation.adoc | 181 +++++++ .../workingwithapachesyncope/cli/logger.adoc | 61 +++ .../cli/notification.adoc | 45 ++ .../workingwithapachesyncope/cli/policy.adoc | 50 ++ .../workingwithapachesyncope/cli/question.adoc | 45 ++ .../workingwithapachesyncope/cli/realm.adoc | 40 ++ .../workingwithapachesyncope/cli/report.adoc | 68 +++ .../workingwithapachesyncope/cli/resource.adoc | 48 ++ .../workingwithapachesyncope/cli/role.adoc | 48 ++ .../workingwithapachesyncope/cli/schema.adoc | 58 +++ .../workingwithapachesyncope/cli/task.adoc | 69 +++ .../workingwithapachesyncope/cli/user.adoc | 81 +++ .../restfulservices/client-library.adoc | 60 +++ .../restfulservices/restful-reference.adoc | 74 +++ .../restfulservices/restful-services.adoc | 30 ++ .../workingwithapachesyncope.adoc | 51 ++ src/main/asciidoc/systemRequirements.adoc | 52 -- src/main/asciidoc/usecases/usecases.adoc | 19 - .../adminconsole/adminconsole.adoc | 32 -- .../adminconsole/configuration.adoc | 60 --- .../adminconsole/dashboard.adoc | 56 --- .../adminconsole/extensions.adoc | 26 - .../adminconsole/introduction.adoc | 33 -- .../adminconsole/realms.adoc | 63 --- .../adminconsole/reports.adoc | 32 -- .../adminconsole/topology.adoc | 26 - .../workingwithapachesyncope/cli/cli.adoc | 56 --- .../cli/configuration.adoc | 52 -- .../workingwithapachesyncope/cli/connector.adoc | 53 -- .../workingwithapachesyncope/cli/domain.adoc | 44 -- .../cli/entitlement.adoc | 51 -- .../workingwithapachesyncope/cli/group.adoc | 54 -- .../workingwithapachesyncope/cli/info.adoc | 52 -- .../cli/installation.adoc | 181 ------- .../cli/introduction.adoc | 33 -- .../workingwithapachesyncope/cli/logger.adoc | 59 --- .../cli/notification.adoc | 43 -- .../workingwithapachesyncope/cli/policy.adoc | 48 -- .../workingwithapachesyncope/cli/question.adoc | 43 -- .../workingwithapachesyncope/cli/realm.adoc | 38 -- .../workingwithapachesyncope/cli/report.adoc | 66 --- .../workingwithapachesyncope/cli/resource.adoc | 46 -- .../workingwithapachesyncope/cli/role.adoc | 46 -- .../workingwithapachesyncope/cli/schema.adoc | 56 --- .../workingwithapachesyncope/cli/task.adoc | 67 --- .../workingwithapachesyncope/cli/user.adoc | 79 --- .../installation/installation.adoc | 23 - .../installation/maven.adoc | 19 - .../restfulservices/client-library.adoc | 60 --- .../restfulservices/restful-reference.adoc | 74 --- .../restfulservices/restful-services.adoc | 30 -- .../workingwithapachesyncope.adoc | 48 -- 117 files changed, 3121 insertions(+), 3363 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/pom.xml ---------------------------------------------------------------------- diff --git a/pom.xml b/pom.xml index 84cfb94..0646c84 100644 --- a/pom.xml +++ b/pom.xml @@ -1820,6 +1820,7 @@ under the License. <configuration> <doctype>book</doctype> <relativeBaseDir>true</relativeBaseDir> + <imagesDir>${basedir}/src/main/asciidoc/images</imagesDir> <sourceHighlighter>highlightjs</sourceHighlighter> <attributes> <docVersion>${project.version}</docVersion> @@ -1841,7 +1842,7 @@ under the License. <goal>process-asciidoc</goal> </goals> <configuration> - <sourceDocumentName>getting-started.adoc</sourceDocumentName> + <sourceDocumentName>getting-started/getting-started.adoc</sourceDocumentName> <backend>html</backend> </configuration> </execution> @@ -1852,7 +1853,7 @@ under the License. <goal>process-asciidoc</goal> </goals> <configuration> - <sourceDocumentName>getting-started.adoc</sourceDocumentName> + <sourceDocumentName>getting-started/getting-started.adoc</sourceDocumentName> <backend>pdf</backend> <attributes> <pdf-stylesdir>${basedir}/src/main/asciidoc</pdf-stylesdir> @@ -1867,7 +1868,7 @@ under the License. <goal>process-asciidoc</goal> </goals> <configuration> - <sourceDocumentName>reference-guide.adoc</sourceDocumentName> + <sourceDocumentName>reference-guide/reference-guide.adoc</sourceDocumentName> <backend>html</backend> </configuration> </execution> @@ -1878,7 +1879,7 @@ under the License. <goal>process-asciidoc</goal> </goals> <configuration> - <sourceDocumentName>reference-guide.adoc</sourceDocumentName> + <sourceDocumentName>reference-guide/reference-guide.adoc</sourceDocumentName> <backend>pdf</backend> <attributes> <pdf-stylesdir>${basedir}/src/main/asciidoc</pdf-stylesdir> http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/architecture/architecture.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/architecture/architecture.adoc b/src/main/asciidoc/architecture/architecture.adoc deleted file mode 100644 index 924c42b..0000000 --- a/src/main/asciidoc/architecture/architecture.adoc +++ /dev/null @@ -1,24 +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. -// - -== Architecture - -include::designprinciples.adoc[] - -include::implementationguidelines.adoc[] \ No newline at end of file http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/architecture/designprinciples.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/architecture/designprinciples.adoc b/src/main/asciidoc/architecture/designprinciples.adoc deleted file mode 100644 index 017107e..0000000 --- a/src/main/asciidoc/architecture/designprinciples.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. -// -=== Design Principles \ No newline at end of file http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/architecture/implementationguidelines.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/architecture/implementationguidelines.adoc b/src/main/asciidoc/architecture/implementationguidelines.adoc deleted file mode 100644 index 04af80f..0000000 --- a/src/main/asciidoc/architecture/implementationguidelines.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. -// -=== Implementation Guidelines \ No newline at end of file http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/commondocs/debpackages.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/commondocs/debpackages.adoc b/src/main/asciidoc/commondocs/debpackages.adoc deleted file mode 100644 index 6bd8441..0000000 --- a/src/main/asciidoc/commondocs/debpackages.adoc +++ /dev/null @@ -1,105 +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. -// -=== Debian packages - -Debian packages are available for use with http://www.debian.org/[Debian GNU / Linux^], -http://www.ubuntu.com/[Ubuntu^] and their derivatives. - -[CAUTION] -.Target Audience -Getting up and running quickly on Debian / Ubuntu. + -*Difficult to extend beyond pre-sets.* - -Download:: -http://syncope.apache.org/downloads.html[Download^] the latest .deb packages - -Prepare:: -. Install Apache Tomcat 8 -+ -[source,bash] -sudo apt-get install tomcat8 -+ -[WARNING] -*Ubuntu LTS 14.04 LTS* does not provide the tomcat8 package by default: you will need instead to download and manually -install the following packages (from Ubuntu 14.10): -http://packages.ubuntu.com/vivid/all/libecj-java/download[libecj-java] -http://packages.ubuntu.com/vivid/all/libtomcat8-java/download[libtomcat8-java] -http://packages.ubuntu.com/vivid/all/tomcat8-common/download[tomcat8-common] -http://packages.ubuntu.com/vivid/all/tomcat8/download[tomcat8] -+ -. Install PostgreSQL -+ -[source,bash] -sudo apt-get install libpostgresql-jdbc-java postgresql postgresql-client -+ -. Use the PostgreSQL JDBC driver with Tomcat -+ -[source,bash] -sudo ln -s /usr/share/java/postgresql-jdbc4.jar /usr/share/tomcat8/lib/ -+ -. Replace `JAVA_OPTS` in `/etc/default/tomcat8` with the following: -+ -[source,bash] ----- -JAVA_OPTS="-Djava.awt.headless=true -Dfile.encoding=UTF-8 -server \ - -Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m - -XX:PermSize=256m -XX:MaxPermSize=256m -XX:+DisableExplicitGC" ----- -+ -Install:: -. Stop Tomcat -+ -[source,bash] -sudo service tomcat8 stop -+ -. Install Apache Syncope core, console and enduser via the downloaded packages -+ -[source,bash] -sudo dpkg -i apache-syncope-*.deb -+ -. Create a database for use with Apache Syncope -+ -[source,bash] -sudo SYNCOPE_USER="syncope" SYNCOPE_PASS="syncope" sh /usr/share/apache-syncope/dbinit-postgresql.sh -+ -. Start Tomcat -+ -[source,bash] -sudo service tomcat8 start - -==== Components - -CAUTION: The following assumes that Apache Tomcat is reachable on host `host.domain` and port `port`. - -[cols="1,2"] -|=== - -| Complete REST API reference -| http://host.domain:port/syncope/index.html - -| http://swagger.io/[Swagger^] UI -| http://host.domain:port/syncope/swagger/ - -| Administration console -| http://host.domain:port/syncope-console/ + - -| End-user UI -| http://localhost:9080/syncope-enduser/ - -|=== \ No newline at end of file http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/commondocs/guiinstaller.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/commondocs/guiinstaller.adoc b/src/main/asciidoc/commondocs/guiinstaller.adoc deleted file mode 100644 index 8840e93..0000000 --- a/src/main/asciidoc/commondocs/guiinstaller.adoc +++ /dev/null @@ -1,129 +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. -// -=== GUI Installer - -GUI application for configuring and deploying Apache Syncope on supported -<<internal-storage,DBMSes>> and <<java-ee-container, Java EE containers>>. - -[CAUTION] -.Target Audience -Getting up and running quickly on any supported DBMS and Java EE container, independently from the underlying -operating system. + -*Difficult to extend beyond pre-sets.* - -==== Prerequisites - - . http://maven.apache.org/[Apache Maven^] (version 3.0.3 or higher) installed - . one of the supported <<internal-storage,DBMSes>> up and running - . one of the supported <<java-ee-container, Java EE containers>> up and running - . A datasource with the name `syncopeDataSource` configured in the selected Java EE container, for a database instance in the - DBMS of choice - -[WARNING] -==== -When deploying on Apache Tomcat, don't forget to configure a `manager` user; if not done yet, ensure that the content -of `$CATALINA_HOME/conf/tomcat-users.xml` looks like: - -[source,xml] -<?xml version='1.0' encoding='utf-8'?> -<tomcat-users> - <role rolename="manager-gui"/> - <role rolename="manager-script"/> - <role rolename="manager-jmx"/> - <role rolename="manager-status"/> - <user username="manager" password="s3cret" roles="manager-script"/> -</tomcat-users> -==== - -==== Usage - -Once http://syncope.apache.org/downloads.html[downloaded^], double-click the JAR file or execute via the command-line: - -[source,bash] -java -jar syncope-installer-*-uber.jar - -image::installer-1.png[installer-1] - -image::installer-2.png[installer-2] - -image::installer-3.png[installer-3] - -image::installer-4.png[installer-4] - -Installation path:: -* installation path: is the directory where Syncope overlay will be created - -image::installer-5.png[installer-5] - -Maven:: -* *Maven home directory:* is the Maven home directory; -* *Group ID:* something like 'com.mycompany' - maven overlay property; -* *Artifact ID:* something like 'myproject' - maven overlay property; -* *Secret Key:* Provide any pseudo-random, 16 character length, string here that will be used in the generated project for AES ciphering; -* *Anonymous Key:* - Provide any pseudo-random, 16 character length, string here that will be used in the generated project for AES ciphering; -* *Configuration directory:* where Syncope configuration files are stored; -* *Log directory:* where Syncope logs are stored; -* *Bundle directory:* where ConnId bundles are stored; -* *Syncope version:* the project version that would be to install. - -image::installer-6.png[installer-6] - -Syncope options:: -* *Swagger:* check if you want to install http://swagger.io[Swagger UI^]; -* *Camel:* check if you want to install http://camel.apache.org[Camel provisioning^]; -* *Activiti workflow modeler:* check if you want to install http://activiti.org[Activiti modeler^] (default is true); - -image::installer-7.png[installer-7] - -Database:: -* DBMS where Syncope will be installed; - -image::installer-8.png[installer-8] - -Database settings:: -* Depends on DBMS selected (in the example: PostgreSQL) -** Database JDBS url; -** Database user; -** Database password; - -image::installer-9.png[installer-9] - -Application server:: -* Container where Syncope will be deployed; - -image::installer-10.png[installer-10] - -Application server settings:: -* Depends on container selected (in the example: Tomcat) - -The next images shows how the installer print some feedback directly on the GUI or reading the log file under the -configuration directory: - -[source] --- -/var/tmp/syncope_2_0_0/install.log --- - -image::installer-11.png[installer-11] - -image::installer-12.png[installer-12] - -image::installer-13.png[installer-13] - -image::installer-14.png[installer-14] http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/commondocs/maven.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/commondocs/maven.adoc b/src/main/asciidoc/commondocs/maven.adoc deleted file mode 100644 index d588f1f..0000000 --- a/src/main/asciidoc/commondocs/maven.adoc +++ /dev/null @@ -1,124 +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. -// -=== Maven Project - -This is the *preferred method* for working with Apache Syncope, giving access to the whole set of customization -and extension capabilities. - -[CAUTION] -.Target Audience -Provides access to the full capabilities of Apache Syncope, and almost all extensions that are possible. + -*Requires Apache Maven (and potentially https://en.wikipedia.org/wiki/DevOps[DevOps^]) skills.* - -==== Prerequisites - - . http://maven.apache.org/[Apache Maven^] (version 3.0.3 or higher) installed - . Some basic knowledge about Maven - . Some basic knowledge about http://maven.apache.org/guides/introduction/introduction-to-archetypes.html[Maven archetypes^]. - -==== Create project - -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 ('\'). - -ifeval::["{snapshotOrRelease}" == "release"] - -[subs="verbatim,attributes"] ----- -mvn archetype:generate \ - -DarchetypeGroupId=org.apache.syncope \ - -DarchetypeArtifactId=syncope-archetype \ - -DarchetypeRepository=http://repo1.maven.org/maven2 \ - -DarchetypeVersion={docVersion} ----- - -endif::[] - -ifeval::["{snapshotOrRelease}" == "snapshot"] - -[subs="verbatim,attributes"] ----- -mvn archetype:generate \ - -DarchetypeGroupId=org.apache.syncope \ - -DarchetypeArtifactId=syncope-archetype \ - -DarchetypeRepository=http://repository.apache.org/content/repositories/snapshots \ - -DarchetypeVersion={docVersion} ----- - -[WARNING] -==== -Once the Maven project is generated, add the following right before `</project>` in the root `pom.xml` of the -generated project: - -[source,xml] ----- -<repositories> - <repository> - <id>ASF</id> - <url>https://repository.apache.org/content/repositories/snapshots/</url> - <snapshots> - <enabled>true</enabled> - </snapshots> - </repository> -</repositories> ----- -==== - -endif::[] - -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 - -[source,bash] -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. - -[NOTE] -You should consider reading the _Apache Syncope Reference Guide_ to understand how to configure, extend, customize -and deploy your new Apache Syncope project. http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/concepts/concepts.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/concepts/concepts.adoc b/src/main/asciidoc/concepts/concepts.adoc deleted file mode 100644 index 2e63820..0000000 --- a/src/main/asciidoc/concepts/concepts.adoc +++ /dev/null @@ -1,55 +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. -// -== Concepts - -=== Data model - -==== Schema - -==== Attributes - -==== Users, Groups and Any objects - -==== Realms - -==== Domains - -=== Tasks - -include::provisioning/provisioning.adoc[] - -=== Policies - -==== Account - -==== Password - -==== Push - -==== Pull - -=== Workflow and Approval - -=== Notifications - -=== Reports - -=== Audit - -=== Delegated Administration http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/concepts/provisioning/connectors.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/concepts/provisioning/connectors.adoc b/src/main/asciidoc/concepts/provisioning/connectors.adoc deleted file mode 100644 index 835d95a..0000000 --- a/src/main/asciidoc/concepts/provisioning/connectors.adoc +++ /dev/null @@ -1,32 +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. -// -==== Connectors -Syncope uses entities like connectors bundles, connector instances and external resources to synchronize user accounts -with and propagate to external systems. This paragraph clarifies what the responsibility and scope of each of these entities are. - -===== Connector bundle -Connector bundles are the components that are able to connect to classes of systems when configured correctly and -told to do so. They are not bound to Syncope specifically, as they are part of the separate framework -http://connid.tirasa.net/[ConnId], but they can be plugged into a deployed Syncope system. - -===== Connector instance -Connectors instances are instance of connector bundles, obtained by assigning values to configuration properties -defined in bundles. -For instance, there is only a single "DatabaseTable connector" (the bundle) that can be instantiated many times, for -example if there is need to connect to two different databases. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/concepts/provisioning/propagation.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/concepts/provisioning/propagation.adoc b/src/main/asciidoc/concepts/provisioning/propagation.adoc deleted file mode 100644 index d58ba53..0000000 --- a/src/main/asciidoc/concepts/provisioning/propagation.adoc +++ /dev/null @@ -1,34 +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. -// -==== Propagation -The propagation is the mechanism to extend provisioning operations on external resources. -The propagation layer implements remote creation, maintenance, activation and deactivation of user and role objects -and their attributes. -A propagation towards a specific external resource occurs if and only if the external resource's connector -instance capabilities permit. -Propagation will be tried on an external resource for each provisioning operation involving users or roles assigned -to that resource. - -===== Configuration -Connectors:: -Connector instances can be configured to create, update and delete operations. -Propagation tasks:: -When propagation tasks are created, their propagation mode will be set according to the mode of the external resource. -Operation:: -When tasks are executed, the execution status will be set to SUCCESS or FAILURE, based on the actual propagation result. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/concepts/provisioning/provisioning.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/concepts/provisioning/provisioning.adoc b/src/main/asciidoc/concepts/provisioning/provisioning.adoc deleted file mode 100644 index 4a9c957..0000000 --- a/src/main/asciidoc/concepts/provisioning/provisioning.adoc +++ /dev/null @@ -1,37 +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. -// -=== Provisioning -The main purpose of identity management systems is to manage user and role provisioning. -User and role provisioning refers to the creation, maintenance, activation and deactivation of user and role objects -and their attributes. Provisioning operations can act on Apache Syncope only or be propagated towards external -resources as well. -The provisioning operation can be initiated by an authorized user (for instance, working on Apache Syncope -administration console) or by an internal task like a pull task. -A push task can be used to perform a bulk provisioning operation involving either Syncope and one -or more external resources. - -include::connectors.adoc[] - -include::resources.adoc[] - -include::propagation.adoc[] - -include::push.adoc[] - -include::pull.adoc[] http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/concepts/provisioning/pull.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/concepts/provisioning/pull.adoc b/src/main/asciidoc/concepts/provisioning/pull.adoc deleted file mode 100644 index bf2157a..0000000 --- a/src/main/asciidoc/concepts/provisioning/pull.adoc +++ /dev/null @@ -1,52 +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. -// -==== Pull -Basically, pull is the mechanism used by Apache Syncope to acquire user, group and any objects data from external resources. -Pull can be "full" (full reconciliation) or "incremental". -In the former case, each pull task execution will take over just of changes from the previous execution -(if exists and connector permits incremental pull). -In the latter case, each pull task execution will take over of the entire set of data managed by the external resource. - -===== From an external resource to Syncope -All the entity (user/group) data involved by a pull are retrieved from an external resource and processed -internally by Syncope itself. -A retrieved entity can be: - -. a matching entity, if a corresponding local/internal entity has been found; -. or an unmatching entity, otherwise. - -By default, Syncope will create locally all the unmatching entities (without linking entities and resources) and will -update all the matching ones. -By the way, a different behaviour can be configured working with matching/unmatching rules. - -===== Matching and Unmatching rules -Unmatching (corresponding user not found on Syncope): - -* IGNORE / UNLINK (do not perform any action); -* ASSIGN (create entity linking the resource); -* PROVISION (create entity without linking the resource). - -Matching (corresponding users found on Syncope): - -* IGNORE (do not perform any action); -* UPDATE (update matching entity); -* DEPROVISION (delete resource entity); -* UNASSIGN (unlink resource and delete resource entity) ; -* UNLINK (just unlink resource without performing any (de-)provisioning operation); -* LINK (just link resource without performing any (de-)provisioning operation). \ No newline at end of file http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/concepts/provisioning/push.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/concepts/provisioning/push.adoc b/src/main/asciidoc/concepts/provisioning/push.adoc deleted file mode 100644 index 06ea053..0000000 --- a/src/main/asciidoc/concepts/provisioning/push.adoc +++ /dev/null @@ -1,51 +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. -// -==== Push -Basically, the push is a sort of synchronization mechanism used by Apache Syncope to propagate a filtered set of -user/role/membership data to external resources. -Push can be "full" only: all the data matching the configured filter (potentially the same set of data) will be sent -to the external resource at each push task execution. - -===== From Syncope to an external resource -All the entity (user/group) data involved by a push are retrieved locally and compared with remote ones before sending out. -An entity to be sent out can be: - -. a matching entity, if a corresponding remote entity has been found; -. or an unmatching entity, otherwise. - -By default, Syncope will propagate all the unmatching entities for provisioning (without linking entities and resources) -and will update all the matching ones. -By the way, a different behaviour can be configured working with matching/unmatching rules. - -===== Matching and Unmatching rules -Unmatching (corresponding user not found on external resource): - -* IGNORE (do not perform any action); -* UNLINK (just unlink resource without performing any (de-)provisioning operation - of course, if any link is found); -* ASSIGN (provision entity linking the resource); -* PROVISION (provision entity without linking the resource). - -Matching (corresponding users found on external resource): - -* IGNORE (do not perform any action); -* UPDATE (update matching entity); -* DEPROVISION (delete resource entity); -* UNASSIGN (unlink resource and delete resource entity) ; -* UNLINK (just unlink resource without performing any (de-)provisioning operation); -* LINK (just link resource without performing any (de-)provisioning operation). \ No newline at end of file http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/concepts/provisioning/resources.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/concepts/provisioning/resources.adoc b/src/main/asciidoc/concepts/provisioning/resources.adoc deleted file mode 100644 index 03c78af..0000000 --- a/src/main/asciidoc/concepts/provisioning/resources.adoc +++ /dev/null @@ -1,51 +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. -// -==== Resources -The propagation implements the provisioning on external resources. It depends on the assignment, directly or indirectly - (via memberships), of users/roles to external resources. -Users and roles can be assigned or linked to an external resource in three different ways: with a soft link, -with a hard link, without any link (see below for more details). -Each provisioning operation involving a certain user/role will be propagated (if permitted by resource connector -instance capabilities) towards each resource linked by the user/role object itself. -In general, the provisioning won't occur on a certain external resource if any direct/indirect link exists with -that resource. - -===== Manage external resource provisioning directly -Provisioning will occur on a certain external resource every time the operation involves users or roles assigned -to that resource. -Users and roles can be assigned to an external resource by defining a direct or indirect link between objects. -By the way, Apache Syncope empowers the possibility to control the existence of users/roles on external resources -giving the possibility to manage remote provisioning directly. -In fact, an authorized user (or an internal task - a pull task, for instance) can ask for - -* *link / unlink* users/roles to/from specific resources (soft link), -* *assign / unassign* users/roles to/from specific resources (hard link), -* *provision / de-provision* users/roles on/from specific resources (maybe, without any link). - -link/unlink:: -Apache Syncope gives the possibility to create and remove a sort of soft linking between users/roles and resources. -This kind of link doesn't imply any propagation at link creation/deletion time. -Provision/De-Provision:: -Apache Syncope gives the possibility to directly provision and de-provision users/roles on/from resources, without any -link in place. This provisioning feature (disjoint from the resource link mechanisms) is often very useful in case -of reclaims. -Assign/Unassign:: -Apache Syncope gives the possibility to create and remove a sort of hard linking between users/roles and resources. -This kind of link implies propagation at link creation/deletion time: it is the composition between link/unlink and -provision/de-provision operations. http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/extensions/extensions.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/extensions/extensions.adoc b/src/main/asciidoc/extensions/extensions.adoc deleted file mode 100644 index 7da12d7..0000000 --- a/src/main/asciidoc/extensions/extensions.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. -// -== Extensions - -=== Apache Camel \ No newline at end of file http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/getting-started.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/getting-started.adoc b/src/main/asciidoc/getting-started.adoc deleted file mode 100644 index 38f7020..0000000 --- a/src/main/asciidoc/getting-started.adoc +++ /dev/null @@ -1,59 +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. -// - -// Quick reference: http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ -// User manual: http://asciidoctor.org/docs/user-manual/ -// Tricks: https://leanpub.com/awesomeasciidoctornotebook/read - -:homepage: http://syncope.apache.org -:description: Several ways to get started with Apache Syncope -:keywords: Apache Syncope, IdM, provisioning, identity management, getting started, tutorial - -:docinfo1: -:last-update-label!: -:sectanchors: -:sectnums: -:sectlinks: - -= Apache Syncope - Getting Started -:revnumber: {docVersion} -:toc: right -:toclevels: 4 - -image::http://syncope.apache.org/images/apache-syncope-logo-small.jpg[Apache Syncope logo] - -[NOTE] -.This document is under active development and discussion! -If you find errors or omissions in this document, please donât hesitate to -http://syncope.apache.org/issue-tracking.html[submit an issue] or -https://github.com/apache/syncope/pulls[open a pull request] with -a fix. We also encourage you to ask questions and discuss any aspects of the project on the -http://syncope.apache.org/mailing-lists.html[mailing lists or IRC]. -New contributors are always welcome! - -[discrete] -== Preface -This guide shows you how to get started with Apache Syncope services for identity management, provisioning, and -compliance. - -include::introduction.adoc[] - -include::systemRequirements.adoc[] - -include::obtain.adoc[] \ No newline at end of file http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/getting-started/getting-started.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/getting-started/getting-started.adoc b/src/main/asciidoc/getting-started/getting-started.adoc new file mode 100644 index 0000000..a26ce46 --- /dev/null +++ b/src/main/asciidoc/getting-started/getting-started.adoc @@ -0,0 +1,61 @@ +// +// 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. +// + +// Quick reference: http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ +// User manual: http://asciidoctor.org/docs/user-manual/ +// Tricks: https://leanpub.com/awesomeasciidoctornotebook/read + +:homepage: http://syncope.apache.org +:description: Several ways to get started with Apache Syncope +:keywords: Apache Syncope, IdM, provisioning, identity management, getting started, tutorial + +:docinfo1: +:last-update-label!: +:sectanchors: +:sectnums: +:sectlinks: + += Apache Syncope - Getting Started +:revnumber: {docVersion} +:toc: right +:toclevels: 4 + +image::http://syncope.apache.org/images/apache-syncope-logo-small.jpg[Apache Syncope logo] + +[NOTE] +.This document is under active development and discussion! +If you find errors or omissions in this document, please donât hesitate to +http://syncope.apache.org/issue-tracking.html[submit an issue] or +https://github.com/apache/syncope/pulls[open a pull request] with +a fix. We also encourage you to ask questions and discuss any aspects of the project on the +http://syncope.apache.org/mailing-lists.html[mailing lists or IRC]. +New contributors are always welcome! + +[discrete] +== Preface +This guide shows you how to get started with Apache Syncope services for identity management, provisioning, and +compliance. + +include::introduction.adoc[] + +include::systemRequirements.adoc[] + +include::obtain.adoc[] + +include::movingForward.adoc[] http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/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 new file mode 100644 index 0000000..19eb534 --- /dev/null +++ b/src/main/asciidoc/getting-started/introduction.adoc @@ -0,0 +1,146 @@ +// +// 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 objects 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 in 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 tecnologies 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] +==== +As you can notice, *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 few +drawbacks are just around the corner: + +. 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 organization + +=== A bird's eye view on the Architecture of Apache Syncope + +[.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 audit over all) + * *_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 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. + * *_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 _SyncopeClient_ 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. +**** http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/getting-started/movingForward.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/getting-started/movingForward.adoc b/src/main/asciidoc/getting-started/movingForward.adoc new file mode 100644 index 0000000..0c072e3 --- /dev/null +++ b/src/main/asciidoc/getting-started/movingForward.adoc @@ -0,0 +1,30 @@ +// +// 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. +// + +== Moving Forward + +Once obtained a working installation of Apache Syncope using one of the methods reported above, you should consider +reading the +ifeval::["{backend}" == "html5"] +http://syncope.apache.org/docs/reference-guide.html[Apache Syncope Reference Guide] +endif::[] +ifeval::["{backend}" == "pdf"] +http://syncope.apache.org/docs/reference-guide.pdf[Apache Syncope Reference Guide] +endif::[] +to understand how to configure, extend, customize and deploy your new Apache Syncope project. http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/getting-started/obtain.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/getting-started/obtain.adoc b/src/main/asciidoc/getting-started/obtain.adoc new file mode 100644 index 0000000..aab53cc --- /dev/null +++ b/src/main/asciidoc/getting-started/obtain.adoc @@ -0,0 +1,489 @@ +// +// 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. +// + +== Obtain Apache Syncope + +There are several ways to obtain Apache Syncope: each of which has advantages or caveats for different types of users. + +=== Standalone + +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. + +[CAUTION] +.Target Audience +First approach, especially with administration console and end-user; does not require technical skills. + +*Not meant for any production environment.* + +Getting ready in a few easy steps: + +. http://syncope.apache.org/downloads.html[download^] the standalone distribution +. unzip the distribution archive +. go into the created Apache Tomcat directory +. start Apache Tomcat +* GNU / Linux, Mac OS X ++ +[source,bash] +---- +$ chmod 755 ./bin/*.sh +$ ./bin/startup.sh +---- ++ +* Windows ++ +[source,cmd] +---- +> bin/startup.bat +---- + +[TIP] +Please refer to the http://tomcat.apache.org/tomcat-8.0-doc/[Apache Tomcat documentation^] for more advanced setup and +instructions. + +==== Components + +The set of available components, including access URLs and credentials, is the same as reported for +<<paths-and-components,embedded mode>>, with the exception of log files, available here under `$CATALINA_HOME/logs`. + +[TIP] +.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 + +[source,java] +jpa.url=jdbc:h2:mem:syncopedb;DB_CLOSE_DELAY=-1 + +with + +[source,java] +jpa.url=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. + +Please refer to the http://www.h2database.com/[H2 documentation^] for more options. +==== + +=== Debian packages + +Debian packages are available for use with http://www.debian.org/[Debian GNU / Linux^], +http://www.ubuntu.com/[Ubuntu^] and their derivatives. + +[CAUTION] +.Target Audience +Getting up and running quickly on Debian / Ubuntu. + +*Difficult to extend beyond pre-sets.* + +Download:: +http://syncope.apache.org/downloads.html[Download^] the latest .deb packages + +Prepare:: +. Install Apache Tomcat 8 ++ +[source,bash] +sudo apt-get install tomcat8 ++ +[WARNING] +*Ubuntu LTS 14.04 LTS* does not provide the tomcat8 package by default: you will need instead to download and manually +install the following packages (from Ubuntu 14.10): +http://packages.ubuntu.com/vivid/all/libecj-java/download[libecj-java] +http://packages.ubuntu.com/vivid/all/libtomcat8-java/download[libtomcat8-java] +http://packages.ubuntu.com/vivid/all/tomcat8-common/download[tomcat8-common] +http://packages.ubuntu.com/vivid/all/tomcat8/download[tomcat8] ++ +. Install PostgreSQL ++ +[source,bash] +sudo apt-get install libpostgresql-jdbc-java postgresql postgresql-client ++ +. Use the PostgreSQL JDBC driver with Tomcat ++ +[source,bash] +sudo ln -s /usr/share/java/postgresql-jdbc4.jar /usr/share/tomcat8/lib/ ++ +. Replace `JAVA_OPTS` in `/etc/default/tomcat8` with the following: ++ +[source,bash] +---- +JAVA_OPTS="-Djava.awt.headless=true -Dfile.encoding=UTF-8 -server \ + -Xms1536m -Xmx1536m -XX:NewSize=256m -XX:MaxNewSize=256m + -XX:PermSize=256m -XX:MaxPermSize=256m -XX:+DisableExplicitGC" +---- ++ +Install:: +. Stop Tomcat ++ +[source,bash] +sudo service tomcat8 stop ++ +. Install Apache Syncope core, console and enduser via the downloaded packages ++ +[source,bash] +sudo dpkg -i apache-syncope-*.deb ++ +. Create a database for use with Apache Syncope ++ +[source,bash] +sudo SYNCOPE_USER="syncope" SYNCOPE_PASS="syncope" sh /usr/share/apache-syncope/dbinit-postgresql.sh ++ +. Start Tomcat ++ +[source,bash] +sudo service tomcat8 start + +==== Components + +CAUTION: The following assumes that Apache Tomcat is reachable on host `host.domain` and port `port`. + +[cols="1,2"] +|=== + +| Complete REST API reference +| http://host.domain:port/syncope/index.html + +| http://swagger.io/[Swagger^] UI +| http://host.domain:port/syncope/swagger/ + +| Administration console +| http://host.domain:port/syncope-console/ + + +| End-user UI +| http://localhost:9080/syncope-enduser/ + +|=== + +=== GUI Installer + +GUI application for configuring and deploying Apache Syncope on supported +<<internal-storage,DBMSes>> and <<java-ee-container, Java EE containers>>. + +[CAUTION] +.Target Audience +Getting up and running quickly on any supported DBMS and Java EE container, independently from the underlying +operating system. + +*Difficult to extend beyond pre-sets.* + +==== Prerequisites + + . http://maven.apache.org/[Apache Maven^] (version 3.0.3 or higher) installed + . one of the supported <<internal-storage,DBMSes>> up and running + . one of the supported <<java-ee-container, Java EE containers>> up and running + . A datasource with the name `syncopeDataSource` configured in the selected Java EE container, for a database instance in the + DBMS of choice + +[WARNING] +==== +When deploying on Apache Tomcat, don't forget to configure a `manager` user; if not done yet, ensure that the content +of `$CATALINA_HOME/conf/tomcat-users.xml` looks like: + +[source,xml] +<?xml version='1.0' encoding='utf-8'?> +<tomcat-users> + <role rolename="manager-gui"/> + <role rolename="manager-script"/> + <role rolename="manager-jmx"/> + <role rolename="manager-status"/> + <user username="manager" password="s3cret" roles="manager-script"/> +</tomcat-users> +==== + +==== Usage + +Once http://syncope.apache.org/downloads.html[downloaded^], double-click the JAR file or execute via the command-line: + +[source,bash] +java -jar syncope-installer-*-uber.jar + +image::installer-1.png[installer-1] + +image::installer-2.png[installer-2] + +image::installer-3.png[installer-3] + +image::installer-4.png[installer-4] + +Installation path:: +* installation path: is the directory where Syncope overlay will be created + +image::installer-5.png[installer-5] + +Maven:: +* *Maven home directory:* is the Maven home directory; +* *Group ID:* something like 'com.mycompany' - maven overlay property; +* *Artifact ID:* something like 'myproject' - maven overlay property; +* *Secret Key:* Provide any pseudo-random, 16 character length, string here that will be used in the generated project for AES ciphering; +* *Anonymous Key:* - Provide any pseudo-random, 16 character length, string here that will be used in the generated project for AES ciphering; +* *Configuration directory:* where Syncope configuration files are stored; +* *Log directory:* where Syncope logs are stored; +* *Bundle directory:* where ConnId bundles are stored; +* *Syncope version:* the project version that would be to install. + +image::installer-6.png[installer-6] + +Syncope options:: +* *Swagger:* check if you want to install http://swagger.io[Swagger UI^]; +* *Camel:* check if you want to install http://camel.apache.org[Camel provisioning^]; +* *Activiti workflow modeler:* check if you want to install http://activiti.org[Activiti modeler^] (default is true); + +image::installer-7.png[installer-7] + +Database:: +* DBMS where Syncope will be installed; + +image::installer-8.png[installer-8] + +Database settings:: +* Depends on DBMS selected (in the example: PostgreSQL) +** Database JDBS url; +** Database user; +** Database password; + +image::installer-9.png[installer-9] + +Application server:: +* Container where Syncope will be deployed; + +image::installer-10.png[installer-10] + +Application server settings:: +* Depends on container selected (in the example: Tomcat) + +The next images shows how the installer print some feedback directly on the GUI or reading the log file under the +configuration directory: + +[source] +-- +/var/tmp/syncope_2_0_0/install.log +-- + +image::installer-11.png[installer-11] + +image::installer-12.png[installer-12] + +image::installer-13.png[installer-13] + +image::installer-14.png[installer-14] + +==== Components + +CAUTION: The following assumes that the Java EE container is reachable on host `host.domain` and port `port`. + +[cols="1,2"] +|=== + +| Complete REST API reference +| http://host.domain:port/syncope/index.html + +| http://swagger.io/[Swagger^] UI +| http://host.domain:port/syncope/swagger/ + +| Administration console +| http://localhost:9080/syncope-console/ + +Credentials: `admin` / `password` + +| End-user UI +| http://localhost:9080/syncope-enduser/ + +|=== + +=== Maven Project + +This is the *preferred method* for working with Apache Syncope, giving access to the whole set of customization +and extension capabilities. + +[CAUTION] +.Target Audience +Provides access to the full capabilities of Apache Syncope, and almost all extensions that are possible. + +*Requires Apache Maven (and potentially https://en.wikipedia.org/wiki/DevOps[DevOps^]) skills.* + +==== Prerequisites + + . http://maven.apache.org/[Apache Maven^] (version 3.0.3 or higher) installed + . Some basic knowledge about Maven + . Some basic knowledge about http://maven.apache.org/guides/introduction/introduction-to-archetypes.html[Maven archetypes^]. + +==== Create project + +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 ('\'). + +ifeval::["{snapshotOrRelease}" == "release"] + +[subs="verbatim,attributes"] +---- +mvn archetype:generate \ + -DarchetypeGroupId=org.apache.syncope \ + -DarchetypeArtifactId=syncope-archetype \ + -DarchetypeRepository=http://repo1.maven.org/maven2 \ + -DarchetypeVersion={docVersion} +---- + +endif::[] + +ifeval::["{snapshotOrRelease}" == "snapshot"] + +[subs="verbatim,attributes"] +---- +mvn archetype:generate \ + -DarchetypeGroupId=org.apache.syncope \ + -DarchetypeArtifactId=syncope-archetype \ + -DarchetypeRepository=http://repository.apache.org/content/repositories/snapshots \ + -DarchetypeVersion={docVersion} +---- + +[WARNING] +==== +Once the Maven project is generated, add the following right before `</project>` in the root `pom.xml` of the +generated project: + +[source,xml] +---- +<repositories> + <repository> + <id>ASF</id> + <url>https://repository.apache.org/content/repositories/snapshots/</url> + <snapshots> + <enabled>true</enabled> + </snapshots> + </repository> +</repositories> +---- +==== + +endif::[] + +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 + +[source,bash] +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. + +==== Embedded Mode + +Every Apache Syncope project has the ability to run a full-blown in-memory environment, particularly useful either when +evaluating the product and during the development phase of an IdM solution. + +[WARNING] +==== +Don't forget that this environment is completely in-memory: this means that every time Maven is stopped, all changes +made are lost. +==== + +From the top-level directory of your project, execute: + +[source,bash] +mvn -P all clean install + +then, from the `enduser` subdirectory, execute: + +[source,bash] +mvn -P embedded,all + +===== Paths and Components + +[cols="1,2"] +|=== + +| Log files +| Available under `core/target/log`, `console/target/log` and `enduser/target/log` + +| ConnId bundles +| Available under `core/target/bundles` + +| Complete REST API reference +| http://localhost:9080/syncope/index.html + +| http://swagger.io/[Swagger^] UI +| http://localhost:9080/syncope/swagger/ + +| Administration console +| http://localhost:9080/syncope-console/ + +Credentials: `admin` / `password` + +| End-user UI +| http://localhost:9080/syncope-enduser/ + +| Internal storage +| A SQL web interface is available at http://localhost:9080/syncope/db.jsp + + + + Choose configuration 'Generic H2 (Embedded)' + + Insert `jdbc:h2:mem:syncopedb` as JDBC URL + + Click 'Connect' button + +| External resource: LDAP +| An http://directory.apache.org/apacheds/[Apache DS^] instance is available. + +You can configure any LDAP client (as http://jxplorer.org/[JXplorer^], for example) with the following information: + + + + host: `localhost` + + port: `1389` + + base DN: `o=isp` + + bind DN: `uid=admin,ou=system` + + bind password: `secret` + +| External resource: SOAP +| An example SOAP server is available at http://localhost:9080/wssample/services + + + + You can check its internal data by visiting http://localhost:9080/wssample/exploredb.jsp + +| External resource: database +| http://www.h2database.com/[H2^] TCP database is available. + + + + A SQL web interface is available at http://localhost:9082/ + + + + Choose configuration 'Generic H2 (Server)' + + Insert `jdbc:h2:tcp://localhost:9092/mem:testdb` as JDBC URL + + Set 'sa' as password + + Click 'Connect' button + +|=== http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/getting-started/systemRequirements.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/getting-started/systemRequirements.adoc b/src/main/asciidoc/getting-started/systemRequirements.adoc new file mode 100644 index 0000000..51ce41c --- /dev/null +++ b/src/main/asciidoc/getting-started/systemRequirements.adoc @@ -0,0 +1,52 @@ +// +// 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. +// + +== System Requirements + +=== Hardware + +The hardware requirements depend greatly on the given deployment, in particular the total number of +managed entities (users, groups and any objects), their attributes and resources. + + * CPU: dual core, 2 GHz (minimum) + * RAM: 2 GB (minimum) + * Disk: 100 MB (minimum) + +=== Java + +Apache Syncope {docVersion} requires the latest JDK 7 or JDK 8 that is available. + +=== Java EE Container + +Apache Syncope {docVersion} is verified with the following Java EE containers: + + . http://tomcat.apache.org/download-80.cgi[Apache Tomcat 8 and 8.5^] + . https://glassfish.java.net/[Glassfish 4.1^] + . http://www.payara.fish/[Payara Server^] + . http://www.wildfly.org/[Wildfly 9 and 10^] + +=== Internal Storage + +Apache Syncope {docVersion} is verified with the recent versions of the following DBMSes, for internal storage: + + . http://www.postgresql.org/[PostgreSQL^] + . https://mariadb.org/[MariaDB^] + . http://www.mysql.com/[MySQL^] + . https://www.oracle.com/database/index.html[Oracle Database^] + . http://www.microsoft.com/en-us/server-cloud/products/sql-server/[MS SQL Server^] http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/iam/accessmanager/accessmanager.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/iam/accessmanager/accessmanager.adoc b/src/main/asciidoc/iam/accessmanager/accessmanager.adoc deleted file mode 100644 index df8d2c9..0000000 --- a/src/main/asciidoc/iam/accessmanager/accessmanager.adoc +++ /dev/null @@ -1,25 +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. -// -=== Access Managers -As briefly mentioned before, in general an access manager is not an identity manager. An access management software -manages above all the authentication on a given environment. It provides the methods, generally called authentication -module, to manage the user authentication, the latter based on various identification systems as the password, -the fingerprint or based on various protocols as SAML and OAuth 2.0. - -include::authentication.adoc[] http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/iam/accessmanager/authentication.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/iam/accessmanager/authentication.adoc b/src/main/asciidoc/iam/accessmanager/authentication.adoc deleted file mode 100644 index e1e992e..0000000 --- a/src/main/asciidoc/iam/accessmanager/authentication.adoc +++ /dev/null @@ -1,69 +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. -// - -==== Authentication and authorization -The security aspects mostly involve examining how RESTful controllers implement communication with external -world. Hence, security is mostly implemented and enforced by the core, as the console is basically an external REST -client (check High-level Architecture for more details). - -===== Entitlements -Authentication and authorization in Syncope is fundamentally based on Entitlements. -Entitlements are basically strings describing the right to perform an operation. -Default entitlements are included at the end of content.xml and always loaded into internal storage. -Entitlements can only be assigned to roles: this is the basis of a role-based authorization mechanism. - -* Normal entitlements:: -related to the general operations that can be performed (like as TASK_DELETE or CONNECTOR_UPDATE); -* Role operational entitlements:: -specifically bound to each and every role defined (like as ROLE_10 or ROLE_23). - -Why such distinction is needed? Because Syncope implements a delegated role-based authorization model so that a user -can manage other users and this can be specified with a very fine-grained mechanism. - -===== Role ownership -Starting with Syncope 1.1.0, the role owner concept was introduced: a user or a role can be defined as owner of a given -role. -Users owning a role (or user assigned to a role owning a role) are granted to perform any operation on the owned role and -also assigned any role operational entitlement of owned role. -This means that if such owners are also granted some user-related entitlements (like as USER_CREATE or USER_UPDATE), -then they will be entitled to administer users of owned role as well. - -===== Example -Let's suppose that we want to implement the following scenario: -_Administrator A can create users under role 5 but not under role 7, administrator B can update users under role 6 and 8, -administrator C can update role 8._ -In this scenario, Syncope will have defined at least the following entitlements: - -* USER_CREATE, USER_UPDATE, ROLE_UPDATE -* ROLE_5, ROLE_6, ROLE_7, ROLE_8 - -Here it follows how entitlements should be assigned to administrators in order to implement the scenario above: - -* A: USER_CREATE + ROLE_5 -* B: USER_UPDATE + ROLE_6 + ROLE_8 -* C: ROLE_UPDATE + ROLE_8 - -With role ownership, if administrator D is set as owner of role 8, the following entitlements will be automatically -granted: - -* D: ROLE_READ + ROLE_CREATE + ROLE_UPDATE + ROLE_DELETE + ROLE_8 - -===== Root administrator -There is of course a special admin user, granted by all the entitlements defined in the system, thus capable of -performing any available operation. http://git-wip-us.apache.org/repos/asf/syncope/blob/c95b6ff5/src/main/asciidoc/iam/iam.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/iam/iam.adoc b/src/main/asciidoc/iam/iam.adoc deleted file mode 100644 index d5f3b76..0000000 --- a/src/main/asciidoc/iam/iam.adoc +++ /dev/null @@ -1,36 +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. -// - -== Identity and Access Management -Though Identity management and Access Management are often united, because the two management worlds often coexist in the -same projects or in the same environment, the two topics are completely different: each one has its context, its rules, -its best practices. On the other hand, many softwares have unorthodox implementations so you could do the same thing with -both of them. -However, in general as suggested by their name, the access management basically handles the access in a certain -environment providing some kind of credentials; on the contrary the identity management handles the digital identity -profile and its lifecycle. -Apache Syncope is an identity manager. - -include::identitystores.adoc[] - -include::provisioningengines.adoc[] - -include::accessmanager/accessmanager.adoc[] - -include::thecompletepicture.adoc[]
