[SYNCOPE-700] Realms and entitlements
Project: http://git-wip-us.apache.org/repos/asf/syncope/repo Commit: http://git-wip-us.apache.org/repos/asf/syncope/commit/0e3ad3cf Tree: http://git-wip-us.apache.org/repos/asf/syncope/tree/0e3ad3cf Diff: http://git-wip-us.apache.org/repos/asf/syncope/diff/0e3ad3cf Branch: refs/heads/master Commit: 0e3ad3cf67c9d5578d6a0b65b2aa7d088c656983 Parents: 0c47ba1 Author: Francesco Chicchiriccò <ilgro...@apache.org> Authored: Thu Aug 4 17:45:48 2016 +0200 Committer: Francesco Chicchiriccò <ilgro...@apache.org> Committed: Thu Aug 4 17:45:48 2016 +0200 ---------------------------------------------------------------------- .../reference-guide/concepts/concepts.adoc | 94 ++++++++++++-------- .../reference-guide/concepts/entitlements.adoc | 63 +++++++++++++ .../concepts/externalresources.adoc | 8 +- .../concepts/provisioning/pull.adoc | 13 +++ .../reference-guide/concepts/realms.adoc | 72 +++++++++++++++ .../concepts/usersgroupsandanyobjects.adoc | 18 +++- 6 files changed, 223 insertions(+), 45 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/syncope/blob/0e3ad3cf/src/main/asciidoc/reference-guide/concepts/concepts.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/concepts/concepts.adoc b/src/main/asciidoc/reference-guide/concepts/concepts.adoc index 3bea53f..841c88a 100644 --- a/src/main/asciidoc/reference-guide/concepts/concepts.adoc +++ b/src/main/asciidoc/reference-guide/concepts/concepts.adoc @@ -24,10 +24,64 @@ include::typemanagement.adoc[] include::externalresources.adoc[] -=== Realms +include::realms.adoc[] + +include::entitlements.adoc[] === Roles +[TIP] +.Static and Dynamic Memberships +==== +Users are _statically_ assigned to roles when assignments are explicitely set. + +With role definition, however, a condition can be expressed so that all matching users are _dynamic_ members of the +role. +==== + +==== Delegated Administration + +The idea is that any user U assigned to a role R, which provides entitlements E~1~...E~n~ for realms Re~1~...Re~k~ can +exercise E~i~ on entities (users or groups, depending on the type of E~i~) under any Re~j~ or related sub-realms. + +About group membership and any relationships: + +* User U can be member of group G either if U and G are in the same realm, or G is in one of super-realms of the realm +of U +* Any object A~1~ can be in relationship with any object A~2~ either if A~1~ and A~2~ are in the same realm, or A~2~ is +in one of super-realms of the realm of A~1~ + +The rationale behind such conditions is to allow the definition of common groups and any objects (to enter in +relationship with) at the topmost position in the realm tree, so that they can be shared by various realm sub-trees. + +.Authorization +==== +Let's suppose that we want to implement the following scenario: + +**** +Administrator A can create users under realm R~5~ but not under realm R~7~, administrator B can update users under +realm R~6~ and R~8~, administrator C can update groups under realm R~8~. +**** + +As default, Syncope will have defined the following entitlements, among others: + +* `USER_CREATE` +* `USER_UPDATE` +* `GROUP_UPDATE` + +Here it follows how entitlements should be assigned (via roles) to administrators in order to implement the scenario +above: + +* A: `USER_CREATE` on R~5~ +* B: `USER_UPDATE` on R~6~ and R~8~ +* C: `GROUP_UPDATE` on R~8~ +==== + +[NOTE] +.Group Ownership +==== +==== + === Domains include::provisioning/provisioning.adoc[] @@ -72,41 +126,3 @@ include::provisioning/provisioning.adoc[] === Reports === Audit - -=== Delegated Administration - -The idea is that any user U assigned to a role R, which provides entitlements E~1~...E~n~ for realms Re~1~...Re~k~ can -exercise E~i~ on entities (users or groups, depending on the type of E~i~) under any Re~j~ or related sub-realms. - -About group membership and any relationships: - -* User U can be member of group G either if U and G are in the same realm, or G is in one of super-realms of the realm -of U -* Any object A~1~ can be in relationship with any object A~2~ either if A~1~ and A~2~ are in the same realm, or A~2~ is -in one of super-realms of the realm of A~1~ - -The rationale behind such conditions is to allow the definition of common groups and any objects (to enter in -relationship with) at the topmost position in the realm tree, so that they can be shared by various realm sub-trees. - -.Authorization -==== -Let's suppose that we want to implement the following scenario: - -**** -Administrator A can create users under realm R~5~ but not under realm R~7~, administrator B can update users under -realm R~6~ and R~8~, administrator C can update groups under realm R~8~. -**** - -As default, Syncope will have defined the following entitlements, among others: - -* `USER_CREATE` -* `USER_UPDATE` -* `GROUP_UPDATE` - -Here it follows how entitlements should be assigned (via roles) to administrators in order to implement the scenario -above: - -* A: `USER_CREATE` on R~5~ -* B: `USER_UPDATE` on R~6~ and R~8~ -* C: `GROUP_UPDATE` on R~8~ -==== http://git-wip-us.apache.org/repos/asf/syncope/blob/0e3ad3cf/src/main/asciidoc/reference-guide/concepts/entitlements.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/concepts/entitlements.adoc b/src/main/asciidoc/reference-guide/concepts/entitlements.adoc new file mode 100644 index 0000000..832293a --- /dev/null +++ b/src/main/asciidoc/reference-guide/concepts/entitlements.adoc @@ -0,0 +1,63 @@ +// +// 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. +// +=== Entitlements + +Entitlements are basically strings describing the right to perform an operation. + +The components in the <<logic,logic layer>> are annotated with +http://projects.spring.io/spring-security/[Spring Security^] to implement declarative security; in the following +code snippet taken from +ifeval::["{snapshotOrRelease}" == "release"] +https://github.com/apache/syncope/blob/syncope-{docVersion}/core/logic/src/main/java/org/apache/syncope/core/logic/RealmLogic.java[RealmLogic^] +endif::[] +ifeval::["{snapshotOrRelease}" == "snapshot"] +https://github.com/apache/syncope/blob/master/core/logic/src/main/java/org/apache/syncope/core/logic/RealmLogic.java[RealmLogic^] +endif::[] +, the +http://docs.spring.io/spring-security/site/docs/4.1.x/reference/htmlsingle/#el-common-built-in[`hasRole` expression^] +is used together with one of the standard entitlements to restrict access only to users owning the `REALM_LIST` +entitlement. + +[source,java] +---- +@PreAuthorize("hasRole('" + StandardEntitlement.REALM_LIST + "')") +public List<RealmTO> list(final String fullPath) { +---- + +Entitlements are granted via <<roles, roles>> to users, scoped under certain <<realms,realms>>, thus allowing +<<delegated-administration,delegated administration>>. + +[NOTE] +==== +The set of available entitlements is +ifeval::["{snapshotOrRelease}" == "release"] +https://github.com/apache/syncope/blob/syncope-{docVersion}/common/lib/src/main/java/org/apache/syncope/common/lib/types/StandardEntitlement.java[statically defined^] +endif::[] +ifeval::["{snapshotOrRelease}" == "snapshot"] +https://github.com/apache/syncope/blob/master/common/lib/src/main/java/org/apache/syncope/common/lib/types/StandardEntitlement.java[statically defined^] +endif::[] +- even though <<extensions,extensions>> have the ability to +ifeval::["{snapshotOrRelease}" == "release"] +https://github.com/apache/syncope/blob/syncope-{docVersion/ext/camel/common-lib/src/main/java/org/apache/syncope/common/lib/types/CamelEntitlement.java[enlarge the initial list^] +endif::[] +ifeval::["{snapshotOrRelease}" == "snapshot"] +https://github.com/apache/syncope/blob/master/ext/camel/common-lib/src/main/java/org/apache/syncope/common/lib/types/CamelEntitlement.java[enlarge the initial list^] +endif::[] +: this because entitlements are the pillars of internal security model and not meant for external usage. +==== http://git-wip-us.apache.org/repos/asf/syncope/blob/0e3ad3cf/src/main/asciidoc/reference-guide/concepts/externalresources.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/concepts/externalresources.adoc b/src/main/asciidoc/reference-guide/concepts/externalresources.adoc index 7720a4a..0fc4f9a 100644 --- a/src/main/asciidoc/reference-guide/concepts/externalresources.adoc +++ b/src/main/asciidoc/reference-guide/concepts/externalresources.adoc @@ -73,7 +73,7 @@ Given a selected connector instance, the following information is required for d * generate random password flag - under some circumstances, password might be mandatory but no actual value could be available: with this flag set, a random value will be generated, compliant with the defined <<policies-password,password policy>> (if set) -* propagation actions - which <<propagationactions,actions>> shall be execute during propagation +* propagation actions - which <<propagationactions,actions>> shall be executed during propagation * trace levels - control how much tracing (including logs and execution details) shall be carried over during <<propagation,propagation>>, <<provisioning-pull,pull>> and <<provisioning-push,push>> * configuration - see <<connector-instance-details,above>> @@ -124,13 +124,15 @@ this mapping item must be necessarily available or not; compared to simple boole express complex statements like as 'be mandatory only if this other attribute value is above 14', and so on * remote key flag - should this item be considered as the key value on the identity store? * password flag (users only) - should this item be treated as password value? -* purpose - should this item be considered for <<propagation,propagation>> / <<push,push>>, <<pull,pull>>, both or none? +* purpose - should this item be considered for <<propagation,propagation>> / <<provisioning-push,push>>, +<<provisioning-pull,pull>>, both or none? Besides items, some more data needs to be specified for a complete mapping: * ConnId `objectClass` - which http://connid.tirasa.net/apidocs/1.4/org/identityconnectors/framework/common/objects/ObjectClass.html[object class^] -shall be used during communication with identity store +shall be used during communication with identity store; predefined are `\\__ACCOUNT__` for users and +`\\__GROUP__` for groups * Object link - only required by some connector bundles as https://connid.atlassian.net/wiki/display/BASE/LDAP[LDAP^] and https://connid.atlassian.net/wiki/pages/viewpage.action?pageId=360482[Active Directory^], generally specifies the model http://git-wip-us.apache.org/repos/asf/syncope/blob/0e3ad3cf/src/main/asciidoc/reference-guide/concepts/provisioning/pull.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/concepts/provisioning/pull.adoc b/src/main/asciidoc/reference-guide/concepts/provisioning/pull.adoc index 92fff96..6444c18 100644 --- a/src/main/asciidoc/reference-guide/concepts/provisioning/pull.adoc +++ b/src/main/asciidoc/reference-guide/concepts/provisioning/pull.adoc @@ -66,6 +66,19 @@ this condition. + **** ==== +[[pull-templates]] +[TIP] +.Pull Templates +==== +With every <<tasks-pull,pull task>> it is possible to add a template for each defined <<anytype,any type>>. + +As the values specified in the template are applied to pulled entities, this can be used as mechanism for setting +default values for attributes or external resources on entities. + +A typical use case is, when pulling users from the external resource `R`, to automatically assign `R` so that every +further modification in Apache Syncope to such users will be <<propagation,propagated>> back to `R`. +==== + ===== PullActions The pull process can be decorated with custom logic to be invoked around task execution, by associating http://git-wip-us.apache.org/repos/asf/syncope/blob/0e3ad3cf/src/main/asciidoc/reference-guide/concepts/realms.adoc ---------------------------------------------------------------------- diff --git a/src/main/asciidoc/reference-guide/concepts/realms.adoc b/src/main/asciidoc/reference-guide/concepts/realms.adoc new file mode 100644 index 0000000..bd1ef66 --- /dev/null +++ b/src/main/asciidoc/reference-guide/concepts/realms.adoc @@ -0,0 +1,72 @@ +// +// 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. +// +=== Realms + +Realms define a hierarchical security domain tree, primarily meant for containing users, groups and +any objects. + +Each realm: + +. has a unique name and a parent realm - except for the pre-defined _root realm_, which is named `/`; +. is either leaf or root of a sub-tree of realms; +. is uniquely identified by the path from root realm, e.g. `/a/b/c` identifies the sub-realm `c` in the sub-tree rooted +at `b`, having in turn `a` as parent realm, directly under root realm; +. optionally refers to <<policies-account,account>> and <<policies-password,password>> policies: such policies are +enforced to all users, groups and any objects in the given realm and sub-realms, unless some sub-realms define their own. + +If users, groups and any objects are member of a realm then they are also member of parent realm: as a result, the root +realm contains everything, and other realms can be seen as containers that split up the total number of entities into +smaller pools. + +This has consequences on <<memberships-relationships,memberhips and relationships>>: + +* An user or an any object can be member of groups in the same realm or in one of sub-realms. +* An user or an any object can be in relation with any objects in the same realm or in one of sub-realms. + +Moreover, this partition allows fine-grained control over policy enforcement and, alongside with +<<entitlements,entitlements>> and <<roles,roles>>, contribute to implement +<<delegated-administration,delegated administration>>. + +[TIP] +.Logic Templates +==== +As with <<pull-templates,pull>> it is also possible to add templates to a realm. + +The values specified in the template are applied to entities belonging to that realm, hence this can be used as +a mechanism for setting default values for attributes or external resources on entities. +==== + +==== Realm Provisioning +<<provisioning>> can be enabled for realms: <<mapping,mapping>> information can be provided so that realms +are considered during <<propagation,propagation>>, <<provisioning-pull,pull>> and <<provisioning-push,push>>. + +Typical use cases for realm provisioning apply to modelization of organization-like structure on identity stores, as +with LDAP and Active Directory. + +==== LogicActions + +When users, groups or any objects get created, updated or deleted into a realm, custom logic can be invoked by +associating the given realm with one or more implementations of the +ifeval::["{snapshotOrRelease}" == "release"] +https://github.com/apache/syncope/blob/syncope-{docVersion}/core/provisioning-api/src/main/java/org/apache/syncope/core/provisioning/api/LogicActions.java[LogicActions^] +endif::[] +ifeval::["{snapshotOrRelease}" == "snapshot"] +https://github.com/apache/syncope/blob/master/core/provisioning-api/src/main/java/org/apache/syncope/core/provisioning/api/LogicActions.java[LogicActions^] +endif::[] +interface. http://git-wip-us.apache.org/repos/asf/syncope/blob/0e3ad3cf/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 90690cd..dcf9b42 100644 --- a/src/main/asciidoc/reference-guide/concepts/usersgroupsandanyobjects.adoc +++ b/src/main/asciidoc/reference-guide/concepts/usersgroupsandanyobjects.adoc @@ -55,12 +55,24 @@ Each user / group / any object will be able to hold values for all schemas: Moreover, users and any objects can be part of groups, or associated to other any objects. -[TIP] +[[memberships-relationships]] +[NOTE] .Memberships and Relationships ==== -When an user or an any object is assigned to a group, a *_membership_* is defined; the members of a group benefit -of <<type-extensions,type extensions>>. +When an user or an any object is assigned to a group, a *_membership_* is defined; the (static) members of a group +benefit of <<type-extensions,type extensions>>. When an user or an any object is associated to another any object, a *_relationship_* is defined, of one of available <<relationshiptype,relationship types>>. ==== + +[TIP] +.Static and Dynamic Memberships +==== +Users and any objects are _statically_ assigned to groups when memberships are explicitely set. + +With group definition, however, a condition can be expressed so that all matching users and any objects are +_dynamic_ members of the group. + +Dynamic memberships have some limitations: for example, <<type-extensions,type extensions>> do not apply; +group-based provisioning is still effective. +====
