[SYNCOPE-1041] Documentation - This closes #45
Project: http://git-wip-us.apache.org/repos/asf/syncope/repo Commit: http://git-wip-us.apache.org/repos/asf/syncope/commit/944ac3d1 Tree: http://git-wip-us.apache.org/repos/asf/syncope/tree/944ac3d1 Diff: http://git-wip-us.apache.org/repos/asf/syncope/diff/944ac3d1 Branch: refs/heads/2_0_X Commit: 944ac3d131d190704e284392b7cdad22c1d1d65b Parents: 622806c Author: Francesco Chicchiriccò <[email protected]> Authored: Tue Mar 28 15:34:36 2017 +0200 Committer: Francesco Chicchiriccò <[email protected]> Committed: Fri Mar 31 15:26:23 2017 +0200 ---------------------------------------------------------------------- .../wicket/markup/html/form/XMLEditorPanel.java | 10 +- .../console/panels/SAML2IdPsDirectoryPanel.java | 3 +- src/main/asciidoc/getting-started/obtain.adoc | 4 +- src/main/asciidoc/images/installer-6.png | Bin 47589 -> 47072 bytes .../reference-guide/concepts/extensions.adoc | 41 +++++-- .../workingwithapachesyncope/customization.adoc | 58 ++++++++- .../systemadministration/keystore.adoc | 123 +++++++++++++++++++ .../systemadministration.adoc | 2 + 8 files changed, 220 insertions(+), 21 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/syncope/blob/944ac3d1/client/console/src/main/java/org/apache/syncope/client/console/wicket/markup/html/form/XMLEditorPanel.java ---------------------------------------------------------------------- diff --git a/client/console/src/main/java/org/apache/syncope/client/console/wicket/markup/html/form/XMLEditorPanel.java b/client/console/src/main/java/org/apache/syncope/client/console/wicket/markup/html/form/XMLEditorPanel.java index 4249641..3399225 100644 --- a/client/console/src/main/java/org/apache/syncope/client/console/wicket/markup/html/form/XMLEditorPanel.java +++ b/client/console/src/main/java/org/apache/syncope/client/console/wicket/markup/html/form/XMLEditorPanel.java @@ -18,7 +18,6 @@ */ package org.apache.syncope.client.console.wicket.markup.html.form; -import java.io.Serializable; import org.apache.syncope.client.console.panels.AbstractModalPanel; import org.apache.syncope.client.console.wicket.markup.html.bootstrap.dialog.BaseModal; import org.apache.wicket.PageReference; @@ -27,7 +26,7 @@ import org.apache.wicket.markup.head.OnLoadHeaderItem; import org.apache.wicket.markup.html.form.TextArea; import org.apache.wicket.model.IModel; -public class XMLEditorPanel extends AbstractModalPanel<Serializable> { +public class XMLEditorPanel extends AbstractModalPanel<String> { private static final long serialVersionUID = -5110368813584745668L; @@ -40,7 +39,7 @@ public class XMLEditorPanel extends AbstractModalPanel<Serializable> { } public XMLEditorPanel( - final BaseModal<Serializable> modal, + final BaseModal<String> modal, final IModel<String> content, final boolean readOnly, final PageReference pageRef) { @@ -66,9 +65,4 @@ public class XMLEditorPanel extends AbstractModalPanel<Serializable> { + " autoRefresh: true" + "}).on('change', updateTextArea);")); } - - @Override - public IModel<String> getItem() { - return content; - } } http://git-wip-us.apache.org/repos/asf/syncope/blob/944ac3d1/ext/saml2sp/client-console/src/main/java/org/apache/syncope/client/console/panels/SAML2IdPsDirectoryPanel.java ---------------------------------------------------------------------- diff --git a/ext/saml2sp/client-console/src/main/java/org/apache/syncope/client/console/panels/SAML2IdPsDirectoryPanel.java b/ext/saml2sp/client-console/src/main/java/org/apache/syncope/client/console/panels/SAML2IdPsDirectoryPanel.java index 8a8d06e..2b3dd70 100644 --- a/ext/saml2sp/client-console/src/main/java/org/apache/syncope/client/console/panels/SAML2IdPsDirectoryPanel.java +++ b/ext/saml2sp/client-console/src/main/java/org/apache/syncope/client/console/panels/SAML2IdPsDirectoryPanel.java @@ -19,7 +19,6 @@ package org.apache.syncope.client.console.panels; import de.agilecoders.wicket.core.markup.html.bootstrap.dialog.Modal; -import java.io.Serializable; import java.util.ArrayList; import java.util.Collection; import java.util.Collections; @@ -68,7 +67,7 @@ public class SAML2IdPsDirectoryPanel extends DirectoryPanel< private static final String PREF_SAML2_IDPS_PAGINATOR_ROWS = "saml2.idps.paginator.rows"; - private final BaseModal<Serializable> metadataModal = new BaseModal<>("outer"); + private final BaseModal<String> metadataModal = new BaseModal<>("outer"); public SAML2IdPsDirectoryPanel(final String id, final PageReference pageRef) { super(id, new Builder<SAML2IdPTO, SAML2IdPTO, SAML2IdPsRestClient>(new SAML2IdPsRestClient(), pageRef) { http://git-wip-us.apache.org/repos/asf/syncope/blob/944ac3d1/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 index c06e2aa..60f7235 100644 --- a/src/main/asciidoc/getting-started/obtain.adoc +++ b/src/main/asciidoc/getting-started/obtain.adoc @@ -47,13 +47,13 @@ $ ./bin/startup.sh + * Windows + -[source,cmd] +[source,dos] ---- > bin/startup.bat ---- [TIP] -Please refer to the http://tomcat.apache.org/tomcat-8.0-doc/[Apache Tomcat documentation^] for more advanced setup and +Please refer to the http://tomcat.apache.org/tomcat-8.5-doc/[Apache Tomcat documentation^] for more advanced setup and instructions. [[standalone-components]] http://git-wip-us.apache.org/repos/asf/syncope/blob/944ac3d1/src/main/asciidoc/images/installer-6.png ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/images/installer-6.png b/src/main/asciidoc/images/installer-6.png index c97d5f2..e66648e 100644 Binary files a/src/main/asciidoc/images/installer-6.png and b/src/main/asciidoc/images/installer-6.png differ http://git-wip-us.apache.org/repos/asf/syncope/blob/944ac3d1/src/main/asciidoc/reference-guide/concepts/extensions.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/concepts/extensions.adoc b/src/main/asciidoc/reference-guide/concepts/extensions.adoc index f89a79e..8f4730d 100644 --- a/src/main/asciidoc/reference-guide/concepts/extensions.adoc +++ b/src/main/asciidoc/reference-guide/concepts/extensions.adoc @@ -23,8 +23,8 @@ every single deployment with unneeded libraries and configurations. With reference to <<architecture,architecture>>, an extension might add a <<rest>> endpoint, manage the <<persistence,persistence>> of additional entities, extend the <<security,security>> mechanisms, tweak the -<<provisioning-layer,provisioning layer>>, add features to the <<admin-console-component,admin console>>, or even bring -all such things together. +<<provisioning-layer,provisioning layer>>, add features to the <<admin-console-component>> or +the <<enduser-component>>, or even bring all such things together. Extensions are available from different sources: @@ -59,12 +59,6 @@ endif::[] . ==== -[TIP] -==== -This extension adds features to all components and layers that are available, and can be taken as reference when creating -<<customization-extensions,new extensions>>. -==== - ==== Swagger This extension enables http://swagger.io/swagger-ui/[Swagger UI^] as web interface for dealing with Apache Syncope @@ -90,3 +84,34 @@ https://github.com/apache/syncope/tree/tree/2_0_X/ext/swagger-ui[source tree^] endif::[] . ==== + +==== SAML 2.0 Service Provider + +This extension can be leveraged to provide +https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language[SAML 2.0^]-based +https://en.wikipedia.org/wiki/Single_sign-on[Single Sign-On^] access to the <<admin-console-component>>, +the <<enduser-component>> or any other Java EE application dealing with the <<core>>. + +Once installed, one or more https://en.wikipedia.org/wiki/Identity_provider[Identity Providers^] can be imported from +their https://en.wikipedia.org/wiki/SAML_2.0#SAML_2.0_Metadata[metadata^]. +For each Identity Provider, it is to configure which one of the attributes - returned as part of the assertion +containing the attribute statements - is going to be used by Syncope to match the internal users. + +[NOTE] +.Extension Sources +==== +The source code of this extension is available from the Apache Syncope +ifeval::["{snapshotOrRelease}" == "release"] +https://github.com/apache/syncope/tree/syncope-{docVersion}/ext/saml2sp[source tree^] +endif::[] +ifeval::["{snapshotOrRelease}" == "snapshot"] +https://github.com/apache/syncope/tree/tree/2_0_X/ext/saml2sp[source tree^] +endif::[] +. +==== + +[TIP] +==== +This extension adds features to all components and layers that are available, and can be taken as reference when creating +<<customization-extensions,new extensions>>. +==== http://git-wip-us.apache.org/repos/asf/syncope/blob/944ac3d1/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc index 47df12c..9430ccc 100644 --- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc +++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/customization.adoc @@ -317,6 +317,30 @@ Add the following dependency to `core/pom.xml`: </dependency> ---- +[discrete] +===== Enable the <<saml-2-0-service-provider>> extension + +Add the following dependencies to `core/pom.xml`: + +[source,xml,subs="verbatim,attributes"] +---- +<dependency> + <groupId>org.apache.syncope.ext.saml2sp</groupId> + <artifactId>syncope-ext-saml2sp-rest-cxf</artifactId> + <version>${syncope.version}</version> +</dependency> +<dependency> + <groupId>org.apache.syncope.ext.saml2sp</groupId> + <artifactId>syncope-ext-saml2sp-persistence-jpa</artifactId> + <version>${syncope.version}</version> +</dependency> +---- + +Copy `core/src/main/resources/all/saml2sp-logic.properties` to `core/src/main/resources/saml2sp-logic.properties`. + +Setup a <<keystore,keystore>> and place it under the <<properties-files-location,configuration directory>>, then review +the content of `core/src/main/resources/saml2sp-logic.properties` accordingly. + [[customization-console]] ==== Console @@ -339,6 +363,22 @@ Add the following dependency to `console/pom.xml`: </dependency> ---- +[discrete] +===== Enable the <<saml-2-0-service-provider>> extension + +Add the following dependencies to `console/pom.xml`: + +[source,xml,subs="verbatim,attributes"] +---- +<dependency> + <groupId>org.apache.syncope.ext.saml2sp</groupId> + <artifactId>syncope-ext-saml2sp-client-console</artifactId> + <version>${syncope.version}</version> +</dependency> +---- + +Copy `console/src/main/resources/all/saml2sp-agent.properties` to `console/src/main/resources/saml2sp-agent.properties`. + [[customization-enduser]] ==== Enduser @@ -348,6 +388,22 @@ generated under the local project's `enduser/src/main/webapp/app/` directory and The files in use by the Apache Wicket-based backend are still subject to the general <<override-behavior,override behavior>>, instead. +[discrete] +===== Enable the <<saml-2-0-service-provider>> extension + +Add the following dependencies to `enduser/pom.xml`: + +[source,xml,subs="verbatim,attributes"] +---- +<dependency> + <groupId>org.apache.syncope.ext.saml2sp</groupId> + <artifactId>syncope-ext-saml2sp-client-enduser</artifactId> + <version>${syncope.version}</version> +</dependency> +---- + +Copy `enduser/src/main/resources/all/saml2sp-agent.properties` to `enduser/src/main/resources/saml2sp-agent.properties`. + [[customization-enduser-translations]] ===== Translations @@ -409,5 +465,5 @@ and modify the JSON files under the new directory <<extensions>> can be part of a local project, to encapsulate special features which are specific to a given deployment. For example, the http://www.chorevolution.eu/[CHOReVOLUTION^] IdM - based on Apache Syncope - provides -https://tuleap.ow2.org/plugins/git/chorevolution/syncope?p=syncope.git&a=tree&f=ext/choreography[an extension^] +https://gitlab.ow2.org/chorevolution/syncope/tree/master/ext/choreography[an extension^] for managing via the <<core>> and visualizing via the <<admin-console-component>> the running choreography instances. http://git-wip-us.apache.org/repos/asf/syncope/blob/944ac3d1/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/keystore.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/keystore.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/keystore.adoc new file mode 100644 index 0000000..7f7d03b --- /dev/null +++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/keystore.adoc @@ -0,0 +1,123 @@ +// +// 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. +// +==== Keystore + +A https://en.wikipedia.org/wiki/Keystore[Java Keystore^] is a container for authorization certificates or public key +certificates, and is often used by Java-based applications for encryption, authentication, and serving over HTTPS. +Its entries are protected by a keystore password. A keystore entry is identified by an alias, and it consists of keys +and certificates that form a trust chain. + +A keystore is currently required by the <<saml-2-0-service-provider>> extension in order to sign and / or encrypt the +generated SAML 2.0 requests. + +While a sample keystore is provided, it is *strongly* recommended to setup a production keystore; in the following, a +reference procedure for this is reported. + +[WARNING] +The procedure below is not meant to cover all possible options and scenarios for generating a keystore, nor to provide +complete coverage of the `keytool` command. + +[discrete] +===== Create new keystore + +[source,bash] +---- +keytool -genkey \ + -keyalg RSA \ + -keysize 2048 \ + -alias saml2sp \ + -dname "CN=SAML2SP,OU=Apache Syncope, O=The ASF, L=Wilmington, ST=Delaware, C=US" \ + -keypass akyepass \ + -storepass astorepass \ + -storetype JKS \ + -keystore saml2sp.jks +---- + +This command will create a keystore file with name `saml2sp.jks` in the execution directory, containing a new 2048-bit +RSA key pair, under the specified alias (`saml2sp`); password values for `keypass` and `storepass` are also set. + +[discrete] +===== Create new CSR + +[source,bash] +---- +keytool -certreq \ + -alias saml2sp \ + -keyalg RSA \ + -file certreq.pem \ + -keypass akyepass \ + -storepass astorepass \ + -storetype JKS \ + -keystore saml2sp.jks +---- + +This command will create a CSR file with name `certreq.pem` in the execution directory, within the keystore generated +above. + +The generated CSR file can be sent to a Certificate Authority (CA) to request the issuance of a CA-signed certificate. + +[discrete] +===== Have the CSR signed by a Certificate Authority (CA) + +This step cannot be automated, and is definitely out of the scope of the this document. + +Before proceeding, it is fundamental to have ready the root / intermediate CA certificate(s) and the signed certificate. + +[discrete] +===== Import the certificates into the keystore + +[source,bash] +---- +keytool -import \ + -alias root \ + -file cacert.pem \ + -keypass akyepass \ + -storepass astorepass \ + -storetype JKS \ + -keystore saml2sp.jks +---- + +This command will import the root / intermediate CA certificate(s) from the `cacert.pem` file into the keystore +generated above. + +[source,bash] +---- +keytool -import \ + -alias saml2sp \ + -file cert.pem \ + -keypass akyepass \ + -storepass astorepass \ + -storetype JKS \ + -keystore saml2sp.jks +---- + +This command will import the signed certificate from the `cert.pem` file into the keystore generated above. + +[discrete] +===== Finalize + +The keystore file `saml2sp.jks` must be now placed in the <<properties-files-location,configuration directory>>; the +relevant part of the `saml2sp-agent.properties` file should be: + +.... +keystore.name=saml2sp.jks +keystore.type=jks +keystore.storepass=astorepass +keystore.keypass=akyepass +sp.cert.alias=saml2sp +.... http://git-wip-us.apache.org/repos/asf/syncope/blob/944ac3d1/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/systemadministration.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/systemadministration.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/systemadministration.adoc index 016c391..1e90d0f 100644 --- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/systemadministration.adoc +++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/systemadministration.adoc @@ -70,4 +70,6 @@ include::connectorbundles.adoc[] include::emailconfiguration.adoc[] +include::keystore.adoc[] + include::configurationparameters.adoc[]
