IDM provides a default schema for typical managed object types, such as users and roles. This section provides information on how to change and add to the managed object schema, establish relationships between objects, and use policies to validate objects. You will also learn how to access IDM objects using queries.

These topics describe how to work with managed object types:

The IDM object model includes other object types besides managed objects.

For more information, refer to Data models and objects reference.

Managed objects and their properties are defined in the default IDM managed object schema.

The default schema includes these types of managed objects:

Each managed object type contains properties for storing information about objects of that type. For example, the user object type has properties for storing usernames, passwords, email addresses, and so forth.

You can extend the default IDM managed object schema to meet your needs:

To store custom data for users, you can add custom attributes (non-searchable) or adapt one of the general purpose extension attributes (searchable). Refer to Customize user identities.

To interact with a managed object schema via REST, refer to Schema.

If the managed object types provided in the default configuration are not sufficient for your deployment, you can create new ones. To do this through the Identity Cloud admin UI:

You can also create a new managed object type by editing your managed object schema. For more information, refer to Schema.

Every managed object type has a name and a schema that describes the properties associated with that object. The name can only include the characters a-z, A-Z, 0-9, and _ (underscore). You can add any arbitrary properties to the schema.

Properties can be derived from other properties within an object. This lets computed and composite values be created in the object. These derived properties are called virtual properties, and their value can be calculated in two ways:

For more information on extending attributes of the user object, refer to idcloud:identities:identity-cloud-identity-schema.adoc#extend_user_identities.

A number of script hooks let you manipulate managed objects using scripts. Scripts can be triggered during various stages of the lifecycle of the managed object, and are defined in the managed object schema.

You can trigger scripts when a managed object is:

Post-action scripts let you manipulate objects after they are:

For in-depth explanations of the various scripts, refer to managed object configuration properties.

Some self-service features, such as progressive profile completion, privacy and consent, and terms and conditions acceptance, rely on user metadata that tracks information related to a managed object state.

For example, this data might include when the object was created or the date of the most recent change. This metadata is not stored within the object itself but in a separate resource location.

In Identity Cloud, metadata is only tracked for managed/alpha_user and managed/bravo_user managed objects.

The metadata configuration includes the following properties:

You cannot search on metadata, and it is not returned by the results of a query, unless it is specifically requested. To return all metadata for an object, include _fields=,_meta/* in your request. The following example returns a user entry without requesting the metadata:

The following example returns the same user entry, with metadata:

The request also returns a _meta property that includes relationship information. IDM uses the relationship model to store the metadata. When the meta stanza is added to the user object definition, the attribute specified by the property ("property" : "_meta", in this case) is added to the schema as a uni-directional relationship to the resource collection specified by resourceCollection.

In this example, the user object’s _meta field is stored as an internal/usermeta object. The _meta/_ref property shows the full resource path to the internal object where the metadata for this user is stored.

In Identity Cloud user identities are sometimes referred to as managed users or user managed objects. There are alpha users and bravo users.

To retrieve, add, change, and delete managed users, use one of the following methods:

Relationships are references between managed objects. Roles and Organizations are implemented using relationships.

In the default IDM schema, several user properties are defined as relationships, for example, the manager relationship.

Relationships let you reference one managed object from another using the _ref* relationship properties. Three properties make up a relationship reference:

For example, imagine that you are creating a new user, psmith, and that psmith's manager is bjensen. You would add psmith's user entry, and reference bjensen's entry with the _ref property.

First, retrieve bjensen's UUID, displayed in the _id property value.

Next, add the new user psmith and specify bjensen as the manager using the _ref property. Make sure to use bjensen's UUID, for example, 1dff18dc-ac57-4388-8127-dff309f80002.

Note that relationship information is not returned by default. To show the relationship in psmith's entry, you must explicitly request their manager entry, as follows:

If a relationship changes, you can query the updated relationship state when any referenced managed objects are queried. So, after creating user psmith with manager bjensen, run a query on bjensen's user entry. The query shows a reference to psmith's entry in their reports property, which is configured as the reversePropertyName of the manager property.

The following query shows bjensen's direct reports including the new user entry, psmith:

Custom relationship properties allow you to define custom relationships between managed objects. For example, you could model a parent-child relationship by creating the custom_Parents and custom_Children properties and configuring them as one-way one-to-many relationships.

A relationship exists between two managed objects. By default, when a relationship changes for any create, update, or delete operation, the managed objects on either side of the relationship are not notified of that change. This means that the state of each object with respect to that relationship field is not recalculated until the object is read. This default behavior improves performance, especially cases where many objects are affected by a single relationship change.

For roles, change notification is set to TRUE by default. This default configuration lets managed users receive notifications when any relationships that link users, roles, and assignments are manipulated. For more information about relationship change notification, refer to Roles and relationship change notification.

Optionally, you can specify that a relationship between two objects must be validated when the relationship is created. For example, you can indicate that a user cannot reference a role if that role does not exist.

When you create a new relationship type, validation is disabled by default because it involves an expensive query to the relationship that is not always required.

To configure validation of a referenced relationship, set "validate":true in the managed object schema. The default schema enables validation for the following relationships:

Relationships between two managed objects come in two forms: forward and reverse. Forward relationships mean one side points to the other in a uni-directional flow. Reverse relationships means both sides point to the other in a bidirectional flow.

Most cases use reverse or bidirectional relationships for efficient querying of objects. For example, a relationship between a user and his manager might indicate a reverse relationship between the manager and her direct report. You may want to query jdoe's user entry to discover who his manager is, or query bjensen's user entry to discover all the users who report to bjensen.

You define a reverse relationship within a relationship definition. Consider the following sample excerpt of the default managed object configuration:

The reports property is a relationship type between users and managers, so you can refer to a managed user’s reports by referencing the reports object. However, the reports property is also a reverse relationship ("reverseRelationship":true), which means you can list all users that reference that report.

You can list all users whose manager property is set to the currently queried user.

The reverse relationship includes an optional resourceCollection that lets you query a set of objects, based on specific fields:

The path property of the resourceCollection points to the set of objects to be queried. If this path is not in the local repository, the link expansion can incur a significant performance cost. Although the resourceCollection is optional, the same performance cost is incurred if the property is absent.

The query property indicates how you will query this resource collection to configure the relationship. In this case, "queryFilter":true indicates that you can search on any of the properties listed in the fields array when you are assigning a manager to a user or a new report to a manager.

Relationships can be granted dynamically, based on a specified condition. In order to conditionally grant a relationship, the schemas for the resources you are creating a relationship between need to be configured to support conditional association. To do this, three fields in the schema are used:

Conditions support both properties and virtual properties derived from other relationships, if the query property has been configured. Conditions are a powerful tool for dynamically creating relationships between two objects. An example of conditional relationships in use is covered in Grant a Role Based on a Condition.

By default, information about relationships is not returned as the result of a GET request on a managed object. You must explicitly include the relationship property in the request. For example, if you request a user’s manager entry, the manager's _ref property returns the UUID (managed/alpha_user/1dff18dc-ac57-4388-8127-dff309f80002) of the manager, bjensen.

To obtain more information about the referenced object (psmith's manager, in this case), you can include additional fields from the referenced object in the query, using the syntax object/property (for a simple string value) or object/*/property (for an array of values).

The following example returns the email address and contact number for psmith's manager:

To query all the relationships associated with a managed object, query the reference (*_ref) property of that object. The following example shows all the objects referenced by psmith's entry:

To expand that query to show all fields within each relationship, add a wildcard (*) as follows:

Roles define privileges for user and device identities. Roles let you automatically assign and update privileges in numerous identity profiles. For further information about roles and assignments, refer to Roles and assignments.

The role object is a managed object type that uses the relationships mechanism to link the role to the managed object to which it applies.

Managed roles are intended to be collections of assignments for easier provisioning.

Managed roles are defined like any other managed object, and are granted to users through the relationships mechanism. A managed role can be granted manually, as a static value of the user’s roles attribute, or dynamically, as a result of a condition or script. For example, a user might be granted a role such as asia-sales-role dynamically, if a user in the sales organization is located in Asia region.

A user’s roles attribute takes an array of references as a value, where the references point to the managed roles. For example, if user bjensen has been granted two roles (employee and supervisor), the value of bjensen’s roles attribute would look something like the following:

The _refResourceCollection container holds each role. The _refResourceId is the ID of the role. The _ref property is a resource path that is derived from the _refResourceCollection and the URL-encoded _refResourceId. _refProperties provides more information about the relationship.

These sections show how to create, read, update, and delete managed roles, and to grant roles to users. For information about using roles to provision users to external systems, refer to Use assignments to provision users.

Temporal constraints restrict the period that a role is effective. You can apply temporal constraints to managed and internal roles, and to role grants (for individual users).

For example, you may want a role, contractors-2020, to apply to all contract employees for the year 2020. In this case, you would set the temporal constraint on the role. Alternatively, you may want to assign a contractors role that applies to an individual user only for the period of their contract of employment.

The following examples show how to set temporal constraints on role definitions, and on individual role grants.

Authorization roles control access to IDM itself. Provisioning roles define the rules for how attribute values update on external systems.

You configure these rules using assignments that are attached to a provisioning role definition or directly assigned to a user. Assignments provision an attribute or set of attributes based on an object’s role membership or through a direct assignment. After you configure a synchronization mapping configuration between two resources to provide the basic account provisioning logic (how an account is mapped from a source to a target system), then you can use role assignments to add more logic. The attributes and values that are updated by using assignments might include membership in external groups, access to specific external resources, and so on. A set of assignments can collectively represent a role.

Assignment objects are created, updated, and deleted like any other managed object, and are attached to a role by using the relationships mechanism, in much the same way as a role is granted to a user. Assignments are stored in the repository and are accessible at the context path /openidm/managed/realm-name_assignment.

This section describes how to manage assignments over the REST interface, and by using the Identity Cloud admin UI.

When you create an assignment, and if desired, attach it to a role definition, all user objects that reference that role definition will, as a result, reference the corresponding assignment in their effectiveAssignments attribute.

Effective roles and effective assignments are virtual properties of a user object. IDM uses the relationships between objects to know when to recalculate the values of these properties.

The relationships between objects are configured using the notify, notifySelf, and notifyRelationships settings for managed/realm-name_user, managed/realm-name_role, and managed/realm-name_assignment. The queryConfig property is used to configure which related objects to traverse for this calculation.

Calculation or recalculation is performed when IDM notifies the related objects that the roles or assignments for a managed user have been added, removed, or changed.

The following excerpt of the IDM managed object schema shows how these two virtual properties are constructed for each managed user object:

When a user references a role which references an assignment, that user automatically references the assignment in its list of effective assignments.

effectiveRoles uses the roles relationship to calculate the grants currently in effect, including any qualified by temporal constraints.

effectiveAssignments uses the roles relationship and the assignments relationship for each role to calculate the current assignments in effect for that user. The synchronization engine reads the calculated value of the effectiveAssignments attribute when it processes the user. The target system is updated according to the configured assignmentOperation for each assignment.

When a user’s roles or assignments are updated, IDM calculates their effectiveRoles and effectiveAssignments based on the current value of their roles property and the assignments property of any roles referenced by that property. The previous set of examples showed the creation of a role employee that referenced an assignment employee and was granted to user bjensen. Querying that user entry would show the following effective roles and effective assignments:

In this example, synchronizing the managed/realm-name_user repository with the external LDAP system defined in the mapping populates user bjensen’s employeeType attribute in LDAP with the value employee.

Before you read this section, see Configure relationship change notification to understand the notify and notifyRelationships properties, and how change notification works for relationships in general. In the case of roles, the change notification configuration exists to ensure that managed users are notified when any of the relationships that link users, roles, and assignments are manipulated (that is, created, updated, or deleted).

Consider the situation where a user has role R. A new assignment A is created that references role R. Ultimately, we want to notify all users that have role R so that their reconciliation state will reflect any attributes in the new assignment A. We achieve this notification with the following configuration:

In the managed object schema, the assignment object definition has a roles property that includes a resourceCollection. The path of this resource collection is managed/realm-name_role and "notify" : true for the resource collection:

With this configuration, when assignment A is created, with a reference to role R, role R is notified of the change. However, we still need to propagate that notification to any users who are members of role R. To do this, we configure the role object as follows:

When role R is notified of the creation of a new relationship to assignment A, the notification is propagated through the assignments property. Because "notifyRelationships" : ["members"] is set on the assignments property, the notification is propagated across role R to all members of role R.

A user’s access to Identity Cloud is based on one or more authorization roles. Authorization roles are cumulative, and are calculated for a user in the following order:

Groups are an important tool for identity management because they simplify managing collections of users by applying permissions and authorizations to all members of a group rather than to individual users. Groups may follow an organization structure or be based on the needs and privileges of an arbitrary set of users.

The managed group object is a default managed object type and is defined like any other managed object type. Managed groups simplify management by using common groups across the entire platform.

Users are made members of groups through the relationships mechanism. You should understand how relationships work before you read about IDM groups.

A group can be assigned to a user manually, as a static value of the user’s groups attribute, or dynamically, as a result of a condition or script. For example, a user might be assigned to a group such as sales dynamically, if that user is in the sales organization.

A user’s groups attribute takes an array of references as a value, where the references point to the managed groups. For example, if user bjensen has been assigned to two groups (employees and supervisors), the value of bjensen’s groups attribute would look something like the following:

The _refResourceCollection is the container that holds the group. The _refResourceId is the ID of the group. The _ref property is a resource path derived from the _refResourceCollection and the URL-encoded _refResourceId. _refProperties provides more information about the relationship.

You can manage groups over REST or by using the Identity Cloud admin UI.

You can perform the following actions with groups:

Organization objects let you arrange and manage users in hierarchical trees. Organizations also allow you to give users fine-grained administrative privileges to various parts of the tree based on their location in that tree. For example, an administrator of one organization might have full access to the users within that organization but no access to the users in an adjacent organization.

IDM comes with two types of managed objects for organizations: Alpha realm organizations and Bravo realm organizations. The default schemas for these two organization types are similar, except that Alpha realm organizations have relationships with Alpha realm users, while Bravo realm organizations have relationships with Bravo realm users. You can modify the default schemas of either of these managed object types; refer to Define managed object schema for more information.

The Alpha and Bravo organization object types have array attributes called admins, owners, and members. These attribute enable the hierarchical organization model.

Users and organizations have a set of relationship-derived virtual properties used by the delegated administration filters to provide the visibility and access constraints that underpin the organization model. Users have the ids of all the organizations of which they are members, and organizations have the ids of all their admin and owner users.

Only IDM administrative users can create top-level organizations. Within organizations, there are various levels of privileges, depending on how a user is related to the organization.

Refer to the organization use case for an example that illustrates organization concepts, including:

IDM provides RESTful access to managed organizations, at the context path /openidm/managed/realm-name_organization. You can add, change, and delete organizations by using the IDM admin UI or over the REST interface. To use the IDM admin UI, select Manage > Organization.

The examples on this page show how to add, query, modify, and delete organizations over the REST interface. For a reference of all managed organization endpoints and actions, refer to Managed organizations.

The relationship-derived virtual properties that support the organization model are calculated in response to relationship signals that travel down the organization tree hierarchy. For example, suppose you:

The relationship signals that trigger relationship-derived virtual property calculation are propagated down to all organizations in the organization hierarchy, and to all the members of the organizations in the hierarchy. This updates their relationship-derived virtual property state.

If there are many thousands of members of the organizations in the hierarchy, such an operation can take a long time to complete. Because of this, it is a best practice to grow organization hierarchies downward, adding new organizations as leaves of an existing hierarchy, and adding new admins and members to the leaves in the hierarchy tree. This is preferable to growing the hierarchy upwards, starting with the leaves, and then growing the hierarchy up towards the root organization.

If you must add a new root to an existing organization hierarchy with many organizations and many members, or add a new admin or owner to an organization near the top of the hierarchy, perform the operations over the command line, using the examples in Manage organizations over REST.

Identity Cloud provides a policy service that lets you apply specific validation requirements to various components and properties.

The policy service provides a REST interface for reading policy requirements and validating the properties of components against configured policies. Objects and properties are validated automatically when they are created, updated, or patched. Policies are generally applied to user passwords, but can also be applied to any managed or system object, and to internal user objects.

The policy service lets you accomplish the following tasks:

The router service limits policy validation to managed and internal user objects. To apply policies to additional objects, such as the audit service, modify your project’s router configuration. For more information about the router service, refer to Script triggers defined in the router configuration.

A configurable default policy applies to all managed objects.

In Identity Cloud, policies can be applied to managed objects using default policies.

You can add a policy using:

The policy configuration determines which policies apply to resources other than managed objects. The default policy configuration includes policies that are applied to internal user objects, but you can extend the configuration to apply policies to system objects.

Manage policies over REST through the policy configuration.

Identity Cloud gives you the ability to access various data objects such as:

You can perform various actions on these objects. Identity Cloud standardizes the objects through a uniform programming model. A uniform programming model means that all objects are queried and manipulated using the Resource API. The URL or URI that is used to identify the target object for an operation depends on the object type.

The various subsections explore the following:

IDM gives you the ability to access various data objects (such as managed objects, configuration objects, repository objects and so on) and perform actions (functions) through inline scripts. Identity Cloud standardizes the objects through a uniform programming model.

For more information about scripts and the objects available to scripts, refer to Scripting.

You can use the Resource API to obtain managed, system, configuration, and repository objects, as follows:

For information about constructing an object ID, refer to URI Scheme.

For information on all the actions you can take on a resource, refer to scripting functions.

IDM provides access to data objects through the ForgeRock REST API. To access objects over REST, you can use a browser-based REST client, such as the Simple REST Client for Chrome or RESTClient for Firefox. Alternatively, you can use the curl command-line utility.

Refer to the REST API for a comprehensive overview.

To obtain a managed object through the REST API, perform an HTTP GET on the corresponding URL; for example:

By default, the HTTP GET returns a JSON representation of the object.

In general, you can map any HTTP request to the corresponding openidm.method call. For more information, refer to script functions.

The following example shows how the parameters provided in an openidm.query request correspond with the key-value pairs you would include in a similar HTTP GET request. It shows the same call using the Resource API and the REST API:

You can proxy REST requests to another Identity Cloud tenant or IDM instance using the /external/idm/instanceName endpoint via the IDM remote proxy. This lets you treat any other tenant/IDM instance as a resource within the one you are managing.

The remote proxy acts as a REST client to the tenant/IDM instance; therefore, typical configurations for a remote proxy to operate (DNS resolution, network connectivity, SSL, and so on) are required.

Once you set up and configure the remote proxy, you can then:

You can call any endpoint in the remote tenant/IDM instance using this proxy.

A few situations where this feature may be useful include:

The proxy does not support liveSync/implicit sync from the remote Identity Cloud resources. This means you are limited to using reconciliation when it comes to pulling data from a remote system.

You can define and call queries using the REST or Resource API. Queries are supported on both managed and system objects, and you can define them through:

You can customize a variety of objects that can be addressed via a URL or URI. IDM can perform a common set of functions on these objects, such as CRUDPAQ (create, read, update, delete, patch, action, and query).

Depending on how you intend to use them, different object types are appropriate.

Managed objects and their properties are defined in the IDM managed object schema.

The default schema includes these types of managed objects:

Each managed object type contains properties for storing information about objects of that type. For example, the user object type has properties for storing usernames, passwords, email addresses, and so forth.

In the IDM admin UI, managed objects represent the identity-related data managed by IDM. In IDM, managed objects are stored in a DS repository.