Resource Configuration

Last modified 17 Oct 2024 15:02 +02:00
Table of Contents

Resource definition is perhaps the most important part of midPoint configuration. It configures connection to resource, resource object classes and attributes (resource schema), mapping of these attributes to the midPoint user model, resource capabilities, password policies, etc.

Resource definition is an ordinary object in midPoint repository. Therefore it has its OID and a name that has to be unique across all defined resources. The type of the object is ResourceType and the internal structure is quite complex. Resource definition consists of several parts:

Part Description Detailed Documentation

Connector Reference

Reference to the connector that implements specified resource. The connector is used to connect to the resource.

Configuration

Resource configuration (hostname, port, …​). Specific for each resource type.

Schema

XSD definition of resource schema for the resource instance. It defines data types for accounts, groups, roles, entitlements, organizational units or any other objects related to identity management that the resource supports. Schema describes what resource can do. I.e. it describe connector and resource configuration capabilities when it comes to object classes and attributes.

Resource Schema

Schema Handling

Specification of handling the objects defined in resource schema. E.g. read-only or read-write attributes, account object classes, expressions to determine values, etc. Schema describes what resource should do. I.e. it describes the decision of a midPoint administrator with respect to handling object classes and attribute values.

Resource Schema Handling

Capabilities

The capabilities supported by the resource, including both native capabilities of the connector and simulated capabilities. This described the capabilities that are not specific to an object class or an attribute, capabilities applicable to the resource as a whole. E.g. support for real-time synchronization, passwords, activation, etc.

Scripts

Collection of scripts to be executed for various provisioning operations.

Provisioning Scripts

Projection

Specification of the way how projections are handled on the resource. This defines the ways how assignments are enforced and so on.

Consistency

Configuration of consistency mechanisms. This may include configuration of high-level operation retries and similar technical configuration.

Caching

Definition of resource object (shadow) caching policies. See Shadow Caching.

Business

Configuration of resource "business" aspects such as workflow parameters, notifications, approvers, owners, etc.

Resource Definition Sections

Connector Reference

Resource has a reference to a connector object. This reference means that the connector will be used for all operations on the resource. This just a normal object reference once the resource definition is imported and running. However it is usually a smart reference when resource definition is imported into midPoint. Using filters in smart references make it easy to define connector by type or version instead of OID.

Smart Connector Reference Example
<connectorRef type="ConnectorType">
    <description>Reference to the ConnId LDAP connector by connectorType</description>
    <filter>
        <q:text>connectorType = "org.identityconnectors.ldap.LdapConnector"</q:text>
    </filter>
</connectorRef>

Hint: for the value of "connectorType", click the Configuration tab, then click the "List Objects" link and list objects of the "Connector" type. Click on the connector you want to use and copy the "connectorType" value.

See ConnectorType for more details regarding connectors, see Object References for more details regarding references.

Resource Configuration

Connector specified by resource connectorRef is just a bunch of code. For the connector to work properly it needs configuration. Such configuration specifies name of host where the resource resides, TCP/IP port number, technical account that should be used to connect to it, password for that account, database table name, directory root, filenames, etc.

Configuration properties are different for each connector type. The names and types of the properties are defined by the connector schema that is stored in connector object.

It may not be easy to create correct resource configuration by hand. Probably the best way is to start from samples.

LDAP Resource Configuration Example
<connectorConfiguration>
    <icfc:configurationProperties>
        <icfcldap:port>10389</icfcldap:port>
        <icfcldap:host>localhost</icfcldap:host>
        <icfcldap:baseContexts>dc=example,dc=com</icfcldap:baseContexts>
        <icfcldap:principal>uid=idm,ou=Administrators,dc=example,dc=com</icfcldap:principal>
        <icfcldap:credentials>
            <clearValue>secret</clearValue>
        </icfcldap:credentials>
        <icfcldap:modifiersNamesToFilterOut>uid=idm,ou=Administrators,dc=example,dc=com</icfcldap:modifiersNamesToFilterOut>
          <icfcldap:vlvSortAttribute>uid</icfcldap:vlvSortAttribute>
          <icfcldap:accountOperationalAttributes>ds-pwp-account-disabled</icfcldap:accountOperationalAttributes>
          <icfcldap:usePagedResultControl>true</icfcldap:usePagedResultControl>
    </icfc:configurationProperties>
</connectorConfiguration>

See Resource and Connector Schema Explanation for a detailed description how the dynamic schemas work together.

Resource Schema

Main article: Resource Schema

The schema element contains the XSD-formatted definition of resource schema. It defines data types for accounts, groups, roles, entitlements, organizational units or any other objects related to identity management that the resource supports.

Resource schema is dynamic. It is only available at run-time and can be different for every resource instance, even for resource instances of the same type. It is supposed to be dynamically interpreted in run-time.

Resource schema defines what a resource can do, what object types it supports (presented as XSD types). But it does NOT define how these types are handled. E.g. it defines attributes and object class for inetOrgPerson, that it has cn attribute which is multi-valued string, etc.

Resource schema is automatically generated from the resource in a normal case therefore it does not need to be configured. It will be fetched from the resource first time the resource is used. This happens on the first use of the resource, which is typically the click on Test Connection button. You can check generated schema clicking through the path Configuration→Repository objects→resource (from List objects)→ resource of your choice (from a resource list on the right pane). If the resource schema needs to be generated again (e.g. after the change of LDAP schema on LDAP resource) then delete the schema element from the resource definition. The schema will be generated anew on the next use of that resource. Resource schema also contains caching metadata that are generated at the same time a schema is generated. There are used for internal midPoint optimizations.

LDAP Resource Schema Example (simplified)
<schema>
    <cachingMetadata>
        <retrievalTimestamp>2012-03-20T13:02:29.275+01:00</retrievalTimestamp>
        <serialNumber>1798eed6def9f54c-3d4bce63faa79272</serialNumber>
    </cachingMetadata>
    <definition>
        <xsd:schema elementFormDefault="qualified"
                targetNamespace="http://midpoint.evolveum.com/xml/ns/public/resource/instance-2"
                xmlns:icfs="http://midpoint.evolveum.com/xml/ns/public/connector/icf-1/resource-schema-2" ...>
            <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 maxOccurs="unbounded" name="cn" type="xsd:string" />
                    <xsd:element ref=`icfs:name` />
                    <xsd:element ref=`icfs:uid` minOccurs="0"/>
                    <xsd:element minOccurs="0" ref="icfs:password" />
                    <xsd:element maxOccurs="unbounded" minOccurs="0" name="givenName" type="xsd:string" />
                    <xsd:element maxOccurs="unbounded" name=`sn` type="xsd:string" />
                    ...
                </xsd:sequence>
            </xsd:complexType>
            <xsd:complexType name="GroupObjectClass">
                ...
            </xsd:complexType>
            ...
        </xsd:schema>
    </definition>
</schema>

Please note that while you can see most of the original LDAP attributes there (cn, sn, givenName, …​) some of the attributes are not really from LDAP (icfs:name, icfs:uid). These attributes are built-in OpenICF attributes. While we always prefer to use native attribute names it is not practical in this case as ICF hides the attributes from midPoint. Similarly for the inetOrgPerson objectclass versus ICF ACCOUNT{}objectclass (see ICF Issues for more details).

See Resource Schema for more details. See Resource and Connector Schema Explanation for a detailed description how the dynamic schemas work together.

Schema Handling

Main article: Resource Schema Handling

Specification of handling the objects defined in resource schema. E.g. read-only or read-write attributes, account object classes, expressions to determine values, etc.

Schema handling specifies decisions of an IDM administrator how the resource schema should be used, e.g. what object types to use for an account, how to setup the attributes, how to deal with passwords, etc. Schema handling is the part of resource definition that takes the most of the administrator attention. It is the place where resource behavior can be customized. Schema handling also influences how the resource will be presented in the GUI, e.g. it sets display names for attributes and account types.

There is a separate access limitation configuration for each resource attribute supported by the resource schema:

  • create: the attribute can be set when creating a resource account. Useful for attributes that can be set only once.

  • update: the attribute can be set when updating a resource account.

  • read: the attribute is read-only and can’t be modified.

By default, no access limitation is enforced (create, update, read).

There is a separate outbound/inbound configuration for each resource attribute supported by the resource schema.

The outbound configuration specifies how to transform the attribute value from midPoint on the fly before it is sent to resource attribute. The modification value can use other attribute values, constants or anything that can be achieved by an expression. For example you may wish to set the resource’s fullname attribute to the uppercase value of midPoint’s fullName attribute. The outbound is what you use for provisioning.

The inbound configuration specifies where (to which midPoint attribute) to store the resource attribute value and optionally, how to transform it. For example, you may wish to store the resource’s full_name_attr attribute value to midPoint’s fullName attribute without modification. The inbound is what you use for synchronization. Please note that there are multiple Synchronization Flavors and this configuration applies to all of them.

There is an optional <strength> argument to specify if an existing attribute value should be replaced:

  • weak: the expression will be evaluated only if there is no value of the attribute on the target side

  • strong: the expression will be always evaluated

Currently, the use of the default value (normal) is not recommended. Please specify strong instead.

See also Mapping strength.

The following example is from the OpenDJ advanced sync sample. The configuration for sn (surname) resource attribute is configured as follows:

  • the resource sn attribute can be modified with no limitation

  • the value of the resource sn attribute will be automatically set from midPoint’s familyName attribute value when provisioning (outbound)

  • the value of the resource sn attribute will be automatically set to midPoint’s familyName attribute when synchronizing (inbound)

<attribute>
    <ref>ri:sn</ref>
    <displayName>Surname</displayName>
    <access>create</access>
    <access>read</access>
    <access>update</access>
    <outbound>
        <source>
             <!-- The path can be shortened like this. $user is a default source "context" in outbound -->
             <path>familyName</path>
        </source>
    </outbound>
    <inbound>
        <target>
            <!-- The path can be shortened like this. $user is a default target "context" in inbound -->
            <path>familyName</path>
        </target>
    </inbound>
</attribute>

The following example is from the OpenDJ advanced sync sample. The configuration for description resource attribute is configured as follows:

  • the resource attribute description can be modified with no limitation

  • the value of the resource attribute description will be automatically set to a constant "Created by IDM" when provisioning (outbound), but only if the resource attribute has no value yet (<strength>weak</strength>)

  • no inbound expression is used: the description resource attribute will not be synchronized to any midPoint attribute when synchronizing

<attribute>
    <ref>ri:description</ref>
    <outbound>
        <strength>weak</strength>
        <expression>
            <description>Expression that assigns a fixed value</description>
            <value>Created by IDM</value>
        </expression>
    </outbound>
</attribute>

See Resource Schema Handling for more detailed explanation.

NAME and UID Special Attributes

There are two special attributes: icfs:name mapped to ConnId __NAME__ attribute and icfs:uid mapped to ConnId __UID__ attribute. Please do not confuse them with ri:name and/or ri:uid attributes.

Attribute Name ICF Attribute Name Description

icfs:name

__NAME__

Unique, mutable account identifier, e.g. Distinguished Name in hierarchical systems like LDAP or a login name in flat resources

icfs:uid

__UID__

Unique, immutable account identifier, e.g. Entry UUID in LDAP (not created by you, but generated by LDAP server)

For some resources (connectors) the __NAME__ and __UID__ attributes are equivalent.

As a rule of thumb, you can configure an outbound expression for icfs:name to define an account identifier (e.g. LDAP’s DN attribute). After the account is created, icfs:uid attribute may be used internally for unique resource account identification, but this attribute will be read-only. There is no need for outbound/inbound expressions for icfs:uid attribute. Change in the icfs:name attribute will cause the renaming of the account.

The following is an example of icfs:uid attribute configuration from OpenDJ advanced sync sample:

  • the attribute is read-only

  • there are no outbound/inbound expressions

<attribute>
    <ref>icfs:uid</ref>
    <displayName>Entry UUID</displayName>
    <access>read</access>
</attribute>

The following is an example of icfs:name attribute configuration from OpenDJ advanced sync sample:

  • the attribute icfs:name can be only created and read (no modification)

  • the value of the icfs:name attribute will be automatically set to a concatenation of user’s login name in midPoint and a static suffix, but only if the resource attribute has no value yet (<strength>weak</strength>)

  • no inbound expression is used: the icfs:name attribute will not be synchronized to any midPoint attribute when synchronizing

<attribute>
    <ref>icfs:name</ref>
    <displayName>Distinguished Name</displayName>
    <access>create</access>
    <access>read</access>
    <outbound>
        <strength>weak</strength>
        <source>
            <path>$user/name</path>
        </source>
        <expression>
            <script>
                <!-- No explicit script language was specified. It means that this is Groovy -->
                <code>
                    'uid=' + name + iterationToken + ',ou=people,dc=example,dc=com'
                </code>
            </script>
        </expression>
    </outbound>
</attribute>

Credentials Handling

Credentials (password and password-related information) handling is a special part of Schema Handling and allows you to define how user’s credentials will be synchronized. The credentials can be synchronized from midPoint user to resource account (outbound) or the opposite way (inbound) or both. You can also specify that the password should be generated - this is very useful for synchronizing resource accounts to midPoint to make sure that the password will be set even if the resource account password can’t be used (e.g. is encrypted).

The following is an example of credentials configuration from OpenDJ advanced sync sample:

  • the password from midPoint user is synchronized to resource account (outbound) as is

  • the password for midPoint user will be generated when synchronizing from the resource account (inbound), but only if the midPoint password is empty (e.g. for the very first time when you create midPoint user from the resource account). The target parameter is omitted, because it will be the midPoint password attribute.

<credentials>
    <password>
        <outbound>
            <expression>
                <asIs/>
            </expression>
        </outbound>
        <inbound>
            <strength>weak</strength>
                <expression>
                    <generate/>
                </expression>
        </inbound>
    </password>
</credentials>

Activation Handling

The activation/deactivation (account enabled/disabled) handling is a special part of Schema Handling and allows you to define how user’s state will be synchronized. The user state can be synchronized from midPoint user to resource account (outbound) or the opposite way (inbound) or both.

The following is an example of activation configuration from OpenDJ advanced sync sample:

  • the user state from midPoint is synchronized to resource account state (outbound) as is

  • the resource account state is synchronized to midPoint user (inbound) as is but only if the midPoint user state is empty (e.g. for the very first time when you create midPoint user from the resource account). The resource account will not be authoritative for the account state except the first synchronization. The target parameter is omitted, because it will be the midPoint user state attribute.

<activation>
    <administrativeStatus>
        <outbound>
            <asIs/>
        </outbound>
        <inbound>
            <strength>weak</strength>
            <source>
                <asIs/>
            </source>
        </inbound>
    </administrativeStatus>
</activation>

Correlation and Synchronization

The correlation and synchronization sections define setting of synchronization mechanisms. That is a common setting for live sync, reconciliation, import, discovery, etc.

  • The correlation section contains instructions how to locate an owner of an account. In the simplest case, it consists of a list of user properties that are used to find the owner. There are other options, though, for example using smart correlation or a custom correlation filter or expression.

  • The synchronization section defines how midPoint will behave in a specific synchronization situation. The reaction may specify, e.g., that a new account has to be linked to a user (typically, if the owner was found) or disabled (if it was not). The default reaction is to do nothing.

The following is an example of a synchronization configuration:

  • the correlation expression is configured as follows: the owner is found by matching the user name (the value of which is derived from the attribute ri:uid)

  • for the unlinked situation (the correlation expression found exactly one owner in midPoint but they have no reference to this account) the response action is about to set link between the account and the owner (link) and to synchronize the values according to mappings

  • for the unmatched situation unmatched (the correlation expression found no owner in midPoint) the response action is about to create a new midPoint user. The midPoint user attributes will be set using the inbound expressions for resource attributes and a specified Object Template object. In addition, the resource account will be linked to the midPoint user.

  • for the linked situation (there is a user that has a reference to this account) the response action is about to synchronize values according to mappings

  • for the deleted situation (account was found to be deleted on the resource) the response action is to synchronize values according to mappings. The account is also unlinked from its owner (if there’s one). This unlinking is done for each deleted account, regardless of the synchronization action(s) specified.

LDAP Resource Correlation and Synchronization Example
<correlation>
    <attribute>
        <ref>ri:uid</ref>
        <inbound>
            <target>
                <path>name</path>
            </target>
        </inbound>
    </attribute>
    ...
    <correlators>
        <items>
            <item>
                <ref>name</ref>
            </item>
        </items>
    </correlators>
</correlation>
<synchronization>
    <reaction>
        <situation>unlinked</situation>
        <actions>
            <link/>
        </actions>
    </reaction>
    <reaction>
        <situation>unmatched</situation>
        <actions>
            <addFocus>
                <!-- Reference to the object template is here. If the user would be created as a result of this action,
                     it will be created according to this template. -->
                <objectTemplateRef oid="c0c010c0-d34d-b33f-f00d-777222222222"/>
            </addFocus>
        </actions>
    </reaction>
    <reaction>
        <situation>linked</situation>
        <actions>
            <synchronize/>
        </actions>
    </reaction>
    <reaction>
        <situation>deleted</situation>
        <actions>
            <synchronize/>
        </actions>
    </reaction>
</synchronization>

See Synchronization page for an overview of the synchronization mechanism and Synchronization Examples for a detailed description of synchronization.

Capabilities

Main article: Resource Capabilities

Capabilities are definitions of specific things that a resource can do. There is plethora of various resource types and configurations. Some resources can enable/disable an account, while others cannot. Some resources can provide live feed of changes, while others cannot. The capabilities section list the features that the resource has.

There are two sections of capabilities definition:

  • Native capabilities are native to the resource. There are the things that resource can do all by itself without any help from midPoint. The list of native capabilities is provided by the connector and does not need to be configured. It is stored in the resource object for performance reasons. If this section is not present in the resource configuration it will be automatically fetched from the resource before its first use.

  • Configured capabilities are decision of an administrator how to use native capabilities. This section can be used to disable native capabilities or add capabilities. Some capabilities can be simulated by midPoint. E.g., a resource does not support account enable/disable directly. But administrator knows that the enable/disable may be done by flipping a boolean value of a specific attribute. Such simulated capability can be configured in this section. MidPoint will then pretend that the resource has the enable/disable ability. But each time the ability us used it will transparently convert the operation to modification of the special attribute. That’s how midPoint simulates some capabilities.

These two sections are added together to form presented capabilities (or just "capabilities"). These are all the features that the resource can do by itself (native capabilities), minus the capabilities that were disabled, plus the capabilities that are simulated. GUI, IDM model and business logic will all work only with presented capabilities, whether a capability is native or simulated does not matter for such upper system layers.

If you want to use native connector’s capabilities without modification, you don’t need to set capabilities for the resource at all.

The following is an example of capabilities configuration as can be seen in XML editor when checking OpenDJ resource configuration (click through the path Configuration→Repository objects→Resources→Local host OpenDJ resource). You have to have imported OpenDJ advanced sync sample (Configuration→Import object→Import from file) and "test connection" button pressed (Resources→Localhost OpenDJ→"test connection" button in Resource details page):

  • resource attribute ri:ds-pwp-account-disabled will be used for resource account de/activation (empty value: account activated, true value: account deactivated)

  • configured capabilities consist of <activation> part

  • native capabilities: credentials, liveSync, testConnection (this part is automatically provided by connector, it is not present in OpenDJ advanced sample code)

LDAP Resource Capabilities Example
<capabilities>
    <cachingMetadata>...</cachingMetadata>
    <native>
        <cap:script>
            <cap:host>
                <cap:type>connector</cap:type>
            </cap:host>
        </cap:script>
        <cap:credentials>
            <cap:password/>
        </cap:credentials>
        <cap:testConnection/>
        <cap:liveSync/>
    </native>
    <configured>
        <cap:activation>
            <cap:enableDisable>
                <cap:attribute>ri:ds-pwp-account-disabled</cap:attribute>
                <cap:enableValue/>
                <cap:disableValue>true</cap:disableValue>
            </cap:enableDisable>
        </cap:activation>
    </configured>
</capabilities>

Scripts

Some resources have the ability to execute scripts. MidPoint binds execution of scripts to specific operations. Therefore a script can be automatically executed before of after the account is created, modified or deleted.

See Provisioning Scripts page for more details.

Consistency

See Resource Consistency Configuration for more details.

This section contains configuration of consistency mechanisms. This may include configuration of high-level operation retries and similar technical configuration. This section contains:

  • avoidDuplicateValues: When set to true, midPoint will try to avoid adding attribute values that are already there and remove values that are not there. Some resources do not tolerate such operations and they respond with errors. However midPoint cannot rely on transactions. MidPoint’s lock-free relativistic model provides the necessary consistency, occasional redundant additions or deletions may happen. If this option is turned on then midPoint will read the data from resource right before the operation and filter our any redundant changes. This requires additional operation and it increases the risk of inconsistencies. However it is the only practical option for some resources.

  • caseIgnoreAttributeNames: If set to true then midPoint will ignore the case of the attribute names. In that case midpoint will normalize any attribute names with regard to the resource schema.

  • postpone:

  • discovery:

  • connectorErrorCriticality: Specifies a method that midPoint will use to evaluate criticality of errors: which errors are considered to be critical (stops the operation) and which error are non-critical (operation continues). By default network errors are not considered critical, other errors are critical. EXPERIMENTAL: use with care.

Account Synchronization Settings

Main article: Projection Policy

It has been mentioned elsewhere that the assignment relates to state that should be while the link relates to state that is. Account synchronization settings are about dealing situations when an user has an assignment but a corresponding account does not exist and when an account on a resource was created but a correspondent user does not exist. There are global account synchronization settings in System Configuration object to set this behavior globally for all resources. To change these properties for individual resource the account synchronization settings in resource object can be customized as you can see in following code:

<c:AccountSynchronizationSettings>
    <assignmentPolicyEnforcement>full</assignmentPolicyEnforcement>
</c:AccountSynchronizationSettings>
Even if the account is linked to the user by synchronization code it does not mean that it will not be deleted later by the standard synchronization code. This may easily happen if the account is not assigned (which is likely) and the projection policy is set to a strict setting. You have to adjust the projection policy (e.g. by relaxing the enforcement or by using legalization option) to resolve the situation.

User Template

The user template can be used in synchronization actions to compute midPoint user attributes and/or assign default account on other resources. It will be used in addition to inbound expression processing.

The following is an example of user template from OpenDJ advanced sync sample:

  • the user template is named "Default User Template"

  • it will compute midPoint user attribute fullName from midPoint user attributes givenName and familyName, but only if the fullName has no value (initial:true). This can be utilized to have a last resort value for the fullName attribute if the inbound expression has not set a value before

<objectTemplate oid="c0c010c0-d34d-b33f-f00d-777111111111">

    <name>Default User Template</name>

    <description>
        User Template Object.
        This object is used when creating a new account, to set it up as needed.
    </description>

    <mapping>
        <description>
            Property mapping.
            Defines how properties of user object are set up.
            This specific definition sets a full name as a concatenation
            of givenName and familyName.
        </description>
        <strength>weak</strength>
        <source>
            <path>$user/givenName</path>
        </source>
        <source>
            <path>$user/familyName</path>
        </source>
        <expression>
            <script>
                <language>http://midpoint.evolveum.com/xml/ns/public/expression/language#Groovy</language>
                <code>
                    givenName + ' ' + familyName
                </code>
            </script>
        </expression>
        <target>
            <path>fullName</path>
        </target>
    </mapping>

</objectTemplate>

Resource and Object Type Inheritance

Resource definitions often have parts that are common to multiple resources and/or to multiple object types. It is possible to either define these parts repeatedly for individual places where they are needed, or to use the inheritance between resources as well as between individual object types.

Samples

The best repository of fresh samples is the midpoint-samples project. There is a lot of examples for various resource types. Some samples define just the basic minimum others demonstrate how to configure advanced features. The samples have in-line comments to make it easier to understand them.

See Also

Was this page helpful?
YES NO
Thanks for your feedback