//
// 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;
. refers to <<anytypeclass,any type class(es)>> which allow to define plain and derived attributes;
. optionally refers to various <<policies,policies>> that are enforced on all Users, Groups and Any Objects in the given
realm and sub-realms, unless some sub-realms define their own policies.
. optionally refers to <<logicactions,logic action(s)>>
. optionally defines <<logic-templates,entity templates>>

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 partition allows fine-grained control over policy enforcement and, alongside with
<<entitlements,entitlements>> and <<roles,roles>>, helps to implement 
<<delegated-administration,delegated administration>>.

[[logic-templates]]
[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/idrepo/logic/src/main/java/org/apache/syncope/core/logic/api/LogicActions.java[LogicActions^]
endif::[]
ifeval::["{snapshotOrRelease}" == "snapshot"]
https://github.com/apache/syncope/blob/4_1_X/core/idrepo/logic/src/main/java/org/apache/syncope/core/logic/api/LogicActions.java[LogicActions^]
endif::[]
interface.

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