Shadow Objects

Last modified 02 Oct 2025 14:18 +02:00

MidPoint works with two distinct concepts that represent objects on the resources, such as accounts, groups, permissions, etc. These concepts are resource objects and their connected resource object shadows.

  • Resource objects are real objects on the target resources. These are LDAP entries, lines in /etc/passwd files, database rows, etc. Access to resource objects is provided by provisioning frameworks such as identity connectors, OpenPTK, or others.

  • Resource object shadows are objects in an IDM repository. They are short pieces of XML that usually contain basic information about the related resource object and are just pointers to the real resource object. Resource object shadows may cache the information from their particular resource object to speed up information access. How much or how little information is cached in the resource object shadow is specified by system (resource) configuration. Resource object shadows are also called simply "shadows" or "shadow objects".

Type Stored in Identified by Schema Content

Resource object

Natively on the resource

Any identifier

Any schema

All resource object data

Resource object shadow

Local midPoint repository database

OID

Fixed midPoint schema

Common resource object data

Refer to Shadow to learn more about the concept of shadows.

How Object References Work in MidPoint

The figure below illustrates the way how references between user, shadows connected to the user, and the resource objects represented by the shadows work together.

The user (<user>) and account shadow (<account>) objects are midPoint objects stored in midPoint repository database. More precisely only the parts shown in black are stored in the repository, the parts in blue are fetched from the resource on demand.

schemas shadow

User and account shadow objects are linked. It means that the user is an owner of the specified account. User and all accounts owned by the user are synchronized using inbound and outbound mappings.

A change of a shadow results in a change of a resource object. In fact, shadows are little more than a projections of resource objects. Only the most important parts of a shadow are stored in midPoint repository. Usually, only the identifiers are stored and therefore the shadow acts as a "mapping" object between OID and native resource identifiers (e.g. LDAP DN, UUID, …​).

What Is the Structure of a Resource Object Shadow

Resource object shadows have a fixed schema. They are defined in midPoint common schema and are (indirect) subtypes of object. Therefore they are identified by OID, can be stored in the repository, the client code may use a name property as a human-readable name, etc. In short, they are usual identity objects in the midPoint system.

Resource object shadows have one additional extensibility point: the attributes element. This element is used to store attributes of the resource object that are not fixed to midPoint static schema. Attributes that are fetched from the resource may be stored in this element. These attributes can have different form and different meaning for each individual resource instance. The schema for the attributes element is not fixed, it is just an xsd:any wild card. However, midPoint expects that all the elements under the attributes tag are in the form of properties.

Resource Object Shadow Example

The following form of shadow object is provided by the provisioning service interface. It has most of the interesting attributes that were probably freshly fetched from the resource.

Shadow object when retrieved from provisioning
<account oid="12345">
  <name>bond</name>
  <objectClass>ds1:AccountObjectClass</objectClass>
  <attributes>
     <ds1:dn>uid=bond,o=mi5</ds1:dn>
     <ds1:uid>bond</ds1:uid>
     <ds1:cn>James Bond</ds1:cn>
     <ds1:sn>Bond</ds1:sn>
     <ds1:givenName>James</ds1:givenName>
  </attributes>
  <resourceRef oid="333"/>
</account>

The following form of shadow object will be stored in the repository. It contains only the very basic information, usually only the identifiers. It may contain cached data as well, but that is not mandatory.

Shadow object as stored in the repository
<account oid="12345">
  <name>bond</name>
  <objectClass>ds1:AccountObjectClass</objectClass>
  <attributes>
     <ds1:dn>uid=bond,o=mi5</ds1:dn>
  </attributes>
  <resourceRef oid="333"/>
</account>

Default namespace in both examples points to the midPoint common schema. The ds1 prefix is bound to the resource schema namespace, schema specific to the resource instance. See the Resource Schema page for more details.

Resource Object

Resource objects are native objects on the resource represented as XML. They have no fixed structure, except that they should be constructed from properties. They are quite formless because we cannot predict all the possible objects that a target resource can have and may be interesting to identity management. There may be projects, workgroups-that-are-almost-but-not-quite-entirely-unlike-organizational-units, server clusters, coffee machines, kangaroos, or any other type of objects that we cannot imagine now.

Resource objects will not be stored in midPoint repository. They cannot as they have no fixed structure and therefore they have no OID. Resource objects are not directly used by stock midPoint logic. Stock midPoint code always works with shadow objects, not resource objects. As resource objects have no fixed schema, it is very difficult to write generic code that would work with them. Resource objects are more like necessary evil than something that we really want in an IDM system. The sole purpose of resource objects is to be available to customized business logic.

The operations that work with resource objects are not yet implemented in provisioning interface.

Resource Object Example

The following example shows the same object but represented as resource object using resource schema. This is really not a typical example, it is provided here only for comparison with the shadow object.

Resource Object
<object xsi:type="ds1:AccountObjectClass">
   <ds1:dn>uid=bond,o=mi5</ds1:dn>
   <ds1:uid>bond</ds1:uid>
   <ds1:cn>James Bond</ds1:cn>
   <ds1:sn>Bond</ds1:sn>
   <ds1:givenName>James</ds1:givenName>
</object>

More typical example of resource object is provided below.

Resource Object
<object xsi:type="au:KangarooObjectClass">
   <au:serialNumber>473562145x384fv2</au:serialNumber>
   <au:variety>au:TasmanianForesterType</au:variety>
   <au:name>Tassie</au:name>
   <au:tailLength unit="meter">0.8</au:tailLength>
</object>

If it looks fictional, it may be caused by the fact that it is fictional. If we could define appropriate type, stereotype or class of typical resource object that are found in IDM deployments now, we would do it. We would create appropriate (static) type of shadow objects for them. But, similarly to the fact that kangaroos are not frequently used in IDM deployments, the resource objects are really designed only to support the unexpected, strange, and exotic cases.

Resource Object Identification

Resource objects are identified by whatever native identifier the resource uses. It may be DN for LDAP, username and groupname for traditional systems, numeric uids, guid, UUIDs, GUID, nsUniqueIds or even some combination of several identifiers. We cannot really dictate any fixed identifier type, format or scheme.

Therefore, we have chosen not to choose a common identifier. Every connector will choose or suggest an identification mechanism for each the resource object type. The connector will announce the identification mechanism in the resource schema using the resource schema annotations.

See Also

Was this page helpful?
YES NO
Thanks for your feedback