LDAP Connector
Important
Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.
The LDAP connector is based on the Java Naming and Directory Interface (JNDI), and can connect to any LDAPv3-compliant directory server, such as ForgeRock Directory Services (DS), Active Directory, SunDS, Oracle Directory Server Enterprise Edition, IBM Security Directory Server, and OpenLDAP.
Because it is based on JNDI, the LDAP connector is restricted to the attribute types that are supported by JNDI. JNDI supports only strings and an array of bytes. If you attempt to use different attribute value types, the connector throws a malformed attribute value exception. For more information, see the corresponding JNDI documentation.
Configure the LDAP Connector
Important
Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.
Create a connector configuration by using the Admin UI:
Select Configure > Connectors > New Connector and select LDAP Connector - 1.5.20.12 as the connector type.
Alternatively, configure the connector with a configuration file.
IDM provides several sample LDAP connector configurations in the
path/to/openidm/samples/example-configurations/provisioners/
directory. Copy one of the sample connector configurations to your project'sconf
directory, and adjust it to match your LDAP environment:provisioner.openicf-ldap.json
— a sample LDAP connector configuration for a generic LDAP server.provisioner.openicf-dsldap.json
— a sample LDAP connector configuration for a ForgeRock Directory Services (DS) server.provisioner.openicf-adldap.json
— a sample LDAP connector configuration for an Active Directory server.
You should be able to adapt one of these sample configurations for any LDAPv3-compliant server.
This configuration shows the properties for an LDAP connector connecting to DS. For more information about the properties that affect synchronization, see "Control What the LDAP Connector Synchronizes". For a complete list of the configuration properties for the LDAP connector, see "LDAP Connector Configuration":
"configurationProperties" : { "host" : "localhost", "port" : 1389, "ssl" : false, "startTLS" : false, "privateKeyAlias" : null, "alternateKeyStore" : null, "alternateKeyStoreType" : null, "alternateKeyStorePassword" : null, "principal" : "uid=admin", "credentials" : "password", "baseContexts" : [ "dc=example,dc=com" ], "baseContextsToSynchronize" : [ "dc=example,dc=com" ], "accountSearchFilter" : null, "accountSynchronizationFilter" : null, "groupSearchFilter" : null, "groupSynchronizationFilter" : null, "removeLogEntryObjectClassFromFilter" : true, "modifiersNamesToFilterOut" : [ ], "changeLogBlockSize" : 100, "attributesToSynchronize" : [ ], "changeNumberAttribute" : "changeNumber", "filterWithOrInsteadOfAnd" : false, "objectClassesToSynchronize" : [ "inetOrgPerson" ], "vlvSortAttribute" : "uid", "passwordAttribute" : "userPassword", "useBlocks" : false, "maintainPosixGroupMembership" : false, "failover" : [ ], "readSchema" : true, "accountObjectClasses" : [ "top", "person", "organizationalPerson", "inetOrgPerson" ], "accountUserNameAttributes" : [ "uid" ], "groupMemberAttribute" : "uniqueMember", "passwordHashAlgorithm" : null, "usePagedResultControl" : true, "blockSize" : 100, "uidAttribute" : "entryUUID", "maintainLdapGroupMembership" : false, "respectResourcePasswordPolicyChangeAfterReset" : false },
host
The host name or IP address of the server on which the LDAP instance is running.
port
The port on which the LDAP server listens for LDAP requests. The sample configuration specifies a default port of 1389.
ssl
If
true
, the specified port listens for LDAPS connections.For instructions on using the LDAP connector over SSL, see "Configure the LDAP Connector to Use SSL and StartTLS".
startTLS
Specifies whether to use the startTLS operation to initiate a TLS/SSL session. To use startTLS, set
"startTLS":true,
and"ssl":false
. Your connection should use the insecure LDAP port (typically389
or1389
for a DS server).Specify the certificates that should be used for authentication, as described in "Configure the LDAP Connector to Use SSL and StartTLS".
principal
The bind DN that is used to connect to the LDAP server.
credentials
The password of the
principal
that is used to connect to the LDAP server.baseContexts
One or more starting points in the LDAP tree that will be used when searching the tree. Searches are performed when discovering users from the LDAP server or when looking for the groups of which a user is a member. During reconciliation operations, IDM searches through the base contexts listed in this property for changes. (See also "Control What the LDAP Connector Synchronizes").
baseContextsToSynchronize
One or more starting points in the LDAP tree that will be used to determine if a change should be synchronized. During liveSync operations, IDM searches through the base contexts listed in this property for changes. If no value is specified here, the values in listed in the
baseContexts
property are used. (See also "Control What the LDAP Connector Synchronizes").accountSynchronizationFilter
Used during synchronization actions to filter out LDAP accounts. (See also "Control What the LDAP Connector Synchronizes").
accountObjectClasses
This property lists all the object classes that represent an account. If this property has multiple values, an
AND
filter is used to determine the affected entries. For example, if the value of this property is["organizationalPerson", "inetOrgPerson"]
, any entry with the object classorganizationalPerson
AND the object classinetOrgPerson
is considered as an account entry. You can override the value of this property by specifying the user object classes during the create operation.If no object class is specified when you create a user, this property is used as the default list of object classes for the new entry.
accountSearchFilter
Search filter that user accounts must match. (See also "Control What the LDAP Connector Synchronizes").
accountUserNameAttributes
Attributes holding the account's user name. Used during authentication to find the LDAP entry matching the user name.
attributesToSynchronize
List of attributes used during object synchronization. IDM ignores change log updates that do not include any of the specified attributes. If empty, IDM considers all changes. (See also "Control What the LDAP Connector Synchronizes").
blockSize
Block size for simple paged results and VLV index searches, reflecting the maximum number of entries retrieved at any one time.
changeLogBlockSize
Block size used when fetching change log entries.
changeNumberAttribute
Change log attribute containing the last change number.
failover
LDAP URLs specifying alternative LDAP servers to connect to if IDM cannot connect to the primary LDAP server specified in the
host
andport
properties.filterWithOrInsteadOfAnd
In most cases, the filter to fetch change log entries is AND-based. If this property is set, the filter ORs the required change numbers instead.
groupMemberAttribute
LDAP attribute holding members for non-POSIX static groups.
groupSearchFilter
Search filter that group entries must match.
maintainLdapGroupMembership
If
true
, IDM modifies group membership when entries are renamed or deleted.Does not apply to Active Directory.
In the sample LDAP connector configuration, this property is set to
false
. This means that LDAP group membership is not modified when entries are renamed or deleted in IDM. To ensure that entries are removed from LDAP groups when the entries are deleted, set this property totrue
or enable referential integrity on the LDAP server. For information about configuring referential integrity in DS, see Referential Integrity in the Configuration Guide for ForgeRock Directory Services.maintainPosixGroupMembership
If
true
, IDM modifies POSIX group membership when entries are renamed or deleted.modifiersNamesToFilterOut
Use this property to avoid loops caused by changes made to managed user objects being synchronized. For more information, see "Control What the LDAP Connector Synchronizes".
objectClassesToSynchronize
IDM synchronizes only entries that have these object classes. See also "Control What the LDAP Connector Synchronizes".
passwordAttribute
Attribute to which IDM writes the predefined
PASSWORD
attribute.passwordHashAlgorithm
Hash password values with the specified algorithm, if the LDAP server stores them in clear text.
The hash algorithm can be one of the following:
NONE
- Clear textWIN-AD
- Used for password changes to Active DirectorySHA
- Secure Hash AlgorithmSHA-1
- A 160-bit hash algorithm that resembles the MD5 algorithmSSHA
- Salted SHAMD5
- A 128-bit message-digest algorithmSMD5
- Salted MD5
readSchema
If
true
, read the schema from the LDAP server.This property is used only during the connector setup, to generate the object types.
If this property is
false
, the LDAP connector provides a basic default schema that can manage LDAP users and groups. The default schema mapsinetOrgPerson
to the OpenICF__ACCOUNT__
property, andgroupOfUniqueNames
to the OpenICF__GROUP__
property. The following LDAP object classes are also included in the default schema:organization
organizationalUnit
person
organizationalPerson
account
groupOfNames
removeLogEntryObjectClassFromFilter
If
true
, the filter to fetch change log entries does not contain thechangeLogEntry
object class, and IDM expects no entries with other object types in the change log. The default setting istrue
.respectResourcePasswordPolicyChangeAfterReset
If
true
, bind with the Password Expired and Password Policy controls, and throwPasswordExpiredException
and other exceptions appropriately.uidAttribute
Specifies the LDAP attribute that should be used as the immutable ID for the entry. You can use a DN (or any unique attribute) for the
_id
. As a best practice, you should use an attribute that is both unique and immutable, such as theentryUUID
. For a DS resource, you must use theentryUUID
as theuidAttribute
, otherwise you might encounter problems with synchronizing delete operations.useBlocks
If
useBlocks
isfalse
, no pagination is used. IfuseBlocks
istrue
, the connector uses block-based LDAP controls, either the simple paged results control, or the virtual list view control, depending on the setting of theusePagedResultControl
property.usePagedResultControl
Taken into account only if
useBlocks
istrue
. IfusePagedResultControl
isfalse
, the connector uses the virtual list view (VLV) control, if it is available. IfusePagedResultControl
istrue
, the connector uses the simple paged results control for search operations.useTimestampsForSync
If
true
, use timestamps for liveSync operations, instead of the change log.By default, the LDAP connector has a change log strategy for LDAP servers that support a change log, such as ForgeRock Directory Services (DS) and Oracle Directory Server Enterprise Edition. If the LDAP server does not support a change log, or if the change log is disabled, liveSync for create and modify operations can still occur, based on the timestamps of modifications.
Regardless of the value of
useTimestampsForSync
, the connector uses a timestamp strategy for liveSync for the following LDAP server types:MS Active Directory Global Catalog
OpenLDAP
Unknown
An LDAP server type is marked unknown if it is anything other than IBM, Novell, UnboundIDD, RedHat/Fedora 389, CA LDAP, OpenDS, ForgeRock OpenDJ / DS, Sun DSEE Directory, MS Active Directory, MS Active Directory Lightweight Directory Services (LDS), MS Active Directory Global Catalog, or OpenLDAP.
vlvSortAttribute
Attribute used as the sort key for virtual list view.
sendCAUDTxId
If
true
, propagate the Common Audit Transaction ID to a DS server.
Configure the LDAP Connector to Use SSL and StartTLS
Important
Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.
To use the LDAP connector over SSL, update your connector configuration as follows:
For a connection over SSL, set the
ssl
property totrue
and set theport
to a secure port, for example,636
.To initiate a connection using startTLS, set
"startTLS":true,
and"ssl":false
. Set theport
to an insecure LDAP port, for example,389
.If you are using a CA-signed server certificate, add that certificate to the IDM truststore, for example:
keytool \ -importcert \ -alias server-cert \ -keystore /path/to/openidm/security/truststore \ -storepass changeit \ -file /path/to/server-cert.crt
Specify the certificate that the LDAP connector will use to authenticate to the remote LDAP server.
By default, the LDAP connector uses the self-signed certificate that is generated in the IDM keystore when IDM first starts up. You have two options to change this default behavior:
Set the
privateKeyAlias
to the alias of a certificate in the IDM keystore. The alias name is case-sensitive.If you set
privateKeyAlias
tonull
, no private key is sent during the SSL handshake, so only the server certificate is used. You must import the server certificate into the IDM truststore, as shown in the previous step.If
privateKeyAlias
is set to an alias within the IDM keystore, the connector uses that private key for SSL mutual authentication.Specify a different keystore for the connector.
If you do not want to use the default IDM keystore, set the following properties:
alternateKeyStore
- specifies the full path to an alternate keystore.alternateKeyStoreType
- specifies alternate keystore type. Valid values areJKS
,JCEKS
andPKCS12
.alternateKeyStorePassword
- specifies password for the alternate keystore.
(Optional) Enable hostname verification to prevent a third party from manipulating DNS entries or spoofing the LDAP Server IP.
When hostname verification is enabled, the connector compares the hostname in the certificate
subject
andsubjectAltName
with a simple hostname pattern defined in thehostNameVerification
property.To enable hostname verification, set
"hostNameVerification" : true
and set thehostNameVerification
property to the hostname you want to match. If the pattern matches, the connector is initialized successfully. If the pattern does not match, connector initialization throws an error. ThehostNameVerification
property supports wild card matching.Assume, for example, a server certificate principal hostname of
server1.example.com
. With the following connector configuration, IDM starts up and the connector is initialized:"configurationProperties" : { ... "hostNameVerification" : true, "hostNameVerifierPattern" : "server1.example.com", ... }
Similarly, with the following connector configuration, IDM starts up and the connector is initialized:
"configurationProperties" : { ... "hostNameVerification" : true, "hostNameVerifierPattern" : "*.example.com", ... }
With the following connector configuration, IDM starts up but connector initialization throws an error:
"configurationProperties" : { ... "hostNameVerification" : true, "hostNameVerifierPattern" : "server2.example.com", ... }
The error returned is similar to the following:
The host name from the server certificate'CN=server1.example.com' does not match the provided pattern 'server2.example.com'
Control What the LDAP Connector Synchronizes
Important
Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.
To control the set of LDAP entries that are affected by reconciliation and automatic synchronization operations, set the following properties in the provisioner configuration. Automatic synchronization includes liveSync (synchronization of changes from the LDAP server to IDM) and implicit sync (synchronization from IDM to the LDAP server). For more information, see "Types of Synchronization".
accountSearchFilter
Only user accounts that match this filter are searched, and therefore affected by reconciliation and synchronization operations. If you do not set this property, all accounts within the base contexts specified previously are searched.
accountSynchronizationFilter
This property is used during reconciliation and automatic synchronization operations, and filters out any LDAP accounts that you specifically want to exclude from these operations.
attributesToSynchronize
During automatic synchronization operations, only the attributes listed here are considered for changes. Objects that include these attributes are synchronized. Objects that do not include these attributes are ignored. If this property is not set, IDM considers changes to all attributes specified in the mapping.
This attribute works only with LDAP servers that log changes in a change log, not with servers (such as Active Directory) that use other mechanisms to track changes.
baseContexts
The starting points in the LDAP tree that are used when searching the directory tree; for example,
dc=example,dc=com
. These base contexts must include the set of users and the set of groups that must be searched during reconciliation operations.baseContextsToSynchronize
The starting points in the LDAP tree that are used to determine if a change should be synchronized. This property is used only for automatic synchronization operations. Only entries that fall under these base contexts are considered during synchronization operations.
modifiersNamesToFilterOut
This property lets you define a list of DNs. During synchronization operations, the connector ignores changes made by these DNs.
When a managed user object is updated, and that change is synchronized to the LDAP server, the change made on the LDAP server is recorded in the change log. A liveSync operation picks up the change, and attempts to replay the change on the managed user object, effectively resulting in a loop of updates.
To avoid this situation, you can specify a unique user in your LDAP directory, that will be used only for the LDAP connector. The unique user must be something other than
uid=admin
; for example,cn=idmuser
. You can then include that user DN as the value ofmodifiersNamesToFilterOut
. When a change is made through the LDAP connector, and that change is recorded in the change log, the modifier's name (cn=idmuser
) is flagged, and IDM does not attempt to replay the change back to the managed user repository. So, you are effectively indicating that IDM should not synchronize changes back to managed user that originated from managed user, thus preventing the update loop.This attribute works only with LDAP servers that log changes in a change log, not with servers (such as Active Directory) that use other mechanisms to track changes.
objectClassesToSynchronize
During automatic synchronization operations, only the object classes listed here are considered for changes. IDM ignores change log updates (or changes to managed objects) which do not have any of the object classes listed here.
Use the LDAP Connector With Active Directory
Important
Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.
The LDAP connector provides functionality specifically for managing Active Directory users and groups. The connector can handle the following operational attributes to manage Active Directory accounts:
__ENABLE__
Uses the
userAccountControl
attribute to get or set the account status of an object.The LDAP connector reads the
userAccountControl
to determine if an account is enabled or disabled. The connector modifies the value of theuserAccountControl
attribute if IDM changes the value of__ENABLE__
.__ACCOUNT_EXPIRES__
Sets the
accountExpires
attribute of an Active Directory object to reset an expired account, or to set a future expiration date.To set an account that never expires, set
"__ACCOUNT_EXPIRES__": "0"
.To set an expiration date, set
"__ACCOUNT_EXPIRES__": "date"
, wheredate
is in ISO8601 format. For example:curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request PUT \ --data '{ "__ACCOUNT_EXPIRES__": "2020-12-31T00:00:00Z" }' \ "http://localhost:8080/openidm/system/AD/account/e1418d64-096c-4cb0-b903-ebb66562d99d"
{ "sn": "jensen", "__LOCK_OUT__": false, "__ENABLE__": true, "objectGUID": "e1418d64-096c-4cb0-b903-ebb66562d99d", "dn": "CN=bjensen,OU=create,DC=example,DC=com", "accountExpires": "2020-12-31T00:00:00Z" }
__LOCK_OUT__
Uses the
msDS-User-Account-Control-Computed
system attribute to check if a user account has been locked.If IDM sets
__LOCK_OUT__
toFALSE
, the LDAP connector sets the Active DirectorylockoutTime
to0
to unlock the account.If IDM sets
__LOCK_OUT__
toTRUE
, the LDAP connector ignores the change and logs a message.__PASSWORD_EXPIRED__
Uses the
msDS-User-Account-Control-Computed
system attribute to check if a user password has expired.To force password expiration (that is, to force a user to change their password when they next log in), set
pwdLastSet
to0
. The LDAP connector setspwdLastSet
to0
, if IDM sets__PASSWORD_EXPIRED__
toTRUE
.To remove password expiration, set
pwdLastSet
to0
and then to-1
. This sets the value ofpwdLastSet
to the current time. The LDAP connector setspwdLastSet
to-1
if IDM sets__PASSWORD_EXPIRED__
toFALSE
.Note
Active Directory does not allow you to create an enabled account with an expired password. If you are using
__PASSWORD_EXPIRED__
to force a new user to change their password when they next log in, you can create the user account as disabled initially (__ENABLE__=false
). You can then patch the new user account to enable it. You can use the same workaround for synchronization operations, creating new user accounts as disabled, then issuing anopenidm.patch
call in apostCreate
script to enable the account.__CURRENT_PASSWORD__
For a password change request, the connector supplies the
__CURRENT_PASSWORD__
, along with the new password. The connector can also do a password reset where only the new password is supplied.
The sample connector configuration file (openidm/samples/example-configurations/provisioners/provisioner.openicf-adldap.json
) includes these operational attributes. Note that the passwordAttribute
property in this provisioner file is set to unicodePwd
. This property specifies the attribute in Active Directory that holds the user password. When a user's password is changed, the new value is set in this attribute.
Manage Active Directory Users With the LDAP Connector
Important
Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.
If you create or update users in Active Directory, and those user entries include passwords, you must use the LDAP connector over SSL. You cannot create or update an Active Directory user password in clear text. To use the connector over SSL, follow the instructions in "Configure the LDAP Connector to Use SSL and StartTLS".
The following command adds an Active Directory user. The output shows the operational attributes described in the previous section:
curl \ --header "Content-Type: application/json" \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ --data '{ "dn": "CN=Brian Smith,CN=Users,DC=example,DC=com", "cn": "Brian Smith", "sAMAccountName": "bsmith", "userPrincipalName": "bsmith@example.com", "userAccountControl": "512", "givenName": "Brian", "mail": "bsmith@example.com", "__PASSWORD__": "Passw0rd" }' \ http://localhost:8080/openidm/system/ad/account?_action=create
{ "_id": "e1418d64-096c-4cb0-b903-ebb66562d99d", "mobile": null, "postalCode": null, "st": null, "employeeType": [], "objectGUID": "e1418d64-096c-4cb0-b903-ebb66562d99d", "cn": "Brian Smith", "department": null, "l": null, "description": null, "info": null, "manager": null, "sAMAccountName": "bsmith", "sn": null, "whenChanged": "20151217131254.0Z", "userPrincipalName": "bsmith@example.com", "userAccountControl": "512", "__ENABLE__": true, "displayName": null, "givenName": "Brian", "middleName": null, "facsimileTelephoneNumber": null, "lastLogon": "0", "countryCode": "0", "employeeID": null, "co": null, "physicalDeliveryOfficeName": null, "pwdLastSet": "2015-12-17T13:12:54Z", "streetAddress": null, "homePhone": null, "__PASSWORD_NOTREQD__": false, "telephoneNumber": null, "dn": "CN=Brian Smith,CN=Users,DC=example,DC=com", "title": null, "mail": "bsmith@example.com", "postOfficeBox": null, "__SMARTCARD_REQUIRED__": false, "uSNChanged": "86144", "__PASSWORD_EXPIRED__": false, "initials": null, "__LOCK_OUT__": false, "company": null, "employeeNumber": null, "accountExpires": "0", "c": null, "whenCreated": "20151217131254.0Z", "uSNCreated": "86142", "division": null, "groups": [], "__DONT_EXPIRE_PASSWORD__": false, "otherHomePhone": [] }
Important
Previous versions of the LDAP connector appended
<GUID=
to the GUID for Active Directory objects. This behavior ensured compatibility with the legacy .NET connector.The LDAP connector no longer appends
<GUID=
to the object GUID. The new GUID format is compatible with objects created using the AD Powershell connector; for example,e1418d64-096c-4cb0-b903-ebb66562d99d
. In existing deployments, this might mean that your links are incompatible with the new GUID format. To update links to the new format, run a reconciliation operation. To retain the legacy behavior, set"useOldADGUIDFormat" : true
in your provisioner file.You cannot sort by
_id
when you return results from an Active Directory (or Active Directory LDS) server. The_id
attribute used by default is theobjectGUID
, which is a binary attribute, and cannot be used for sorting.When you page and sort query results (using the
sortKeys
parameter), thepagedResultsCookie
applies only to the first connection that makes the sorted, paginated query. Active Directory (and AD LDS) build a cached index for sorted searches, which is attached to the original connection.
Note that the command sets the userAccountControl
to 512
, which is an enabled
account. The value of the userAccountControl
determines the account policy. The following list describes the common values for the userAccountControl
.
512
Enabled account.
514
Disabled account.
544
Enabled account, password not required.
546
Disabled account, password not required.
66048
Enabled account, password does not expire.
66050
Disabled account, password does not expire.
66080
Enabled account, password does not expire and is not required.
66082
Disabled account, password does not expire and is not required.
262656
Enabled account, smartcard required.
262658
Disabled account, smartcard required.
262688
Enabled account, smartcard required, password not required.
262690
Disabled account, smartcard required, password not required.
328192
Enabled account, smartcard required, password does not expire.
328192
Enabled account, smartcard required, password does not expire.
328194
Disabled account, smartcard required, password does not expire.
328224
Enabled account, smartcard required, password does not expire and is not required.
328226
Disabled account, smartcard required, password does not expire and is not required.
Manage Active Directory Groups With the LDAP Connector
Important
Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.
The following command creates a basic Active Directory group with the LDAP connector:
curl \ --header "Content-Type: application/json" \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ --data '{ "dn": "CN=Employees,DC=example,DC=com" }' \ http://localhost:8080/openidm/system/ad/group?_action=create
{ "_id": "240da4e9-59d8-1547-ad86-29f5b2b5114d" }
The LDAP connector exposes two special attributes to handle Active Directory group scope and type: GROUP_SCOPE
and GROUP_TYPE
.
The GROUP_SCOPE
attribute is defined in the provisioner configuration as follows:
... "__GROUP_SCOPE__" : { "type" : "string", "nativeName" : "__GROUP_SCOPE__", "nativeType" : "string" },
The value of the GROUP_SCOPE
attribute can be global
, domain
, or universal
. If no group scope is set when the group is created, the scope is global
by default. For more information about the different group scopes, see the corresponding Microsoft documentation.
The GROUP_TYPE
attribute is defined in the provisioner configuration as follows:
... "__GROUP_TYPE__" : { "type" : "string", "nativeName" : "__GROUP_TYPE__", "nativeType" : "string" },
The value of the GROUP_TYPE
attribute can be security
or distribution
. If no group type is set when the group is created, the type is security
by default. For more information about the different group types, see the corresponding Microsoft documentation.
The following example creates a new distribution group, with universal scope:
curl \ --header "Content-Type: application/json" \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ --data '{ "dn": "CN=NewGroup,DC=example,DC=com", "__GROUP_SCOPE__": "universal", "__GROUP_TYPE__": "distribution" }' \ http://localhost:8080/openidm/system/ad/group?_action=create
{ "_id": "f189df8a-276f-9147-8ad5-055b1580cbcb" }
Handle Active Directory Dates
Important
Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.
Most dates in Active Directory are represented as the number of 100-nanosecond intervals since January 1, 1601 (UTC). For example:
pwdLastSet: 130698687542272930
IDM generally represents dates as an ISO 8601-compliant string with yyyy-MM-dd'T'HH:mm:ssZ
format. For example:
2015-03-02T20:17:48Z
The generic LDAP connector therefore converts any dates from Active Directory to ISO 8601 format, for fields such as pwdLastSet
, accountExpires
, lockoutTime
, and lastLogon
.
Multiple Active Directory Domains
Important
Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.
In a multi-domain Active Directory Domain Services (AD DS) forest, the global catalog (GC) provides a read-only (searchable) representation of every object in the forest. Each domain controller (DC) in the forest stores a writable replica of the objects in its domain. Therefore, a DC can locate only the objects in its domain.
If your Active Directory deployment has only one domain controller, you can configure the connector to connect to that single domain controller. If your deployment spans multiple domains, you must configure the connector to connect to the Global Catalog (GC) to have a comprehensive view of all the domains.
Using a GC as the authoritative data source has the following limitations:
Only a subset of attributes is replicated from other domains to the GC.
Certain attributes required by the LDAP connector might be missing. To avoid this problem, modify the Active Directory schema to ensure that the required attributes are replicated to the GC.
Delete operations are not detected immediately.
A liveSync operation will therefore not update IDM with the result of a delete operation. Delete operations are detected by a reconciliation operation, so data stores are only temporarily "out of sync" with regard to deletes.
Not all group types are supported.
Group membership information is replicated to the GC for universal groups only. You must therefore use universal groups if your directory service has more than one domain.
Note
You can use the USN
value for liveSync but must connect to the GC in this case, and ensure that you never failover to a different GC or to a DC. Using the USN for liveSync instead of the timestamp mechanism is generally preferred, because of the issue with detecting delete operations.
LDAP Search Filters
Important
Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.
The LDAP connector constructs an LDAP search filter using a combination of filters, in the following order:
(& (native filter) (user filter) (object class filter) )
The filter components are as follows:
- Native Filter
The native filter is the query filter that has been translated to an LDAP query. For example,
uid+eq+"user123"
is translated touid=user123
.This part of the filter is processed first.
- User Filter
You can define a user filter with the properties
accountSearchFilter
andgroupSearchFilter
in the connector configuration.These properties enable you to construct a more granular or specific search filter. If a user filter is specified, the connector does not use the object class filter. If no user filter is specified, (
accountSearchFilter
andgroupSearchFilter
set tonull
or absent from the connector configuration), the connector uses the object class filter.- Object Class Filter
This part of the filter includes the object classes that the entry must have in order to be returned by the search.
The
__ACCOUNT__
and__GROUPS__
object classes are defined by the propertiesaccountObjectClasses
andgroupObjectClasses
in the connector configuration. For example, the following configuration indicates that theaccountObjectClasses
include the LDAP object classestop
,person
,organizationalPerson
, andinetOrgPerson
:"configurationProperties" : { ... "accountObjectClasses" : [ "top", "person", "organizationalPerson", "inetOrgPerson" ], ... }
With this configuration, the search filter for accounts is constructed as follows:
(&(objectClass=top)(objectClass=person)(objectClass=organizationalPerson)(objectClass=inetOrgPerson))
If no
accountObjectClasses
orgroupObjectClasses
are defined in the connector configuration, the connector uses the name of the ICF ObjectClass in the filter. For example, an object of typeorganizationUnit
will result in:(&(objectClass=organizationUnit)
OpenICF Interfaces Implemented by the LDAP Connector
The LDAP Connector implements the following OpenICF interfaces.
- Authenticate
Provides simple authentication with two parameters, presumed to be a user name and password.
- Create
Creates an object and its
uid
.- Delete
Deletes an object, referenced by its
uid
.- Resolve Username
Resolves an object by its username and returns the
uid
of the object.- Schema
Describes the object types, operations, and options that the connector supports.
- Script on Connector
Enables an application to run a script in the context of the connector. Any script that runs on the connector has the following characteristics:
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration.The script has access to any script-arguments passed in by the application.
- Search
Searches the target resource for all objects that match the specified object class and filter.
- Sync
Polls the target resource for synchronization events, that is, native changes to objects on the target resource.
- Test
Tests the connector configuration. Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
Updates (modifies or replaces) objects on a target resource.
LDAP Connector Configuration
The LDAP Connector has the following configurable properties.
Configuration properties
Property | Type | Default | Encrypted [a] | Required [b] | |
---|---|---|---|---|---|
filterWithOrInsteadOfAnd | boolean | false |
| ||
Normally the filter used to fetch change log entries is an and-based filter retrieving an interval of change entries. If this property is set, the filter will or together the required change numbers instead. | |||||
| |||||
objectClassesToSynchronize | String[] | ['inetOrgPerson'] |
| ||
The object classes to synchronize. The change log is for all objects; this filters updates to just the listed object classes. You should not list the superclasses of an object class unless you intend to synchronize objects with any of the superclass values. For example, if only "inetOrgPerson" objects should be synchronized, but the superclasses of "inetOrgPerson" ("person", "organizationalperson" and "top") should be filtered out, then list only "inetOrgPerson" here. All objects in LDAP are subclassed from "top". For this reason, you should never list "top", otherwise no object would be filtered. | |||||
| |||||
baseContextsToSynchronize | String[] | [] |
| ||
One or more starting points in the LDAP tree that will be used to determine if a change should be synchronized. The base contexts attribute will be used to synchronize a change if this property is not set. | |||||
| |||||
attributesToSynchronize | String[] | [] |
| ||
The names of the attributes to synchronize. This ignores updates from the change log if they do not update any of the named attributes. For example, if only "department" is listed, then only changes that affect "department" will be processed. All other updates are ignored. If blank (the default), then all changes are processed. | |||||
| |||||
changeNumberAttribute | String | changeNumber |
| ||
The name of the change number attribute in the change log entry. | |||||
| |||||
modifiersNamesToFilterOut | String[] | [] |
| ||
The list of names (DNs) to filter from the changes. Changes with the attribute "modifiersName" that match entries in this list will be filtered out. The standard value is the administrator name used by this adapter, to prevent loops. Entries should be of the format "cn=Directory Manager". | |||||
| |||||
credentials | GuardedString | null | |||
Password for the principal. | |||||
| |||||
changeLogBlockSize | int | 100 |
| ||
The number of change log entries to fetch per query. | |||||
| |||||
useTimestampsForSync | boolean | false |
| ||
If true, the connector will use the createTimestamp and modifyTimestamp system attributes to detect changes (Create/Update) on the directory instead of native change detection mechanism (cn=changelog on OpenDJ or Update Sequence Number -USN- on Active Directory for instance). Default value is false. | |||||
| |||||
accountSynchronizationFilter | String | null |
| ||
An optional LDAP filter for the objects to synchronize. Because the change log is for all objects, this filter updates only objects that match the specified filter. If you specify a filter, an object will be synchronized only if it matches the filter and includes a synchronized object class. | |||||
| |||||
removeLogEntryObjectClassFromFilter | boolean | true |
| ||
If this property is set (the default), the filter used to fetch change log entries does not contain the "changeLogEntry" object class, expecting that there are no entries of other object types in the change log. | |||||
| |||||
alternateKeyStorePassword | GuardedString | null | |||
Password to use for the alternate keystore | |||||
| |||||
groupSynchronizationFilter | String | null |
| ||
An optional LDAP filter for the objects to synchronize. Because the change log is for all objects, this filter updates only objects that match the specified filter. If you specify a filter, an object will be synchronized only if it matches the filter and includes a synchronized object class. | |||||
| |||||
groupMemberAttribute | String | uniqueMember | |||
The name of the group attribute that will be updated with the distinguished name of the user when the user is added to the group. | |||||
| |||||
accountSearchFilter | String | null | |||
An optional LDAP filter to control which accounts are returned from the LDAP resource. If no filter is specified, only accounts that include all specified object classes are returned. | |||||
| |||||
privateKeyAlias | String | null | |||
Specifies the name of a private key alias from the keystore that should be used for SSL mutual authentication. If null, no private key is sent during SSL handshake so only server cert is used. This alias name is case sensitive. | |||||
| |||||
ssl | boolean | false | |||
Select the check box to connect to the LDAP server using SSL. | |||||
| |||||
maintainPosixGroupMembership | boolean | false | |||
When enabled and a user is renamed or deleted, update any POSIX groups to which the user belongs to reflect the new name. Otherwise, the LDAP resource must maintain referential integrity with respect to group membership. | |||||
| |||||
checkAliveMinInterval | long | 60 | |||
The minimum interval (seconds) at which the target directory is polled when a connection is reused from the pool. Defaults to 60 seconds. | |||||
| |||||
groupSearchFilter | String | null | |||
An optional LDAP filter to control which groups are returned from the LDAP resource. If no filter is specified, only groups that include all specified object classes are returned. | |||||
| |||||
referralsHandling | String | follow | |||
Defines how to handle LDAP referrals. Possible values can be follow, ignore or throw. | |||||
| |||||
host | String | null | |||
The name or IP address of the host where the LDAP server is running. | |||||
| |||||
maintainLdapGroupMembership | boolean | false | |||
When enabled and a user is renamed or deleted, update any LDAP groups to which the user belongs to reflect the new name. Otherwise, the LDAP resource must maintain referential integrity with respect to group membership. | |||||
| |||||
resetSyncToken | String | never | |||
Connector can reset the sync token if ever the value of the sync token is greater than the last change number in the directory changelog. Defaults to "never" (no reset). If set to "first" it will reset the sync token to the value of the firstChangeNumber changelog attribute. If set to "last" it will reset the sync token to the value of the lastChangeNumber changelog attribute. | |||||
| |||||
vlvSortAttribute | String | uid | |||
Specify the sort attribute to use for VLV indexes on the resource. | |||||
| |||||
convertGTToISO8601 | String[] | ['whenCreated', 'whenChanged'] | |||
Converts the Greenwich Time to ISO8601 format | |||||
| |||||
baseContexts | String[] | [] | |||
One or more starting points in the LDAP tree that will be used when searching the tree. Searches are performed when discovering users from the LDAP server or when looking for the groups of which a user is a member. | |||||
| |||||
hostNameVerification | boolean | false | |||
If true, the connector will verify the hostname in the certificate (subject + alternative subject) against the defined hostNameVerifierPattern. | |||||
| |||||
blockSize | int | 100 | |||
The maximum number of entries that can be in a block when retrieving entries in blocks. | |||||
| |||||
groupObjectClasses | String[] | ['top', 'groupOfUniqueNames'] | |||
The default list of object classes that will be used when creating new group objects in the LDAP tree. This can be overridden by specifying the group object classes during the Create operation. | |||||
| |||||
accountUserNameAttributes | String[] | ['uid', 'cn'] | |||
Attribute or attributes which holds the account's user name. They will be used when authenticating to find the LDAP entry for the user name to authenticate. | |||||
| |||||
failover | String[] | [] | |||
List all servers that should be used for failover in case the preferred server fails. If the preferred server fails, JNDI will connect to the next available server in the list. List all servers in the form of "ldap://ldap.example.com:389/", which follows the standard LDAP v3 URLs described in RFC 2255. Only the host and port parts of the URL are relevant in this setting. | |||||
| |||||
port | int | 389 | |||
TCP/IP port number used to communicate with the LDAP server. | |||||
| |||||
convertADIntervalToISO8601 | String[] | ['pwdLastSet', 'accountExpires', 'lockoutTime', 'lastLogon'] | |||
Converts the AD Interval to ISO8601 | |||||
| |||||
hostNameVerifierPattern | String | null | |||
A simple pattern used to match the hostname from the certificate. It can contains * character (server1.example.com, *.example.com) | |||||
| |||||
passwordAttribute | String | userPassword | |||
The name of the LDAP attribute that holds the password. When changing a users password, the new password is set to this attribute. | |||||
| |||||
useDNSSRVRecord | boolean | false | |||
If true, the connector will do a DNS query to find SRV records associated with the value set for host property ("_ldap._tcp.example.com" for example). Defaults to false. | |||||
| |||||
getGroupMemberId | boolean | false | |||
Specifies whether to add an extra _memberId attribute to get the group members __UID__. CAUTION: Setting this property to true can incur a large performance cost on group handling. | |||||
| |||||
lastCheckAlive | long | 1670009912790 | |||
The last time the connector was checked to see if it was alive | |||||
| |||||
ldapGroupsUseStaticGroups | boolean | false | |||
When set to true, The ldapGroups attribute will search group membership through static groups only. If false, it will leverage the "memberOf" attribute of an object (defaults to true). | |||||
| |||||
startTLS | boolean | false | |||
Specifies whether to use the startTLS operation to initiate a TLS/SSL session. | |||||
| |||||
allowTreeDelete | boolean | false | |||
Connector can delete an entry (node) with leaf entry if this value is set to true (defaults to false). The LDAP control LDAP_SERVER_TREE_DELETE_OID (1.2.840.113556.1.4.805) is used. | |||||
| |||||
respectResourcePasswordPolicyChangeAfterReset | boolean | false | |||
When this resource is specified in a Login Module (i.e., this resource is a pass-through authentication target) and the resource's password policy is configured for change-after-reset, a user whose resource account password has been administratively reset will be required to change that password after successfully authenticating. | |||||
| |||||
uidAttribute | String | entryUUID | |||
The name of the LDAP attribute that is mapped to the OpenICF UID attribute. | |||||
| |||||
principal | String | null | |||
The distinguished name with which to authenticate to the LDAP server. | |||||
| |||||
accountObjectClasses | String[] | ['top', 'person', 'organizationalPerson', 'inetOrgPerson'] | |||
The default list of object classes that will be used when creating new user objects in the LDAP tree. This can be overridden by specifying the user object classes during the Create operation. | |||||
| |||||
alternateKeyStoreType | String | null | |||
Defines the type of the alternate key store. Valid values are JKS, JCEKS and PKCS12 | |||||
| |||||
passwordHashAlgorithm | String | null | |||
Indicates the algorithm that the Identity system should use to hash the password. Currently supported values are SSHA, SHA, SMD5, MD5 and WIN-AD (when AD is the target). A blank value indicates that the system will not hash passwords. This will cause clear text passwords to be stored in LDAP unless the LDAP server performs the hash (as Forgerocks OpenDJ does, for example). | |||||
| |||||
alternateKeyStore | String | null | |||
Defines the filename of an alternate keystore. If specified, the connector will not use the default keystore specified by the javax.net.ssl.keyStore property. | |||||
| |||||
authType | String | simple | |||
The authentication mechanism to use: Simple or SASL-GSSAPI. Defaults to "simple". | |||||
| |||||
connectionTimeout | int | 30000 | |||
The timeout (in ms) before the connection attempt is aborted. | |||||
| |||||
useBlocks | boolean | false | |||
Specifies whether to use block-based LDAP controls, like the simple paged results or VLV control. When performing search operations on large numbers of entries, the entries are returned in blocks to reduce the amount of memory used by the operation. | |||||
| |||||
readSchema | boolean | true | |||
If true, the connector will read the schema from the server. If false, the connector will provide a default schema based on the object classes in the configuration. This property must be true in order to use extended object classes. | |||||
| |||||
usePagedResultControl | boolean | false | |||
When enabled, the LDAP Paged Results control is preferred over the VLV control when retrieving entries. If disabled, paged queries will be ignored. | |||||
| |||||
useOldADGUIDFormat | boolean | false | |||
The connector used to transform the AD ObjectGUID in the form <GUID=xxxxxx>. It now used dashed notation (xxxx-xx-xx-xxxx-xxxxxx) by default. Set to true to keep the old format. | |||||
| |||||
sendCAUDTxId | boolean | false | |||
Connector can send the Common Audit Transaction Id (if present) to the target OpenDJ server when this value is set to true (defaults to false). The LDAP control TransactionIdControl (1.3.6.1.4.1.36733.2.1.5.1) is used. | |||||
| |||||
gssapiLoginContext | String | null | |||
Defines the name used in the JAAS configuration file to define the JAAS login configuration. If null, it defaults to "org.identityconnectors.ldap.LdapConnector". | |||||
| |||||
[a] Indicates whether the property value is considered confidential, and therefore encrypted in OpenIDM. [b] A list of operations in this column indicates that the property is required for those operations. |