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

ForgeRock Identity Platform™ serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

The ForgeRock Common REST API works across the platform to provide common ways to access web resources and collections of resources.

These topics describe how to work with managed object types:

The Identity Cloud object model includes other object types besides managed objects. For more information, see Data models and objects reference.

Managed objects and their properties are defined in the default Identity Cloud 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 Identity Cloud managed object schema to meet your needs:

To store custom data for users, you do not extend the default Identity Cloud managed object schema. Instead, use one of the generic extension attributes provided in the default user object schema. For a list of generic extension attributes, see the tables here.

If the managed object types provided in the default configuration are not sufficient for your deployment, you can create new managed object types. The easiest way to create a new managed object type is to use the IDM admin UI, as follows:

You can also create a new managed object type by editing your managed object 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.

A property definition typically includes the following fields:

Properties can be derived from other properties within an object. This lets computed and composite values be created in the object. Such derived properties are named virtual properties. The value of a virtual property can be calculated in two ways:

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 created (onCreate), updated (onUpdate), retrieved (onRetrieve), deleted (onDelete), validated (onValidate), or stored in the repository (onStore). You can also trigger a script when a change to a managed object triggers an implicit synchronization operation (onSync).

Post-action scripts let you manipulate objects after they are created (postCreate), updated (postUpdate), and deleted (postDelete).

The following sample schema runs a script to check that a role has no members before attempting to delete the role:

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. Such data might include when the object was created, or the date of the most recent change, for example. This metadata is not stored within the object itself, but in a separate resource location.

Because object metadata is stored outside the managed object, state change situations (such as the time of an update) are separate from object changes (the update itself). This separation reduces unnecessary synchronization to targets when the only data that has changed is metadata. Metadata is not returned in a query unless it is specifically requested. Therefore, the volume of data that is retrieved when metadata is not required, is reduced.

To specify which metadata you want to track for an object, add a meta stanza to the object definition in your managed object configuration. The following default configuration tracks the createDate and lastChanged date for managed user objects:

The metadata configuration includes the following properties:

You cannot search on metadata and it is not returned in 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 their metadata:

The request also returns a _meta property that includes relationship information. Identity Cloud 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 the IDM admin UI, user identities are referred to as user managed objects, also known as managed users.

You can retrieve, add, change, and delete managed users:

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

In the default Identity Cloud 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 will be bjensen. You would add psmith’s user entry, and reference bjensen’s entry with the _ref property, as follows:

Note that relationship information is not returned by default. To show the relationship in psmith’s entry, you must explicitly request her 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, a query on bjensen’s user entry will show a reference to psmith’s entry in her reports property (because the reports property is configured as the reversePropertyName of the manager property). The following query shows the updated relationship state for bjensen:

Identity Cloud maintains referential integrity by deleting the relationship reference, if the object referred to by that relationship is deleted. In our example, if bjensen’s user entry is deleted, the corresponding reference in psmith’s manager property is removed.

A relationship exists between two managed objects. By default, when a relationship changes (when it is created, updated, or deleted), 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 in the case where many objects are affected by a single relationship change.

For roles, a special kind of relationship, change notification is configured by default. The purpose of this default configuration is to notify managed users when any of the relationships that link users, roles, and assignments are manipulated. For more information about relationship change notification in the specific case of managed roles, see Roles and relationship change notification.

To change the default configuration, or to set up notification for other relationship changes, use the notify* properties in the relationship definition, as described in this section.

A relationship exists between an origin object and a referenced object. These terms reflect which managed object is specified in the URL (for example managed/realm-name_user/psmith), and which object is referenced by the relationship (_ref*) properties. For more information about the relationship properties, see Create a relationship between two objects.

In the previous example, a PUT on managed/realm-name_user/psmith with "manager" : {_ref : "managed/realm-name_user/bjensen"}, causes managed/realm-name_user/psmith to be the origin object, and managed/realm-name_user/bjensen to be the referenced object for that relationship, as shown in the following illustration:

Note that for the reverse relationship (a PUT on managed/realm-name_user/bjensen with "reports" : [{_ref = "managed/realm-name_user/psmith"}]) managed/realm-name_user/bjensen would be the origin object, and managed/realm-name_user/psmith would be the referenced object.

By default, when a relationship changes, neither the origin object nor the referenced object is notified of the change. So, with the PUT on managed/realm-name_user/psmith with "manager" : {_ref : "managed/realm-name_user/bjensen"}, neither psmith’s object nor bjensen’s object is notified.

To configure relationship change notification, set the notify and notifySelf properties in your managed object schema. These properties specify whether objects that reference relationships are notified of a relationship change:

By default, roles, assignments, and members use relationship change notification to ensure that relationship changes are accurately provisioned.

For example, the default user object includes a roles property with notifySelf set to true:

In this case, notifySelf indicates the origin or user object. If any changes are made to a relationship referencing a role through a URL that includes a user, the user will be notified of the change. For example, if there is a CREATE on managed/realm-name_user/psmith/roles which specifies a set of references to existing roles, user psmith will be notified of the change.

Similarly, the role object includes a members property. That property includes the following schema definition:

Notice the "notify" : true setting on the resourceCollection. This setting indicates that if the relationship is created, updated, or deleted through a URL that references that role, all objects in that resource collection (in this case, managed/realm-name_user objects) that are identified as members of that role must be notified of the change.

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:

In most cases, relationships between two objects in the Identity Cloud schema are defined in both directions. For example, a relationship between a user and his manager might indicate a reverse relationship between the manager and her direct report. Reverse relationships are particularly useful for queries. You might 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.

A reverse relationship is part of the relationship definition. Consider the following sample excerpt of the default managed object configuration:

The reports property is a relationship between users and managers. So, you can refer to a managed user’s reports by referencing the reports. However, the reports property is also a reverse relationship ("reverseRelationship" : true) which means that 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:

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. For example, the following query shows all the objects that are referenced by psmith’s entry:

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

Which outputs the following:

The managed role object is a default managed object type that uses the relationships mechanism. You should understand how relationships work before you read about Identity Cloud roles.

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 sales-role dynamically, if that user is in the sales organization.

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 is the container that holds the 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 the REST calls 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, see 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 might 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 might 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 Identity Cloud itself. Provisioning roles define rules for how attribute values are updated on external systems. These rules are configured through assignments that are attached to a provisioning role definition. The purpose of an assignment is to provision an attribute or set of attributes, based on an object’s role membership.

The synchronization mapping configuration between two resources provides the basic account provisioning logic (how an account is mapped from a source to a target system). Role assignments provide additional provisioning logic that is not covered in the basic mapping configuration. 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 manipulate assignments over the REST interface, and by using the IDM admin UI. When you have created an assignment, and attached 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. Their values are calculated by Identity Cloud, using relationships between related objects to know when to recalculate when changes occur. 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. Which related objects to traverse for calculation is configured using queryConfig. Calculation or recalculation is triggered when the roles or assignments for a managed user are added, removed, or changed, including by changes from temporal constraints, and notification of that change is sent to the related objects.

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

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

effectiveRoles uses the roles relationship to calculate the grants that are 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, Identity Cloud calculates the effectiveRoles and effectiveAssignments for that user based on the current value of the user’s roles property, and the assignments property of any roles referenced by the roles 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.

Like any other managed object, you can use script hooks to configure role behavior. The default role configuration includes an onDelete hook that calls a script to prevent the role from being deleted if it is currently assigned to users:

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:

The managed group object is a default managed object type, and is defined like any other managed object type. Users are made members of groups through the relationships mechanism. You should understand how relationships work before you read about Identity Cloud 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 that is derived from the _refResourceCollection and the URL-encoded _refResourceId. _refProperties provides more information about the relationship.

These sections show the REST calls to create, read, update, and delete groups, and to assign groups to users.

Organization objects let you arrange and manage users in hierarchical trees. Organizations also let you 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.

An organization object (defined in the Identity Cloud managed object schema) has an array of admins, an array of owners, and an array of members. These relationship properties 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 Identity Cloud 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.

The following diagram gives a high-level overview of how privileges are assigned to various entities in the organization hierarchy:

Identity Cloud 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 following examples show how to add, change, and delete organizations over the REST interface. For a reference of all managed organization endpoints and actions, see Managed organizations.

The organization established by the previous set of examples can be represented as follows:

In this organization, both bjensen and scarter can create and delete sub-organizations, also known as child organizations, of example-org, and can create and delete members within these child organizations.

The following example shows how to add and delete child organizations over the REST interface:

The relationship-derived virtual properties that support the organization model are generally calculated in response to relationship signals that travel down the organization tree hierarchy. Imagine, for example, that a new root organization is added to an existing organization hierarchy (or that a new admin or owner is added to the root of an existing organization hierarchy). The relationship signals that trigger relationship-derived virtual property calculation are propagated down the organization hierarchy, and to all members of the organizations in this hierarchy. This, in turn, updates their relationship-derived virtual property state.

If there are many thousands of members of the organizations in the hierarchy, this operation can take a long time to complete. It is therefore best practice to grow an organization hierarchy downwards, adding new organizations as leaves to 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 growing the hierarchy up towards the root.

If you must add a new root to an existing organization hierarchy with many organizations and many members, or a new admin or owner to an organization near the top of the hierarchy, rather perform this request over the command-line, using the examples provided in the previous section.

Identity Cloud provides an extensible policy service that lets you apply specific validation requirements to various components and properties. This chapter describes the policy service, and provides instructions on configuring policies for managed objects.

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 application 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, see Script triggers defined in the router configuration.

A configurable default policy applies to all managed objects.

Policies applied to managed objects are configured in two places:

You can extend the policy service by adding policies that are applied only under certain conditions.

Manage the policy service over the REST interface at the openidm/policy endpoint.

Identity Cloud’s uniform programming model means that all objects are queried and manipulated in the same way, using the Resource API. The URL or URI that is used to identify the target object for an operation depends on the object type. For more information about scripts and the objects available to scripts, see Scripting.

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

For information about constructing an object ID, see URI Scheme.

You can update entire objects with the update() function, as follows:

You can apply a partial update to a managed or system object by using the patch() function:

The create(), delete(), and query() functions work the same way.

Identity Cloud provides RESTful access to data objects through the ForgeRock Common 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.

For a comprehensive overview of the REST API, see the REST API reference.

To obtain a managed object through the REST API, depending on your security settings and authentication configuration, perform an HTTP GET on the corresponding URL, for example https://tenant-name.forgeblocks.com/openidm/managed/realm-name_organization/mysampleorg.

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. The following example shows how the parameters provided in an openidm.query request correspond with the key-value pairs that you would include in a similar HTTP GET request:

Reading an object using the Resource API:

Reading an object using the REST API:

You can proxy REST requests to a remote IDM instance using the /external/idm/factoryPid endpoint. This lets you treat any other IDM instance as a resource within the one you are managing. You can then use it in a sync mapping, call actions on it, use it within scripts, or use it in any other way that you might use a resource in IDM. You can call any endpoint in the remote IDM system using this proxy.

A few situations where this feature may be useful include:

This feature does not support liveSync/implicit sync from the remote IDM resources. This means that you will be limited to using recon when it comes to pulling data from a remote system.

An advanced query model enables you to define queries and to call them over the REST or Resource API. The following types of queries are supported, on both managed, and system objects:

The bulk import facility lets you import large numbers of external entries over REST. You import entries from a comma-separated values (CSV) file, to a specified managed object type in the Identity Cloud repository. Bulk import works as follows:

To import bulk CSV entries into the repository, using the REST API, follow these steps:

For a list of all REST endpoints related to bulk import, see Bulk import.

You can customize a variety of objects that can be addressed via a URL or URI. Identity Cloud 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 Identity Cloud 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 Identity Cloud. In Identity Cloud, managed objects are stored in a DS repository.

System objects are pluggable representations of objects on external systems. They follow the same RESTful resource based design principles as managed objects. There is a default implementation for the ICF framework, which allows any connector object to be represented as a system object.

Link objects define relations between source objects and target objects, usually relations between managed objects and system objects. The link relationship is established by provisioning activity that either results in a new account on a target system, or a reconciliation or synchronization scenario that takes a LINK action.