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

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

.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_SEARCH`
. `GROUP_SEARCH`
====

===== Any Managers

Users, Groups and Any Objects can designate a User or a Group as their _manager_.

The practical consequence of this setting is that Users managing either Groups or other Users and Any Objects (either
because they are directly set as managers or are members of their managing Group) are entitled to perform all operations
(create, update, delete, ...) on the managed entities, regardless of the Realm where such entities are actually placed.

[TIP]
Working with Any Managers allows to dynamically identify sets of entities to enforce delegated administration on.

.Delegated Administration with Managers
====
Let's suppose there are Group G, User U and User M.

* Case 1: G sets M as its manager, U is member of G. +
⇒ M can administer both G and U.
* Case 2: M is member of G, U sets G as its manager. +
⇒ M can administer U.
====

==== 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>> events generated when operating under Delegation will report both delegating and delegated users.
