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

[NOTE]
.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, regardless of the Realm.
====

[[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`
====