//
// 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 a leaf or root of a sub-tree of realms;
. is uniquely identified by the path from the 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 the root realm;
. optionally refers to <<policies-account,account>> and <<policies-password,password>> policies: such policies are
enforced on all Users, Groups and Any Objects in the given realm and sub-realms, unless some sub-realms define their own policies.

If Users, Groups and Any Objects are members of a realm then they are also members of the 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,memberships and relationships>>:

* A User or an Any Object can be members of Groups in the same realm or in one of the parent realms.
* A User or an Any object can be in a relation with Any Objects in the same realm or in one of parent realms.

Moreover, this partition allows fine-grained control over policy enforcement and, alongside with
<<entitlements,entitlements>> and <<roles,roles>>, helps to implement
<<delegated-administration,delegated administration>>.

[[dynamic-realms]]
.Dynamic Realms
****
Realms provide a means to model static containment hierarchies. +
This might not be the ideal fit for situations where the set of Users, Groups and Any Objects to administer
cannot be statically defined by containment.

Dynamic Realms can be used to identify Users, Groups and Any Objects according to some attributes' value, resource
assignment, group membership or any other condition available, with purpose of granting
<<delegated-administration,delegated administration>> rights.
****

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

Logic Templates apply to all operations passing through the <<logic,logic layer>>, e.g. triggered by REST requests.
====

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

A typical use case for realm provisioning is to model an organization-like structure on Identity Stores, as
with LDAP and Active Directory.

==== LogicActions

When Users, Groups or Any Objects get created, updated or deleted in a realm, custom logic can be invoked
by associating the given Realm with one or more <<implementations,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.

[NOTE]
LogicActions apply to all operations passing through the <<logic,logic layer>>, e.g. triggered by REST requests.