[SYNCOPE-1035] Some documentation
Project: http://git-wip-us.apache.org/repos/asf/syncope/repo Commit: http://git-wip-us.apache.org/repos/asf/syncope/commit/52badc4b Tree: http://git-wip-us.apache.org/repos/asf/syncope/tree/52badc4b Diff: http://git-wip-us.apache.org/repos/asf/syncope/diff/52badc4b Branch: refs/heads/master Commit: 52badc4b9e8afa4b5042ba19c19e570c926dad88 Parents: 7004b84 Author: Francesco Chicchiriccò <ilgro...@apache.org> Authored: Fri Mar 3 11:06:24 2017 +0100 Committer: Francesco Chicchiriccò <ilgro...@apache.org> Committed: Fri Mar 3 11:07:03 2017 +0100 ---------------------------------------------------------------------- pom.xml | 4 +- .../concepts/usersgroupsandanyobjects.adoc | 4 +- .../restfulservices.adoc | 44 +++++++++++++++++++- .../configurationparameters.adoc | 2 + 4 files changed, 48 insertions(+), 6 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/syncope/blob/52badc4b/pom.xml ---------------------------------------------------------------------- diff --git a/pom.xml b/pom.xml index f1ae83a..6743c70 100644 --- a/pom.xml +++ b/pom.xml @@ -2061,8 +2061,8 @@ under the License. <link>http://fasterxml.github.io/jackson-dataformat-xml/javadoc/2.8/</link> <link>http://fasterxml.github.io/jackson-dataformat-yaml/javadoc/2.8/</link> <link>http://fasterxml.github.io/jackson-datatype-joda/javadoc/2.8/</link> - <link>http://camel.apache.org/maven/current/camel-core/apidocs/</link> - <link>http://camel.apache.org/maven/current/camel-spring/apidocs/</link> + <link>http://www.javadoc.io/doc/org.apache.camel/camel-core/2.17.5</link> + <link>http://www.javadoc.io/doc/org.apache.camel/camel-spring/2.17.5</link> <link>https://ci.apache.org/projects/wicket/apidocs/7.x/</link> <link>https://commons.apache.org/proper/commons-lang/javadocs/api-release/</link> <link>https://commons.apache.org/proper/commons-io/javadocs/api-2.5/</link> http://git-wip-us.apache.org/repos/asf/syncope/blob/52badc4b/src/main/asciidoc/reference-guide/concepts/usersgroupsandanyobjects.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/concepts/usersgroupsandanyobjects.adoc b/src/main/asciidoc/reference-guide/concepts/usersgroupsandanyobjects.adoc index a9aa2f9..09e9a3b 100644 --- a/src/main/asciidoc/reference-guide/concepts/usersgroupsandanyobjects.adoc +++ b/src/main/asciidoc/reference-guide/concepts/usersgroupsandanyobjects.adoc @@ -114,8 +114,8 @@ The usage of security questions can be however disabled by setting the `password [[password-reset-no-security-answer]] [WARNING] ==== -Once provided via Enduser UI, the answers to security questions are *never* reported, neither via REST or Admin UI to -administrators, nor to end-users via Enduser UI. +Once provided via Enduser Application, the answers to security questions are *never* reported, neither via REST or Admin UI to +administrators, nor to end-users via Enduser Application. This to avoid any information disclosure which can potentially lead attackers to reset other users' passwords. ==== http://git-wip-us.apache.org/repos/asf/syncope/blob/52badc4b/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices.adoc index 7adacd6..d52cc8e 100644 --- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices.adoc +++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices.adoc @@ -44,14 +44,54 @@ where `protocol`, `host` and `port` reflect your Java EE container installation. [TIP] The <<swagger,Swagger extension>> might also help greatly when working with RESTful services. +==== REST Authentication and Authorization + +The <<core>> authentication and authorization is based on http://projects.spring.io/spring-security/[Spring Security^]. + +As an initial step, authentication is required to obtain, in the `X-Syncope-Token` HTTP header, the +unique signed https://en.wikipedia.org/wiki/JSON_Web_Token[JSON Web Token^] to include in all subsequent requests. + +By providing the token received in the initial exchange, the requester can be identified and checked for authorization, +based on owned <<entitlements,entitlements>>. + +[NOTE] +Users can examine their own entitlements looking at the `<<x-syncope-entitlements,X-Syncope-Entitlements>>` +header value. + +[TIP] +==== +The relevant security configuration lies in +ifeval::["{snapshotOrRelease}" == "release"] +https://github.com/apache/syncope/blob/syncope-{docVersion}/core/spring/src/main/resources/securityContext.xml[securityContext.xml^]; +endif::[] +ifeval::["{snapshotOrRelease}" == "snapshot"] +https://github.com/apache/syncope/blob/master/core/spring/src/main/resources/securityContext.xml[securityContext.xml^]; +endif::[] +while normally not needed, this configuration can be anyway customized via the <<override-behavior,override behavior>>. + +https://en.wikipedia.org/wiki/Basic_access_authentication[HTTP Basic Authentication] is set for use by default. +==== + ==== REST Headers -Apache Syncope supports a number of HTTP headers as detailed below, in addition -to the common HTTP headers such as `Accept`, `Content-Type`, etc. +Apache Syncope supports a number of HTTP headers as detailed below, in addition to the common HTTP headers such as +`Accept`, `Content-Type`, etc. [TIP] It is possible to deal with the headers below when using the <<client-library>> via the `SyncopeClient` class methods. +===== X-Syncope-Token + +`X-Syncope-Token` is returned on response to <<rest-authentication-and-authorization,successful authentication>>, and +contains the unique signed https://en.wikipedia.org/wiki/JSON_Web_Token[JSON Web Token^] identifying the authenticated +user. + +The same header with provided value must be included in all subsequent requests, in order for the requester to +be checked for authorization. + +The token duration can be configured via the `jwt.lifetime.minutes` property - see +<<configuration-parameters, below>> for details. + ===== X-Syncope-Domain `X-Syncope-Domain` can be optionally set for requests (when not set, `Master` is assumed) to select the target http://git-wip-us.apache.org/repos/asf/syncope/blob/52badc4b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configurationparameters.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configurationparameters.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configurationparameters.adoc index d9550f6..fa70c8d 100644 --- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configurationparameters.adoc +++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/systemadministration/configurationparameters.adoc @@ -25,6 +25,8 @@ barely invoking the REST layer through http://curl.haxx.se/[curl^]: * `password.cipher.algorithm` - which cipher algorithm shall be used for encrypting password values; supported algorithms include `SHA-1`, `SHA-256`, `SHA-512`, `AES`, `S-MD5`, `S-SHA-1`, `S-SHA-256`, `S-SHA-512` and `BCRYPT`; salting options are available in the `security.properties` file; +* `jwt.lifetime.minutes` - validity of https://en.wikipedia.org/wiki/JSON_Web_Token[JSON Web Token^] values used for +<<rest-authentication-and-authorization,authentication>> (in minutes); * `notificationjob.cronExpression` - http://www.quartz-scheduler.org/documentation/quartz-2.2.x/tutorials/crontrigger.html[cron^] expression describing how frequently the pending <<tasks-notification,notification tasks>> are processed: empty means disabled;
