src/main/asciidoc/reference-guide/concepts/roles.adoc

//
// 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.
//
=== Roles

Roles map a set of <<entitlements,entitlements>> to a set of <<realms,realms>> and / or
<<dynamic-realms, dynamic realms>>.

In addition, Roles can be used to assign <<privileges,privileges>> to Users.

[TIP]
.Static and Dynamic Memberships
====
Users are _statically_ assigned to roles when assignments are explicitly set.

However, a condition can be expressed in the role definition 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~m~, can 
exercise E~i~ on entities (Users, Groups, Any Objects of given types - depending on E~i~ - or Connector Instances and 
External Resources) under any Re~j~ or related sub-realms.

Moreover, any user U assigned to a role R, which provides entitlements E~1~...E~n~ for dynamic realms DR~1~..DR~n~, can
exercise E~i~ on entities (Users, Groups, Any Objects of given types, depending on E~i~) matching the conditions defined
for any DR~k~.

[WARNING]
.Dynamic Realms limitations
====
Users to whom administration rights were granted via Dynamic Realms can only *update* Users, Groups and Any Objects,
not create nor delete. +
Moreover, the only accepted changes on a given entity are the ones that do not change any Dynamic Realm's matching
condition for such entity.
====

.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 by default, Apache Syncope will have defined the following entitlements, among others:

* `USER_CREATE`
* `USER_UPDATE`
* `GROUP_UPDATE`

Hence, here is how entitlements should be assigned (via roles) to administrators in order to implement the scenario 
above:

* Administrator A: `USER_CREATE` on R~5~
* Administrator B: `USER_UPDATE` on R~6~ and R~8~
* Administrator C: `GROUP_UPDATE` on R~8~
====

[[delegated-administration-console]]
[TIP]
.Delegated Administration via Admin Console
====
When administering via <<REST>>, the entitlements to be granted to delegated administrators are straightforward:
`USER_CREATE` for certain <<Realms>> will allow to create users under such Realms.

When using the <<Admin Console>>, instead, more entitlements are generally required: this because the underlying
implementation takes care of simplifying the UX as much as possible. +
For example, the following entitlements are normally required to be granted for user administration, besides the actual
`USER_CREATE`, `USER_UPDATE` and `USER_DELETE`:

. `USER_SEARCH`
. `ANYTYPECLASS_READ`
. `ANYTYPE_LIST`
. `ANYTYPECLASS_LIST`
. `RELATIONSHIPTYPE_LIST`
. `USER_READ`
. `ANYTYPE_READ`
. `REALM_LIST`
. `GROUP_SEARCH`
====

===== Group Ownership

Groups can designate a User or another Group as _owner_.

The practical consequence of this setting is that Users owning a Group (either because they are directly set as owners
or members of the owning Group) is that they are entitled to

* perform all operations (create, update, delete, ...) on the owned Group
* perform all operations (create, update, delete, ...) on all User and Any Object members of the owner Group, with
exception of removing members from the Group itself

regardless of the Realm.

The actual Entitlements are assigned through the predefined `GROUP_OWNER` Role:

. `USER_SEARCH`
. `USER_READ`
. `USER_CREATE`
. `USER_UPDATE`
. `USER_DELETE`
. `ANYTYPECLASS_READ`
. `ANYTYPE_LIST`
. `ANYTYPECLASS_LIST`
. `RELATIONSHIPTYPE_LIST`
. `ANYTYPE_READ`
. `REALM_LIST`
. `GROUP_SEARCH`
. `GROUP_READ`
. `GROUP_UPDATE`
. `GROUP_DELETE`

The `GROUP_OWNER` Role can be updated to adjust the set of assigned Entitlements.

==== Delegation

With Delegation, any user can delegate other users to perform operations on their behalf.

In order to set up a Delegation, the following information shall be provided:

* delegating User (mandatory) - administrators granted with `DELEGATION_CREATE` Entitlement can create Delegations for
all defined Users; otherwise, the only accepted value is the User itself;
* delegated User (mandatory) - any User defined, distinct from delegating;
* start (mandatory) - initial timestamp from which the Delegation is considered effective;
* end (optional) - final timestamp after which the Delegation is not considered effective: when not provided, Delegation
will remain valid unless deleted;
* roles (optional) - set of Roles granted by delegating to delegated User: only Roles owned by delegating can be
granted, when not provided all owned Roles are considered as part of the Delegation.

[NOTE]
<<Audit>> entries generated when operating under Delegation will report both delegating and delegated users.