LDAP Connector Reference¶ Connection configuration¶ The connection is used to establish a connection to the LDAP instance. The LDAP API requires all requests to be authenticated as a user. LDAP Connection Parameter Name Description Required providerUrl The URL of the LDAP server. Instead of just one URL, you can also specify a space-separated list of URLs. In this case, the LDAP connector will attempt to use each URL in turn until it is able to create a successful connection. Yes securityPrincipal The Distinguished Name (DN) of the admin of the LDAP Server. Yes securityCredentials The password of the LDAP admin. Yes secureConnection Specifies whether to enable a secure connection. By default, this is set to false. No disableSSLCertificateChecking Indicates whether the certificate is enabled (true) or disabled (false).By default, this is set to false. No timeout Specifies the timeout duration for the LDAP request. The default value is 30000ms. No connectionPoolingEnabled Specifies whether connection pooling is enabled (true) or disabled (false). The default value is false. No connectionPoolingProtocol Specifies a space-separated list of protocol types for connections that can be pooled. Valid values are plain and ssl No connectionPoolingInitSize The number of connections per connection identity to create when initially creating a connection for the identity. No connectionPoolingMaxSize The maximum number of connections per connection identity that can be maintained concurrently. No binaryAttributes A list of space-separated attribute names that should be treated as binary attributes. The values of these attributes will be returned as base64-encoded strings. Note: This configuration is available from LDAP connector version 2.0.3 and above. objectGUID is treated as a binary attribute by default and it will be returned as UUID string. No Sample configuration <ldap.init> <providerUrl>{$ctx:providerUrl}</providerUrl> <securityPrincipal>{$ctx:securityPrincipal}</securityPrincipal> <securityCredentials>{$ctx:securityCredentials}</securityCredentials> </ldap.init> Sample request { "providerUrl":"ldap://localhost:389/", "securityPrincipal":"uid=admin,ou=system", "securityCredentials":"adminpassword" } You can follow the steps below to import your LDAP certificate into the WSO2 Integrator: MI client’s keystore as follows: To encrypt the connections, you need to configure a certificate authority and use it to sign the keys for the LDAP server. See the How To Encrypt OpenLDAP Connections Using STARTTLS documentation for more info. Use the following command to import the certificate into the integration server's client keystore. keytool -importcert -file <certificate file> -keystore <PRODUCT_HOME>/repository/resources/security/client-truststore.jks -alias "LDAP" Restart the server and deploy the LDAP configuration. Ensuring secure data Secure Vault is supported for encrypting passwords. See, Working with Secrets on integrating and using Secure Vault. User authentication¶ ldap.authenticateLDAP authentication is a major requirement in most LDAP based applications. The authenticate operation simplifies the LDAP authentication mechanism. This operation authenticates the provided Distinguished Name(DN) and password against the LDAP server, and returns either a success or failure response depending on whether the authentication was successful or not. Parameter Name Description Required dn The distinguished name of the user. Yes password The password of the user. Yes Sample configuration <ldap.authenticate> <dn>{$ctx:dn}</dn> <password>{$ctx:password}</password> </ldap.authenticate> Sample request { "dn":"uid=testDim20,ou=staff,dc=wso2,dc=com", "password":"12345" } Entry Management¶ addThe add operation creates a new LDAP entry in the LDAP server. Parameter Name Description Required objectClass The object class of the new entry. Yes dn The distinguished name of the new entry. This should be a unique DN that does not already exist in the LDAP server. Yes attributes The other attributes of the entry other than the DN. These attributes should be specified as comma separated key-value pairs. Yes Sample configuration <ldap.addEntry> <objectClass>{$ctx:objectClass}</objectClass> <dn>{$ctx:dn}</dn> <attributes>{$ctx:attributes}</attributes> </ldap.addEntry> Sample request { "objectClass":"inetOrgPerson", "dn":"uid=testDim20,ou=staff,dc=wso2,dc=com", "attributes":'{ "mail":"[email protected]", "userPassword":"12345", "sn":"dim", "cn":"dim", "manager":"cn=dimuthuu,ou=Groups,dc=example,dc=com" } } searchThe search operation performs a search for one or more LDAP entities based on the specified search keys. Parameter Name Description Required dn The distinguished name of the entry you need to search. Yes filters The keywords to use in the search. The parameters should be in JSON format as follow: { "uid":"john", "mail":"[email protected]"} Yes objectClass The object class of the new entry. No attributes The attributes of the LDAP entry that should be included in the search result. No onlyOneReference Boolean value whether to guarantee or not only one reference. No limit This allows you to set a limit on the number of search results. If this property is not defined the maximum no of search results will be returned. No allowEmptySearchResult Boolean value to allow an empty search result or throw an exception. If this property is not defined, an exception will be thrown and a fault sequence is executed if the search result is empty. No Sample configuration <ldap.searchEntry> <objectClass>{$ctx:objectClass}</objectClass> <dn>{$ctx:dn}</dn> <filters>{$ctx:filters}</filters> <attributes>{$ctx:attributes}</attributes> </ldap.searchEntry> Sample request { "dn":"ou=sales,dc=example,dc=com", "objectClass":"inetOrgPerson", "attributes":"mail,uid,givenName,manager,objectGUID", "filters":{ "manager":"cn=sales-group,ou=sales,dc=example,dc=com","uid":"rajjaz","createTimestamp >":"20210412000000.0Z"}, "onlyOneReference":"false" } updateThe update operation updates an existing LDAP entry in the LDAP server based on the specified changes. Parameter Name Description Required dn The distinguished name of the entry. Yes mode The mode of the update operation. Possible values are as follows: replace : Replaces an existing attribute with the new attribute that is specified. add : Adds a new attributes remove : Removes an existing attribute. Yes attributes Attributes of the entry to be updated. The attributes to be updated should be specified as comma separated key-value pairs. Yes Sample configuration <ldap.searchEntry> <dn>{$ctx:dn}</dn> <mode>{$ctx:mode}</mode> <attributes>{$ctx:attributes}</attributes> </ldap.searchEntry> Sample request { "dn":"ou=sales,dc=example,dc=com", "mode":"replace", "attributes":"mail,uid,givenName,manager,objectGUID" } deleteThe delete operation deletes an existing LDAP entry from the LDAP server. Parameter Name Description Required dn The distinguished name of the entry to be deleted. Yes Sample configuration <ldap.deleteEntry> <dn>{$ctx:dn}</dn> </ldap.deleteEntry> Sample request { "dn":"ou=sales,dc=example,dc=com", } updateNameThe updateName operation renames an entry in the LDAP directory by changing its distinguished name (DN) on the LDAP server. Parameter Name Description Required oldName The distinguished name of the entry to be deleted. Yes newName The distinguished name of the entry to be deleted. Yes Sample configuration <ldap.updateName> <oldName>{$ctx:oldName}</oldName> <newName>{$ctx:newName}</newName> </ldap.updateName> Sample request { "oldName":"ou=sales,dc=example,dc=com", "newName":"ou=marketing,dc=example,dc=com" } Handle errors¶ The connector may encounter errors during operation execution. When an error occurs, the ERROR_DETAIL property will contain detailed information about the error. You can handle these errors using a Fault Sequence in your integration. For more information, refer to Using Fault Sequences. Error Details Error Code Description 7000001 An error occurred while searching a LDAP entry. 7000002 LDAP root user's credentials are invalid. 7000003 An error occurred while adding a new LDAP entry. 7000004 An error occurred while updating an existing LDAP entry. 7000005 An error occurred while deleting a LDAP entry. 7000006 The LDAP entry that is required to perform the operation does not exist.