<xsd:complexType name="AccountObjectClass">
<xsd:annotation>
<xsd:appinfo>
<ra:resourceObject/>
<ra:identifier>icfs:uid</ra:identifier>
<ra:displayNameAttribute>icfs:name</ra:displayNameAttribute>
<ra:namingAttribute>icfs:name</ra:namingAttribute>
<ra:nativeObjectClass>__ACCOUNT__</ra:nativeObjectClass>
<ra:account/>
<ra:default/>
</xsd:appinfo>
</xsd:annotation>
<xsd:sequence>
<xsd:element ref="icfs:uid" />
<xsd:element ref="icfs:name" />
<xsd:element minOccurs="0" ref="icfs:password" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="internationaliSDNNumber" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="x121Address" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="employeeType" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="pager" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="audio" type="xsd:base64Binary" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="departmentNumber" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="x500UniqueIdentifier" type="xsd:base64Binary" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="postalAddress" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="objectClass" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="givenName" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="mail" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="photo" type="xsd:base64Binary" />
<xsd:element minOccurs="0" name="displayName" type="xsd:string" />
<xsd:element maxOccurs="unbounded" name="cn" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="userPassword" type="xsd:base64Binary" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="physicalDeliveryOfficeName" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="manager" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="homePhone" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="description" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="postOfficeBox" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="homePostalAddress" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="roomNumber" type="xsd:string" />
<xsd:element minOccurs="0" name="employeeNumber" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="facsimileTelephoneNumber" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="userSMIMECertificate" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="l" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="userCertificate" type="xsd:base64Binary" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="teletexTerminalIdentifier" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="jpegPhoto" type="xsd:base64Binary" />
<xsd:element minOccurs="0" name="preferredDeliveryMethod" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="userPKCS12" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="postalCode" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="labeledURI" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="telexNumber" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="carLicense" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="street" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="registeredAddress" type="xsd:string" />
<xsd:element maxOccurs="unbounded" name="sn" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="seeAlso" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="secretary" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="mobile" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="uid" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="initials" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="businessCategory" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="telephoneNumber" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="o" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="title" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="destinationIndicator" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="st" type="xsd:string" />
<xsd:element maxOccurs="unbounded" minOccurs="0" name="ou" type="xsd:string" />
<xsd:element minOccurs="0" name="preferredLanguage" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>Resource Schema
|
Resource schema feature
This page is an introduction to Resource schema midPoint feature.
Please see the feature page for more details.
|
Definition
-
Defined at runtime in Resource definition (
ResourceType), in the<schema>element -
Annotations: xml/ns/public/resource/annotation-3.xsd
Introduction
Resource Schema defines representation of the information from the resources. Resource schema describes "live" objects such as accounts, groups or entitlements.
Specific resource schema depends on the actual resource instance: what type it is, how the adapter/connector is configured, what kind of native schema it is using (e.g. LDAP inetOrgPerson) and how the schema is customized. The information that the resource schema describes is dynamic and cannot be expressed as static XML structure. Resource schema can only be determined in run-time. Dynamic resource schema can vary for each instance of resource, e.g. two LDAP servers using exactly the same product, version, connector and even very similar connector configuration may show a very different resource schema. Resource schema is defined using the XSD language as most other schemas in midPoint.
We will refer to parts of the dynamic resource schema using a slightly different terminology than we use for static schemas.
While the static XSD types in midPoint use Type suffix in their XSD names, dynamic resource schema is using a ObjectClass suffix for the XSD types.
This naming distinction avoid confusion between the static parts of midPoint and the dynamic resource schema.
Resource schema works together with another dynamic schema: Connector Schema. The Resource and Connector Schema Explanation describes how these two fits together.
Motivation
It may look like the resource schema definition is duplicating many objects from the identity schema. E.g. the Object Class concept may look like Object Shadow, Account Object Class may look like Account Shadow. But this is not really the case. It is not a duplication, but rather an alignment of concepts. The resource schema is only available at run-time, therefore we need a static equivalent for these concepts in compile-type, e.g. to be able to store them in repository. Identity schema is static and takes that role. Secondly, the generic objects defined in the resource schema are defined in a very loose manner regarding their identification and therefore also referencing. They have no universal concept of unique identifier. To be able to store them efficiently and manage them, we need OID which is provided by the objects in identity schema. The identity schema acts as a mapping between native identifier and the OID. Thirdly, the resource schema is a shearing layer on top of identity schema as we want great deal of flexibility in the resource schema. That provides the capability of midPoint to adapt to almost any resource schema that we may encounter in the field.
Resource Schema and Resource Schema Handling
Resource schema defines capabilities of the Resource and the connector.
Resource schema is a dynamic thing.
It is in fact usually generated by the connector on demand and is not written by system administrator at all.
It has (almost) nothing to do with midPoint configuration.
For example, if there is an optional attribute givenName in the LDAP schema and the connector can expose that attribute to midPoint the Resource Schema will also contain such attribute.
It will be most likely marked as read-write and optional.
It does not matter if midPoint is using that attribute or not, it will be in the resource schema.
The details of how the Resource Schema is used by the midPoint is not part of the Resource Schema itself. It is defined by the Resource Schema Handling - except for one detail. Resource schema can suggest how the object classes and attributes should be used which provides reasonable default settings for midPoint. This is expressed in the resource schema by appropriate annotations.
The basic principle is:
-
Specifies capabilities of the Resource and Connector. If does not direcly define how the schema is used (although it may suggest it).
-
Resource Schema Handling specifies the decisions of IDM administrators. It defines how the Resource Schema is used by midPoint to implement parts of IDM logic, present the data to the user, etc.
Object Class
Object Class refers to a type of object on the Resource.
Unix account, Active Directory group, inetOrgPerson LDAP objectclass or a schema of USERS database table are all Object Classes from the midPoint point of view.
Object class defines a set of attribute names, types for each attribute and few additional properties.
Object classes are presented in the form of simple XSD schema objects in midPoint.
Each object class is a XSD complex type.
Each first-level element in such complex type is considered to be an attribute of the object class.
XSD datatypes are used to describe the attribute types.
Usually primitive and simple types are used (such as xsd:string), but even a complex types may be used (with some limitations, see below).
Usual XSD constructs such as minOccurs and maxOccurs are used to describe whether the attribute is mandatory and whether it is single-valued or multi-valued, as described in the following table.
| minOccurs | maxOccurs | ||
|---|---|---|---|
|
|
mandatory |
single-valued |
|
|
optional |
single-valued |
|
|
mandatory |
multi-valued |
|
|
optional |
multi-valued |
The XSD form of object class depends on the connector. It is generated by the connector (directly or indirectly) as it is in fact a definition of the objects that the connector understands.
MidPoint has a slightly unusual approach when it comes to the object class and attribute names.
midPoint does not try to map object class names and attribute names to some kind of common "global" structure.
midPoint is exposing the native resource terminology all the way to business logic and GUI.
It means that if account object class is known as inetOrgPerson on the resource and it contains attribute cn, the accounts from that resource will have attribute cn and will be presented as being of type InetOrgPersonObjectClass.
We do not consider the lack of the mapping as a drawback.
The mapping is usually too simplistic to be of any use for real IDM deployments and it only leads to a confusion.
Therefore we have decided to show the real names through the whole system.
Note that the attributes can still be transformed and synchronized to other attributes and properties using several midPoint mechanisms, such as inbound and outbound expressions.
See (Resource Schema Handling for more details).
The general rule of thumb is that XSD Object Classes should be as close to the "culture" of the target system (resource) as possible.
It should use the same or similar names for XSD elements as are the resource attributes.
Similarly, the names of object classes should reflect the types of object on the Resource.
For example the LDAP inetOrgPerson object class should be mapped to InetOrgPersonObjectClass XSD type, containing the cn, sn, givenName and similar elements (see the example below).
In addition to this, the connector should put nativeObjectClass and nativeAttributeName XSD annotations in the schema.
This may be used by the tools and business logic.
The complete process how native resource schema is used by the connector and mapped to Resource Schema is illustrated at Resource Schema Mapping page.
|
Technically, Object Class is a definition of Resource Object. Resource Object Definition is mean to be synonym for Object Class in some of the Java code (for naming consistency reasons). |
Object Class Definition Example
Following XSD snippet provides an example of object class definition.
The example shows how LDAP person object class could be presented in the resource schema.
The example shows a schema presented by ICF connector, therefore some attributes are mangled into tha ICF mandatory format (e.g. LDAP DN is mangled into ICF __NAME__ which is presented in the resource schema as icfs:name).
See ICF Issues.
Object Class Example
Resource Object Attribute
Resource object attribute is a property of object class. All that applies to property applies also to attribute, e.g. only a whole attributes can be changed, they may be simple or complex types, they should be representable in XML, etc. In addition, attribute definition may have some annotations that suggest its purpose and use on the Resource.
|
Terminology
TODO: terminology motivation. |
Resource Schema Annotations
There are some aspects of the Resource Schema that cannot be expressed by using just the standard XSD mechanisms. Such aspects include designation of identifiers for the Object Class, native object class and attribute names, readable names, etc. The midPoint resource schema defines a set of XSD annotations that can be used for this purpose. The annotations extend the XSD language to match our needs. Some annotations are authoritative information, some are just suggestions (default setting) that can be overridden in the Resource Schema Handling. Following sections define the annotations that can be used in the Resource Schema.
|
Prism Annotations
Please see also the Prism Schema that may also be applicable here. |
resourceObject
Resource object marker. The complex type marked by this annotation is considered to be a resource object.
Every object in the resource schema should have this marker annotation. Complex type definition that do not have this annotation are not considered part of the resource schema unless they are referred from types that have this annotation.
account
Account marker. The complex type marked by this annotation is considered to be an account.
default
A flag that specifies whether this object class is a default for its type of object classes. E.g. when combined with "account" annotation it marks a default account type.
accountType
Account type specification. The annotation contains a simple string value that is used to define account type, e.g. "user" or "admin".
nativeObjectClass
Native object class name. This annotation contains string value that specifies native object class of the resource object without any transformations, the name as it is used on the resource or as seen by the connector.
This annotation is used to specify the native object class only for diagnostics purposes and may be used by the connector itself. As the object class names in XSD have to comply with XSD limitations and by midPoint convention should end with ObjectClass suffix, this may be the only way how to determine original object class name. It is "read-only" in this aspect. It cannot use used to change or enforce object class mapping.
The name should be the same as the one used by the resource, if the resource supports naming of object classes. E.g. in case of LDAP this annotation should contain "inetOrgPerson", "groupOfNames", etc. If the resource is not that flexible, the native object class names may be hardcoded (e.g. "account", "group") or may not be present at all (which is discouraged).
This annotation may appear several times if the object is composed from several native object classes (e.g. as usual in LDAP).
If not present, the it defaults to the name of the object class XSD type (without namespace).
nativeAttributeName
Native attribute name. This annotation contains string value that specifies native name of the attribute without any transformations, the name as it is used on the resource or as seen by the connector.
This annotation is used to specify the native attribute name only for diagnostics purposes and may be used by the connector itself. As the attribute names in XSD have to comply with XML element name limitations, this may be the only way how to determine original attribute name. It is "read-only" in this aspect. It cannot use used to change or enforce attribute name mapping.
The name should be the same as the one used by the resource, if the resource supports naming of attributes. E.g. in case of LDAP this annotation should contain "cn", "givenName", etc. If the resource is not that flexible, the native attribute names may be hardcoded (e.g. "username", "homeDirectory") or may not be present at all.
If not present, the it defaults to the corresponding element name (without namespace).
identifier
Reference to the (primary) identifier attribute. This annotation contains a QName of the attribute that must be used to identify the resource objects. Identifiers are used to locate the object and to work with it. Every resource object must have at least one identifier to be practical.
The value of identifier must by unique in the scope of the resource.
The identifier should be immutable. E.g. if the object is renamed the identifier should be unchanged.
There may be multiple identifiers for a single object type. In that case it is assumed that all such identifier attributes form a compound identifier. E.g. that each unique combination of identifier values refers to a different object.
E.g. LDAP entryUUID, Unix UID, persistent object identifiers and similar attributes make a good identifier. Usernames, DNs and similar attributes may be used as well. But these are less desirable as they may change. Therefore these should be used only if no other option is available.
secondaryIdentifier
Reference to the secondary identifier attribute. This annotation contains a QName of the attribute that may be used to provide additional identification to the resource objects. Secondary identifiers are used as an alternative way to locate the object.
The value of secondary identifier must by unique in the scope of the resource.
It is OK for a secondary identifier to be mutable.
Secondary identifiers are optional. It is OK if an object has no secondary identifiers. There may be multiple secondary identifiers for a single object type. In that case it is assumed that all such identifier attributes form a compound identifier. E.g. that each unique combination of identifier values refers to a different object.
E.g. LDAP DN, username, unique object name or similar attributes are usually presented as secondary identifiers.
There are many reasons for taking secondary identifiers into account. The most important reason is the uniqueness requirement for secondary identifiers. I.e. a new resource object (e.g. account) cannot be created if the value of a secondary identifier conflicts with existing object. When midPoint knows about such secondary identifiers, it may read and cache them in shadows. Then it can make a uniqueness check for both primary and secondary identifiers by just looking at the shadows. Which is much more efficient than trying to create the account on resource and failing (maybe even several times). Secondary identifiers may be also used to confirm the equivalence of an object after primary identifier changes and in similar situations.
namingAttribute
Reference to the naming name attribute. This annotation contains a QName of the attribute that should be used to "name" the resource objects. The values of such attribute will be used for "name" property in shadows and may be also used for other similar purposes. This may not necessarily be human-readable, but it should be unique within the scope of the resource. It should also be admin-friendly in a sense that administrator should be able to quickly interpret that. E.g. user names, login names, screen name, DNs and similar attributes are good candidate for naming attribute.
displayNameAttribute
Reference to the display name attribute. This annotation contains a QName of the attribute that should be used as a human-readable "display name" for the resource objects. E.g. if it refers to the ldap:cn attribute then the content of that attribute will be used as short name when displaying the resource object to user (e.g. in GUI). This should be used for user-friendly values such as cn, full name, etc. There is no requirement for uniqueness.
descriptionAttribute
Reference to the desription attribute. This annotation contains a QName of the attribute that should be used as description of resource objects. Description is a longer (multi-line) free form-text. The description may be used as a general comment, it may be displayed when the object details are shown to the user, etc.
Implementation of Resource Schema
But, as such definition is not available at run-time, it cannot be mapped to Java using JAXB or similar compile-time technology. The resource schema needs to be dynamically interpreted at run-time, which makes the code quite complex.
The attributes of object class are properties, therefore they theoretically may have a deeper structure. However, midPoint does not care about that structure, it considers the attribute to be opaque. If there is a structured attribute, midPoint will pass it unchanged all the way from the connector to the business logic and GUI.
TODO
See Also
Compliance
This feature is related to the following compliance frameworks:
Was this page helpful?
YES
NO
Thanks for your feedback