Managed objects
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.
Data consistency
Single-object operations are consistent within the scope of the operation performed, limited by the capabilities of the underlying data store. Bulk operations have no consistency guarantees. Identity Cloud does not expose any transactional semantics in the managed object access API.
For information on conditional header access through the REST API, see Conditional Operations.
Managed object triggers
Triggers are user-definable functions that validate or modify object or property state.
State triggers
Managed objects are resource-oriented. A set of triggers is defined to intercept the supported request methods on managed objects. Such triggers are intended to perform authorization, redact, or modify objects before the action is performed. The object being operated on is in scope for each trigger, meaning that the object is retrieved by the data store before the trigger is fired.
If retrieval of the object fails, the failure occurs before any trigger is called. Triggers are executed before any optimistic concurrency mechanisms are invoked. The reason for this is to prevent a potential attacker from getting information about an object (including its presence in the data store) before authorization is applied.
- onCreate
-
Called upon a request to create a new object. Throwing an exception causes the create to fail.
- postCreate
-
Called after the creation of a new object is complete.
- onRead
-
Called upon a request to retrieve a whole object or portion of an object. Throwing an exception causes the object to not be included in the result. This method is also called when lists of objects are retrieved via requests to its container object; in this case, only the requested properties are included in the object. Allows for uniform access control for retrieval of objects, regardless of the method in which they were requested.
- onUpdate
-
Called upon a request to store an object. The
oldObject
andnewObject
variables are in-scope for the trigger. TheoldObject
represents a complete object, as retrieved from the data store. The trigger can elect to changenewObject
properties. If, as a result of the trigger, the values of theoldObject
andnewObject
are identical (that is, update is reverted), the update ends prematurely, but successfully. Throwing an exception causes the update to fail. - postUpdate
-
Called after an update request is complete.
- onDelete
-
Called upon a request to delete an object. Throwing an exception causes the deletion to fail.
- postDelete
-
Called after an object is deleted.
- onSync
-
Called when a managed object is changed, and the change triggers an implicit synchronization operation. The implicit synchronization operation is triggered by calling the sync service, which attempts to go through all the configured managed-system mappings. The sync service returns either a response or an error. For both the response and the error, the script that is referenced by the
onSync
hook is called.You can use this hook to inject business logic when the sync service either fails or succeeds to synchronize all applicable mappings. For an example of how the
onSync
hook is used to revert partial successful synchronization operations, see Synchronization Failure Compensation.
Object storage triggers
An object-scoped trigger applies to an entire object. Unless otherwise specified, the object itself is in scope for the trigger.
- onValidate
-
Validates an object prior to its storage in the data store. If an exception is thrown, the validation fails and the object is not stored.
- onStore
-
Called just prior to when an object is stored in the data store. Typically used to transform an object just prior to its storage (for example, encryption).
Property storage triggers
A property-scoped trigger applies to a specific property within an object. Only the property itself is in scope for the trigger. No other properties in the object should be accessed during execution of the trigger. Unless otherwise specified, the order of execution of property-scoped triggers is intentionally left undefined.
- onValidate
-
Validates a given property value after its retrieval from and prior to its storage in the data store. If an exception is thrown, the validation fails and the property is not stored.
- onRetrieve
-
Called on all requests that return a single object: read, create, update, patch, and delete.
onRetrieve
is called on queries only ifexecuteOnRetrieve
is set totrue
in the query request parameters. IfexecuteOnRetrieve
is not passed, or if it isfalse
, the query returns previously persisted values of the requested fields. This behavior avoids performance problems when executing the script on all results of a query. - onStore
-
Called before an object is stored in the data store. Typically used to transform a given property before its object is stored.
Storage Trigger Sequences
Triggers are executed in the following order:
- Object Retrieval Sequence
-
-
Retrieve the raw object from the data store
-
The
executeOnRetrieve
boolean is used to check whether property values should be recalculated. The sequence continues if the boolean is set totrue
. -
Call object
onRetrieve
trigger -
Per-property within the object, call property
onRetrieve
trigger
-
- Object Storage Sequence
-
-
Per-property within the object:
-
Call property
onValidate
trigger -
Call object
onValidate
trigger
-
-
Per-property trigger within the object:
-
Call property
onStore
trigger -
Call object
onStore
trigger -
Store the object with any resulting changes to the data store
-
-
Managed Object Encryption
Sensitive object properties can be encrypted prior to storage, typically through the property onStore
trigger. The trigger has access to configuration data, which can include arbitrary attributes that you define, such as a symmetric encryption key. Such attributes can be decrypted during retrieval from the data store through the property onRetrieve
trigger.
Managed Object Configuration
Configuration of managed objects is provided through an array of managed object configuration objects.
{
"objects": [ managed-object-config object, ... ]
}
- objects
-
array of managed-object-config objects, required
Specifies the objects that the managed object service manages.
Managed-Object-Config Object Properties
Specifies the configuration of each managed object.
{
"name" : string,
"actions" : script object,
"onCreate" : script object,
"onDelete" : script object,
"onRead" : script object,
"onRetrieve": script object,
"onStore" : script object,
"onSync" : script object,
"onUpdate" : script object,
"onValidate": script object,
"postCreate": script object,
"postDelete": script object,
"postUpdate": script object,
"schema" : {
"id" : urn,
"icon" : string,
"mat-icon" : string,
"order" : [ list of properties],
"properties": { property-configuration objects },
"$schema" : "http://json-schema.org/draft-03/schema",
"title" : "User",
"viewable" : true
}
}
- name
-
string, required
The name of the managed object. Used to identify the managed object in URIs and identifiers.
- actions
-
script object, optional
A custom script that initiates an action on the managed object. For more information, see Register custom scripted actions.
- onCreate
-
script object, optional
A script object to trigger when the creation of an object is being requested. The object to be created is provided in the root scope as an
object
property. The script can change the object. If an exception is thrown, the create aborts with an exception. - onDelete
-
script object, optional
A script object to trigger when the deletion of an object is being requested. The object being deleted is provided in the root scope as an
object
property. If an exception is thrown, the deletion aborts with an exception. - onRead
-
script object, optional
A script object to trigger when the read of an object is being requested. The object being read is provided in the root scope as an
object
property. The script can change the object. If an exception is thrown, the read aborts with an exception. - onRetrieve
-
script object, optional
A script object to trigger when an object is retrieved from the repository. The object that was retrieved is provided in the root scope as an
object
property. The script can change the object. If an exception is thrown, then object retrieval fails. - onStore
-
script object, optional
A script object to trigger when an object is about to be stored in the repository. The object to be stored is provided in the root scope as an
object
property. The script can change the object. If an exception is thrown, then object storage fails. - onSync
-
script object, optional
A script object to trigger when a change to a managed object triggers an implicit synchronization operation. The script has access to the
syncResults
object, therequest
object, the state of the object before the change (oldObject
) and the state of the object after the change (newObject
). The script can change the object. - onUpdate
-
script object, optional
A script object to trigger when an update to an object is requested. The old value of the object being updated is provided in the root scope as an
oldObject
property. The new value of the object being updated is provided in the root scope as anewObject
property. The script can change thenewObject
. If an exception is thrown, the update aborts with an exception. - onValidate
-
script object, optional
A script object to trigger when the object requires validation. The object to be validated is provided in the root scope as an
object
property. If an exception is thrown, the validation fails. - postCreate
-
script object, optional
A script object to trigger after an object is created, but before any targets are synchronized.
- postDelete
-
script object, optional
A script object to trigger after a delete of an object is complete, but before any further synchronization. The value of the deleted object is provided in the root scope as an
oldObject
property. - postUpdate
-
script object, optional
A script object to trigger after an update to an object is complete, but before any targets are synchronized. The value of the object before the update is provided in the root scope as an
oldObject
property. The value of the object after the update is provided in the root scope as anewObject
property. - schema
-
json-schema object, optional
The schema to use to validate the structure and content of the managed object, and how the object is displayed in the UI. The schema-object format is defined by the JSON Schema specification.
The
schema
property includes the following additional elements:- icon
-
string, optional
The name of the Font Awesome icon to display for this object in the UI. Only applies to standalone Identity Cloud.
- mat-icon
-
string, optional
The name of the Material Design Icon to display for this object in the UI. Only applies to Identity Cloud as part of the ForgeRock Identity Platform.
- id
-
urn, optional
The URN of the managed object, for example,
urn:jsonschema:org:forgerock:openidm:managed:api:Role
. - order
-
list of properties, optional
The order in which properties of this managed object are displayed in the UI.
- properties
-
list of property configuration objects, optional
A list of property specifications. For more information, see Property Configuration Properties.
- $schema
-
url, optional
Link to the JSON schema specification.
- title
-
string, optional
The title of this managed object in the UI.
- viewable
-
boolean, optional
Whether this object is visible in the UI.
Property Configuration Properties
Each managed object property, identified by its property-name
, can have the following configurable properties:
"property-name" : {
"description" : string,
"encryption" : property-encryption object,
"isPersonal" : boolean true/false,
"isProtected" : boolean true/false,
"isVirtual" : boolean true/false,
"items" : {
"id" : urn,
"properties" : property-config object,
"resourceCollection" : property-config object,
"reversePropertyName" : string,
"reverseRelationship" : boolean true/false,
"title" : string,
"type" : string,
"validate" : boolean true/false,
},
"onRetrieve" : script object,
"onStore" : script object,
"onValidate" : script object,
"pattern" : string,
"policies" : policy object,
"required" : boolean true/false,
"returnByDefault" : boolean true/false,
"scope" : string,
"searchable" : boolean true/false,
"secureHash" : property-hash object,
"title" : string,
"type" : data type,
"usageDescription": string,
"userEditable" : boolean true/false,
"viewable" : boolean true/false,
}
- description
-
string, optional
A brief description of the property.
- encryption
-
property-encryption object, optional
Specifies the configuration for encryption of the property in the repository. If omitted or null, the property is not encrypted.
- isPersonal
-
boolean, true/false
Designed to highlight personally identifying information. By default,
isPersonal
is set totrue
foruserName
andpostalAddress
. - isProtected
-
boolean, true/false
Specifies whether reauthentication is required if the value of this property changes.
- isVirtual
-
boolean, true/false
Specifies whether the property takes a static value, or whether its value is calculated dynamically as the result of a script.
The most recently calculated value of a virtual property is persisted by default. The persistence of virtual property values allows Identity Cloud to compare the new value of the property against the last calculated value, and therefore to detect change events during synchronization.
Virtual property values are not persisted by default if you are using an explicit mapping.
- items
-
property-configuration object, optional
For
array
type properties, defines the elements in the array.items
can include the following sub-properties:- id
-
urn, optional
The URN of the property, for example,
urn:jsonschema:org:forgerock:openidm:managed:api:Role:members:items
. - properties
-
property configuration object, optional
A list of properties, and their configuration, that make up this items array. For example, for a relationship type property:
"properties" : { "_ref" : { "description" : "References a relationship from a managed object", "type" : "string" }, "_refProperties" : { "description" : "Supports metadata within the relationship", ... } }
- resourceCollection
-
property configuration object, optional
The collection of resources (objects) on which this relationship is based (for example,
managed/realm-name_user
objects). - reversePropertyName
-
string, optional
For
relationship
type properties, specifies the corresponding property name in the case of a reverse relationship. For example, aroles
property might have areversePropertyName
ofmembers
. - reverseRelationship
-
boolean, true or false.
For
relationship
type properties, specifies whether the relationship exists in both directions. - title
-
string, optional
The title of array items, as displayed in the UI, for example
Role Members Items
. - type
-
string, optional
The array type, for example
relationship
. - validate
-
boolean, true/false
For reverse relationships, specifies whether the relationship should be validated.
- onRetrieve
-
script object, optional
A script object to trigger once a property is retrieved from the repository. That property may be one of two related variables:
property
andpropertyName
. The property that was retrieved is provided in the root scope as thepropertyName
variable; its value is provided as theproperty
variable. If an exception is thrown, then object retrieval fails. - onStore
-
script object, optional
A script object to trigger when a property is about to be stored in the repository. That property may be one of two related variables:
property
andpropertyName
. The property that was retrieved is provided in the root scope as thepropertyName
variable; its value is provided as theproperty
variable. If an exception is thrown, then object storage fails. - onValidate
-
script object, optional
A script object to trigger when the property requires validation. The value of the property to be validated is provided in the root scope as the
property
property. If an exception is thrown, validation fails. - pattern
-
string, optional
Any specific pattern to which the value of the property must adhere. For example, a property whose value is a date might require a specific date format. Patterns specified here must follow regular expression syntax.
- policies
-
policy object, optional
Any policy validation that must be applied to the property.
- required
-
boolean, true/false
Specifies whether the property must be supplied when an object of this type is created.
- returnByDefault
-
boolean, true/false
For virtual properties, specifies whether the property will be returned in the results of a query on an object of this type if it is not explicitly requested. Virtual attributes are not returned by default.
- scope
-
string, optional
Specifies whether the property should be filtered from HTTP/external calls. The value can be either
"public"
or"private"
."private"
indicates that the property should be filtered,"public"
indicates no filtering. If no value is set, the property is assumed to be public and thus not filtered. - searchable
-
boolean, true/false
Specifies whether this property can be used in a search query on the managed object. A searchable property is visible in the End User UI. False by default.
Do not modify the searchable setting on properties in the Identity Cloud managed object schema. - secureHash
-
property-hash object, optional
Specifies the configuration for hashing of the property value in the repository. If omitted or null, the property is not hashed.
- title
-
string, required
A human-readable string, used to display the property in the UI.
- type
-
data type, required
The data type for the property value; can be String, Array, Boolean, Number, Object, or Resource Collection.
- usageDescription
-
string, optional
Designed to help end users understand the sensitivity of a property such as a telephone number.
- userEditable
-
boolean, true/false
Specifies whether users can edit the property value in the UI. This property applies in the context of the End User UI, in which users are able to edit certain properties of their own accounts. False by default.
- viewable
-
boolean, true/false
Specifies whether this property is viewable in the object’s profile in the UI. True by default.
Script Object Properties
{
"type" : "text/javascript",
"source": string
}
- type
-
string, required
Identity Cloud supports
"text/javascript"
. - source, file
-
string, required (only one, source or file is required)
Specifies the source code of the script to be executed (if the keyword is "source"), or a pointer to the file that contains the script (if the keyword is "file").
Property Encryption Object
{
"cipher": string,
"key" : string
}
- cipher
-
string, optional
The cipher transformation used to encrypt the property. If omitted or null, the default cipher of
"AES/CBC/PKCS5Padding"
is used. - key
-
string, required
The alias of the key in the Identity Cloud cryptography service keystore used to encrypt the property.
Accessing Managed Objects Through the REST API
Identity Cloud exposes all managed object functionality through the REST API unless you configure a policy to prevent such access. In addition to the common REST functionality of create, read, update, delete, patch, and query, the REST API also supports patch by query. For more information, see the REST API reference.