IDM 7.2.1

Mappings with a DS repository

For both generic and explicit mappings, IDM maps object types using a dnTemplate property. The dnTemplate is effectively a pointer to where the object is stored in DS. For example, the following excerpt of the default repo.ds.json file shows how configuration objects are stored under the DN ou=config,dc=openidm,dc=forgerock,dc=com:

"config": {
    "dnTemplate": "ou=config,dc=openidm,dc=forgerock,dc=com"
}

Generic mappings (DS)

By default, IDM uses a generic mapping for all objects except the following:

  • Internal users, roles, and privileges

  • Links

  • Clustered reconciliation target IDs

    Clustered reconciliation is not supported with a DS repository.

  • Locks

  • Objects related to queued synchronization

With a generic mapping, all the properties of an object are stored as a single JSON blob in the fr-idm-json attribute. To create a new generic mapping, you need only specify the dnTemplate; that is, where the object will be stored in the directory tree.

You can specify a wildcard mapping, that stores all nested URIs under a particular branch of the directory tree, for example:

"managed/*": {
    "dnTemplate": "ou=managed,dc=openidm,dc=forgerock,dc=com"
}

With this mapping, all objects under managed/, such as managed/user and managed/device, will be stored in the branch ou=managed,dc=openidm,dc=forgerock,dc=com. You do not have to specify separate mappings for each of these objects. The mapping creates a new ou for each object. So, for example, managed/user objects will be stored under the DN ou=user,ou=managed,dc=openidm,dc=forgerock,dc=com and managed/device objects will be stored under the DN ou=device,ou=managed,dc=openidm,dc=forgerock,dc=com.

Improve generic mapping search performance (DS)

By default, all generic objects are instances of the fr-idm-generic-obj object class and their properties are stored as a single JSON blob in the fr-idm-json attribute. The fr-idm-json attribute is indexed by default, which results in all attributes of a generic object being indexed. JDBC repositories behave in a similar way, with all generic objects being searchable by default.

To optimize search performance on specific generic resources, you can set up your own schema providers and indices as described in this section. For a detailed explanation of how indexes improve LDAP search performance, see Indexes in the DS Configuration Guide.

For an embedded or external DS repository, the following managed user properties are indexed by default:

  • userName (cn)

  • givenName

  • sn

  • mail

  • accountStatus

You can configure managed user indexes in the repository configuration (repo.ds.json) by adding indices and schemaProviders objects, as follows:

"indices" : {
    ...
    "fr-idm-managed-user-json" : {
        "type" : [ "EQUALITY" ]
    },
    ...
},
"schemaProviders" : {
    "IDM managed/user Json Schema" : {
        "matchingRuleName" : "caseIgnoreJsonQueryMatchManagedUser",
        "matchingRuleOid" : "1.3.6.1.4.1.36733.2.....",
        "caseSensitiveStrings" : false,
        "fields" : [ "accountStatus", "givenName", "mail", "sn", "userName" ]
    },
    ...
}

The indexed properties are listed in the array of fields for that managed object. To index additional managed user properties, add the property names to this array of fields.

To set up indexes on generic objects other than the managed user object, you must do the following:

  • Add the object to the DS schema.

    The schema for an embedded DS repository is stored in the /path/to/openidm/db/openidm/opendj/db/schema/60-repo-schema.ldif file.

    You can use the managed user object as an example of the schema syntax:

    ###
# Managed User
###
attributeTypes: ( 1.3.6.1.4.1.36733.2.3.1.13
  NAME 'fr-idm-managed-user-json'
  SYNTAX 1.3.6.1.4.1.36733.2.1.3.1
  EQUALITY caseIgnoreJsonQueryMatchManagedUser
  ORDERING caseIgnoreOrderingMatch
  SINGLE-VALUE
  X-ORIGIN 'OpenIDM DSRepoService')
objectClasses: ( 1.3.6.1.4.1.36733.2.3.2.6
  NAME 'fr-idm-managed-user'
  SUP top
  STRUCTURAL
  MUST ( fr-idm-managed-user-json )
  X-ORIGIN 'OpenIDM DSRepoService' )

    For information about adding JSON objects to the DS schema, see Schema and JSON in the DS Configuration Guide.

    If you delete the db/openidm directory, any additions you have made to the schema will be lost. If you have customized the schema, be sure to back up the 60-repo-schema.ldif file.

  • Add the object to the indices property in the conf/repo.ds.json file.

    The following example sets up an equality index for a managed devices object:

    "indices" : {
    ...
    "fr-idm-managed-devices-json" : {
        "type" : [ "EQUALITY" ]
    },
    ...
}

  • Add the object to the schemaProviders property in the conf/repo.ds.json file and list the properties that should be indexed.

    The following example sets up indexes for the deviceName, brand, and assetNumber properties of the managed device object:

    "schemaProviders" : {
    "Managed Device Json" : {
        "matchingRuleName" : "caseIgnoreJsonQueryMatchManagedDevice",
        "matchingRuleOid" : "1.3.6.1.4.1.36733.2.....",
        "caseSensitiveStrings" : false,
        "fields" : [ "deviceName", "brand", "assetNumber" ]
    }
}

For more information about indexing JSON attributes, see JSON Query Matching Rule Index in the DS Configuration Guide.

The OIDs shown in this section are reserved for ForgeRock internal use. If you set up additional objects and attributes, or if you change the default schema, you must specify your own OIDs here.

Explicit mappings (DS)

The default configuration uses a generic mapping for managed user objects. To use an explicit mapping for managed user objects, change the repository configuration before you start IDM for the first time.

To set up an explicit mapping:

  1. Copy the repo.ds-explicit-managed-user.json file to your project’s conf directory, and rename that file repo.ds.json :

    cp /path/to/openidm/db/ds/conf/repo.ds-explicit-managed-user.json project-dir/conf/repo.ds.json
    This file is configured for an embedded DS repository by default. To set up an explicit mapping for an external DS repository, change the value of the embedded property to false and add the following properties: 
    "security": {
  "trustManager": "file",
  "fileBasedTrustManagerType": "JKS",
  "fileBasedTrustManagerFile": "&{idm.install.dir}/security/truststore",
  "fileBasedTrustManagerPasswordFile": "&{idm.install.dir}/security/storepass"
},
"ldapConnectionFactories": {
  "bind": {
    "connectionSecurity": "startTLS",
    "heartBeatIntervalSeconds": 60,
    "heartBeatTimeoutMilliSeconds": 10000,
    "primaryLdapServers": [
      {
        "hostname": "localhost",
        "port": 31389
      }
    ],
    "secondaryLdapServers": []
  },
  "root": {
    "inheritFrom": "bind",
    "authentication": {
      "simple": {
        "bindDn": "uid=admin",
        "bindPassword": "password"
      }
    }
  }
}

    For more information on these properties, see DS Repository Configuration.

  2. Start IDM.

IDM uses the DS REST to LDAP gateway to map JSON objects to LDAP objects stored in the directory. To create additional explicit mappings, you must specify the LDAP objectClasses to which the object is mapped, and how each property maps to its corresponding LDAP attributes. Specify at least the property type and the corresponding ldapAttribute. For relationships between objects, you must explicitly define those objects in the repository configuration.

The following excerpt shows an example of an explicit managed user object mapping:

"managed/user" : {
    "dnTemplate": "ou=user,ou=managed,dc=openidm,dc=forgerock,dc=com",
    "objectClasses": [
        "person",
        "organizationalPerson",
        "inetOrgPerson",
        "fr-idm-managed-user-explicit",
        "inetuser"
    ],
    "properties": {
        "_id": {
            "type": "simple", "ldapAttribute": "uid", "isRequired": true, "writability": "createOnly"
        },
        "userName": {
            "type": "simple", "ldapAttribute": "cn"
        },
        "password": {
            "type": "json", "ldapAttribute": "fr-idm-password"
        },
        "accountStatus": {
            "type": "simple", "ldapAttribute": "fr-idm-accountStatus"
        },
        "roles": {
            "type": "json", "ldapAttribute": "fr-idm-role", "isMultiValued": true
        },
        "effectiveRoles": {
            "type": "json", "ldapAttribute": "fr-idm-effectiveRole", "isMultiValued": true
        },
        "effectiveAssignments": {
            "type": "json", "ldapAttribute": "fr-idm-effectiveAssignment", "isMultiValued": true
        },
        ...
    }
}

You do not need to map the _rev (revision) property of an object as this property is implicit in all objects and maps to the DS etag operational attribute.

If your data objects include virtual properties, you must include property mappings for these properties. If you don’t explicitly map the virtual properties, you will see errors similar to the following when you attempt to create the corresponding object:

{
    "code": 400,
    "reason": "Bad Request",
    "message": "Unmapped fields..."
}

For more information about the REST to LDAP property mappings, see Mapping Configuration in the DS REST API Guide.

For performance reasons, the DS repository does not apply unique constraints to links. This behavior is different to the JDBC repositories, where uniqueness on link objects is enforced.

DS currently has a default index entry limit of 4000. Therefore, you cannot query more than 4000 records unless you create a Virtual List View (VLV) index. A VLV index is designed to help DS respond to client applications that need to browse through a long list of objects.

You cannot create a VLV index on a JSON attribute. For generic mappings, IDM avoids this restriction by using client-side sorting and searching. However, for explicit mappings you must create a VLV index for any filtered or sorted results, such as results displayed in a UI grid. To configure a VLV index, use the dsconfig command described in Virtual List View Index in the DS Configuration Guide.

Specify how IDM IDs map to LDAP entry names

The DS REST2LDAP configuration lets you set a namingStrategy that specifies how LDAP entry names are mapped to JSON resources. When IDM stores its objects in a DS repository, this namingStrategy determines how the IDM _id value maps to the Relative Distinguished Name (RDN) of the corresponding DS object.

The namingStrategy is specified as part of the explicitMapping of an object in the repo.ds.json file. The following example shows a naming strategy configuration for an explicit managed user mapping:

"resourceMapping": {
    "defaultMapping": {
        "dnTemplate": "ou=generic,dc=openidm,dc=forgerock,dc=com"
    },
    ...
    "explicitMapping": {
        "managed/user": {
            "dnTemplate": "ou=user,ou=managed,dc=openidm,dc=forgerock,dc=com",
            "objectClasses": [
                "person",
                "organizationalPerson",
                "inetOrgPerson",
                "fr-idm-managed-user-explicit"
            ],
            "namingStrategy": {
                "type": "clientDnNaming",
                "dnAttribute": "uid"
            },
            ...
        }
    }
}

The namingStrategy can be one of the following:

  • clientDnNaming - IDM provides an _id to DS and that _id is used to generate the DS RDN. In the following example, the IDM _id maps to the LDAP uid attribute:

    {
    "namingStrategy": {
        "type": "clientDnNaming",
        "dnAttribute": "uid"
    }
}

    With this default configuration, entries are stored in DS with a DN similar to the following:

    "uid=idm-uuid,ou=user,ou=managed,dc=openidm,dc=forgerock,dc=com"
    If these default DNs are suitable in your deployment, you do not have to change anything with regard to the naming strategy.

  • clientNaming - IDM provides an _id to DS but the DS RDN is derived from a different user attribute in the LDAP entry. In the following example, the RDN is the cn attribute. The _id that IDM provides for the object maps to the LDAP uid attribute:

    {
    "namingStrategy": {
        "type": "clientNaming",
        "dnAttribute": "cn",
        "idAttribute": "uid"
    }
}

    With this configuration, entries are stored in DS with a DN similar to the following:

    "cn=username,ou=user,ou=managed,dc=openidm,dc=forgerock,dc=com"

Specifying a namingStrategy is optional. If you do not specify a strategy, the default is clientDnNaming with the following configuration:

{
    "namingStrategy" : {
        "type" : "clientDnNaming",
        "dnAttribute" : "uid"
    },
    "properties: : {
        "_id": {
            "type": "simple",
            "ldapAttribute": "uid",
            "isRequired": true,
            "writability": "createOnly"
        },
        ...
    }
}

If you do not set a dnAttribute as part of the naming strategy, the value of the dnAttribute is taken from the value of the ldapAttribute on the _id property.

Relationship properties in a DS repository

The IDM object model lets you define relationships between objects. In a DS repository, relationships are implemented using the reference and reverseReference REST to LDAP property types. For more information about the reference and reverseReference property types, read the JSON property mapping section of the DS HTTP User Guide.

Relationship properties must be defined in the repository configuration (repo.ds.json), for both generic and explicit object mappings.

The following property definitions for a managed/user object show how the relationship between a manager and their reports is defined in the repository configuration:

"managed/user" : {
    "dnTemplate" : "ou=user,ou=managed,dc=openidm,dc=forgerock,dc=com",
    ...
    "properties" : {
        ...
        "reports" : {
            "type" : "reverseReference",
            "resourcePath" : "managed/user",
            "propertyName" : "manager",
            "isMultiValued" : true
        },
        "manager" : {
            "type" : "reference",
            "ldapAttribute" : "fr-idm-managed-user-manager",
            "primaryKey" : "uid",
            "resourcePath" : "managed/user",
            "isMultiValued" : false
        },
        ...
    }
}

This configuration sets the reports property as a reverseReference, or reverse relationship of the manager property. This means that if you add a manager to a user, the user automatically becomes one of the reports of that manager.

Note the ldapAttribute defined in the relationship object (fr-idm-managed-user-manager in this case). Your DS schema must include this attribute, and an object class that contains this attribute. Relationship attributes in the DS schema must use the Name and JSON with id syntax.

The following example shows the DS schema definition for the IDM manager property:

attributeTypes: ( 1.3.6.1.4.1.36733.2.3.1.69
  NAME 'fr-idm-managed-user-manager'
  DESC 'Reference to a users manager'
  SINGLE-VALUE
  SYNTAX 1.3.6.1.4.1.36733.2.1.3.12
  EQUALITY nameAndOptionalCaseIgnoreJsonIdEqualityMatch
  X-STABILITY 'Internal' )

If you define a relationship in the managed object configuration and you do not define that relationship as a reference or reverse reference in the repository configuration (repo.ds.json ), you will be able to query the relationships, but filtering and sorting on those queries will not work. This is the case when you define relationship objects in the admin UI—the relationship is defined only in the managed object configuration and not in the repository configuration.

In this case, queries such as the following are not supported:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/managed/user/_id/managedOrgs?_pageSize=50&_sortKeys=_id&_totalPagedResultsPolicy=ESTIMATE&_queryFilter=true"

This restriction includes delegated admin privilege filters.
Copyright © 2010-2022 ForgeRock, all rights reserved.