chap-managed-objects.xml revision c8d7e1b85314740c293b6bc0b74b78091e93a7ef
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang ! CCPL HEADER START
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang ! This work is licensed under the Creative Commons
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang ! To view a copy of this license, visit
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang ! http://creativecommons.org/licenses/by-nc-nd/3.0/
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang ! or send a letter to Creative Commons, 444 Castro Street,
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang ! Suite 900, Mountain View, California, 94041, USA.
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang ! You can also obtain a copy of the license at
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang ! See the License for the specific language governing permissions
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang ! and limitations under the License.
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang ! If applicable, add the following below this CCPL HEADER, with the fields
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang ! enclosed by brackets "[]" replaced with your own identifying information:
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang ! Portions Copyright [yyyy] [name of copyright owner]
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang ! CCPL HEADER END
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang ! Copyright 2011 ForgeRock AS
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang xmlns:xinclude='http://www.w3.org/2001/XInclude'>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>A managed object in OpenIDM is an object which represents the identity-related data managed by OpenIDM. Managed objects are stored by OpenIDM in its data store. All managed objects are JSON-based data structures.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>Managed objects have an associated schema to enforce a specific data structure. Schema is specified using the JSON Schema specification. This is currently an Internet Draft, with implementations in multiple programming languages. As this specification evolves, OpenIDM's implementation will evolve in parallel.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>Top-level properties in a managed object that begins with an underscore _ are reserved by OpenIDM for internal use, and are not an explicitly part of its schema. Internal properties are read-only, and are ignored when provided by the REST API client.The following properties exist for all managed objects in OpenIDM:</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <variablelist>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <varlistentry>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>The unique identifier for the object. This value forms a part of the managed object's URI.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang </varlistentry>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <varlistentry>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>The revision of the object. This is the same value that is exposed as the object's ETag via the REST API. The content of this attribute is not defined. No consumer should make any assumptions of its content beyond equivalence comparison. This attribute may be provided by the underlying data store.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang </varlistentry>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <varlistentry>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>The a reference to the schema object that the managed object is associated with.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang </varlistentry>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <varlistentry>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>The revision of the schema that was used for validation when the object was last stored.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang </varlistentry>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang </variablelist>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>Schema validation is performed unequivocally whenever an object is stored, and conditionally whenever an object is retrieved from the data store and exhibits a _schema_rev value that differs from the _rev of the schema that the OpenIDM instance currently has for that managed object type. Whenever a schema validation is performed, the _schema_rev of the object is updated to contain the _rev value of the current schema.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>PB: While the _schema_rev optimization above reduces schema validation overhead for object retrieval, there's still the issue of object and property validation triggers. One way to solve this could be to qualify these as schema validation and bake them into the computed ETag for the schema. I kinda like this solution, but should be discussed.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>Properties can be defined to be strictly derived from other properties within the object. This allows computed and composite values to be created in the object. Whenever an object undergoes a change, all derived properties are recomputed. The value of derived properties are stored in the data store, and are not recomputed upon retrieval.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>PB: Mechanism for defining a derived property will likely be through a JavaScript trigger.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>Single-object operations shall be consistent within the scope of the operation performed, limited by capabilities of the underlying data store. Bulk operations shall not have any consistency guarantees. There are no plans to expose any transactional semantics in the managed object access API.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>All access through the REST API uses the ETag and associated conditional headers: If-Match, If-None-Match. In operations that modify model objects, conditional headers are mandatory.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>Triggers are user-definable functions that validate and/or modify object or property state.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>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 and/or modify objects before the action is performed. The object being operated on is in scope for each trigger, meaning that it the object is retrieved by the data store before the trigger is fired.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>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.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>PB: Status codes and internationalization considerations are still TBD.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>Called upon a request to create a new object. Throwing an exception causes the create to fail.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>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.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>Called upon a request to store an object. The "old" and "new" objects are in-scope for the trigger. The "old" object represents a complete object as retrieved from the data store. The trigger can elect to change "new" object properties. If as a result of the trigger the object's "old" and "new" values are identical (i.e. update is reverted), the update ends prematurely, though successfully. Throwing an exception causes the update to fail.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>Called upon a request to delete an object. Throwing an exception causes the deletion to fail.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>An object-scoped trigger applies to an entire object. Unless otherwise specified, the object itself is in scope for the trigger.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>Validates an object after its retrieval and prior to its storage into the data store. Throws an exception in the event of a validation failure. i18n TBD.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>Called when an object is retrieved from the data store. Typically used to transform an object after it has been retrieved (e.g. decryption, JIT data conversion).</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>Called just prior to when an object is stored into the data store. Typically used to transform an object just prior to its storage (e.g. encryption).</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>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.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>Validates a given property value after its retrieval from and prior to its storage into the data store. Throws an exception in the event of a validation failure. i18n of validation error TBD.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>Called after an object is retrieved from the data store. Typically used to transforms a given property after its object's retrieval. </para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>Called prior to when an object is stored into the data store.Typically used to transform a given property prior to its object's storage.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>The triggers are executed in the following orders.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <orderedlist>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>retrieve the raw object from the data store</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>per-property within the object (order undefined):</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>perform schema validation if _schema_rev doesn't match (see schema validation section above)</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>call object validate trigger ← PB: overhead we may be able to avoid; see note in schema validation section</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>per-property within the object (order undefined):</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>call property validate trigger ← PB: overhead we may be able to avoid; see note in schema validation section</para>
c51b5677113ce7260c44afb3c5932eea6c875e27Heng Jiang </orderedlist>
c51b5677113ce7260c44afb3c5932eea6c875e27Heng Jiang <orderedlist>
c51b5677113ce7260c44afb3c5932eea6c875e27Heng Jiang <para>per-property within the object (order undefined):</para>
c51b5677113ce7260c44afb3c5932eea6c875e27Heng Jiang <para>perform schema validation (see schema validation section above)</para>
c51b5677113ce7260c44afb3c5932eea6c875e27Heng Jiang <para>per-property trigger within the object (order undefined):</para>
c51b5677113ce7260c44afb3c5932eea6c875e27Heng Jiang <para>store the object with any resulting changes to the data store</para>
c51b5677113ce7260c44afb3c5932eea6c875e27Heng Jiang </orderedlist>
c51b5677113ce7260c44afb3c5932eea6c875e27Heng Jiang <para>Sensitive object properties can be encrypted prior to storage, typically through the property onStorage trigger. The trigger will have access to configuration data, which can include arbitrary customer-defined attributes, such as symmetric encryption key. Such attributes can be decrypted during retrieval from the data store through the property onRetrieval trigger.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>Configuration of managed objects is provided through an array of :</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang "objects": [ managed-object-config object, … ]
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang}</programlisting>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <variablelist>
c51b5677113ce7260c44afb3c5932eea6c875e27Heng Jiang <varlistentry>
b3c65285705f6d184b5f8b00b1a328d96b6b19c5Heng Jiang <para>array of managed-object-config objects, required</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>Specifies the objects that the managed object service manages.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang </varlistentry>
b3c65285705f6d184b5f8b00b1a328d96b6b19c5Heng Jiang </variablelist>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>Specifies the configuration of each managed object.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang "name": string,
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang "schema": json-schema object,
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang "onCreate": script object,
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang "onRead": script object,
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang "onUpdate": script object,
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang "onDelete": script object,
b3c65285705f6d184b5f8b00b1a328d96b6b19c5Heng Jiang "onValidate": script object,
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang "onRetrieve": script object,
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang "onStore": script object,
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang "properties": [ property-configuration object, … ]
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang}</programlisting>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <variablelist>
b3c65285705f6d184b5f8b00b1a328d96b6b19c5Heng Jiang <varlistentry>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>The name of the managed object. Used to identify the managed object in URIs and identifiers. </para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang </varlistentry>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <varlistentry>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>The schema to use to validate the structure and content of the managed object. The schema-object format is specified by the JSON Schema specification.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang </varlistentry>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <varlistentry>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>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 may change the object. If an exception is thrown, the create will abort with an exception.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang </varlistentry>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <varlistentry>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>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 may change the object. If an exception is thrown, the read will abort with an exception.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang </varlistentry>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <varlistentry>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <para>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 a newObject property. The script may change the newObject. If an exception is thrown, the update will abort with an exception.</para>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang </varlistentry>
95242ab07e9aa13b37c16cac36a75d190e1766e4Heng Jiang <varlistentry>
<para>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 will abort with an exception.</para>
<para>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 will fail.</para>
<para>A script object to trigger once an object is retrieved from the repository. The object that was retrieved is provided in the root scope as an object property. The script may change the object. If an exception is thrown, then object retrieval will fail.</para>
<para>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 may change the object. If an exception is thrown, then object storage will fail.</para>
<para>Specifies the type of script to be executed. Presently, only "text/javascript" is supported.</para>
<para>A script object to trigger when the property requires validation. The property to be validated is provided in the root scope as the property property. If an exception is thrown, the validation will fail.</para>
<para>A script object to trigger once a property is retrieved from the repository. The property that was retrieved is provided in the root scope as the property property. The script may change the property value. If an exception is thrown, then object retrieval will fail.</para>
<para>A script object to trigger when a property is about to be stored in the repository. The property to be stored is provided in the root scope as the property property. The script may change the property value. If an exception is thrown, then object storage will fail.</para>
<para>Specifies the configuration for encryption of the property in the repository. If omitted or null, the property is not encrypted.</para>
<para>The cipher transformation used to encrypt the property. If omitted or null, the default cipher of "AES/CBC/PKCS5Padding" is used.</para>