LDAP Connector Reference¶
To use the LDAP connector, add the <ldap.init>
element in your configuration before carrying out any other LDAP operations.
ldap.init
The ldap.init operation initializes the connector to interact with an LDAP.
Parameter Name | Description | Required |
---|---|---|
providerUrl | The URL of the LDAP server. | Yes |
securityPrincipal | The Distinguished Name (DN) of the admin of the LDAP Server. | Yes |
securityCredentials | The password of the LDAP admin. | Yes |
secureConnection | The boolean value for the secure connection. | Yes |
disableSSLCertificateChecking | The boolean value to check whether the certificate is enabled or not. | Yes |
Sample configuration
<ldap.init>
<providerUrl>{$ctx:providerUrl}</providerUrl>
<securityPrincipal>{$ctx:securityPrincipal}</securityPrincipal>
<securityCredentials>{$ctx:securityCredentials}</securityCredentials>
<secureConnection>{$ctx:secureConnection}</secureConnection>
<disableSSLCertificateChecking>{$ctx:disableSSLCertificateChecking}</disableSSLCertificateChecking>
</ldap.init>
You can follow the steps below to import your LDAP certificate into wso2ei client’s keystore as follows:
- To encrypt the connections, you need to configure a certificate authority (https://www.digitalocean.com/community/tutorials/how-to-encrypt-openldap-connections-using-starttls) and use it to sign the keys for the LDAP server.
- Use the following command to import the certificate into the EI client keystore.
keytool -importcert -file <certificate file> -keystore <EI>/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 Passwords on integrating and using Secure Vault.
Re-using LDAP configurations
You can save the LDAP configuration as a local entry and then easily reference it with the configKey attribute in your operations. For example, if you saved the above
<ldap.addEntry configKey="MyLDAPConfig"/>
User authentication¶
authenticate
LDAP 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
{
"providerUrl":"ldap://localhost:10389/",
"securityPrincipal":"cn=admin,dc=wso2,dc=com",
"securityCredentials":"comadmin",
"secureConnection":"false",
"disableSSLCertificateChecking":"false",
"application": "ldap",
"operation":"authenticate",
"content":{
"dn":"uid=testDim20,ou=staff,dc=wso2,dc=com",
"password":"12345"
}
}
Authentication success response
<Response xmlns="http://localhost/services/ldap">
<result>
<message>Success</message>
</result>
</Response>
Authentication failure response
<Response xmlns="http://localhost/services/ldap">
<result>
<message>Fail</message>
</result>
</Response>
Error codes
This section describes the connector error codes and their meanings.
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. |
Sample error response
<Fault xmlns="http://localhost/services/ldap">
<error>
<errorCode>700000X</errorCode>
<errorMessage>Error Message</errorMessage>
</error>
</Fault>
CRUD operations¶
addEntry
The addEntry 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
{
"providerUrl":"ldap://localhost:10389/",
"securityPrincipal":"cn=admin,dc=wso2,dc=com",
"securityCredentials":"comadmin",
"secureConnection":"false",
"disableSSLCertificateChecking":"false",
"application":"ldap",
"operation":"createEntity",
"content":{
"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"
}
}
}
searchEntry
The searchEntry operation performs a search for one or more LDAP entities based on the specified search keys.
Parameter Name | Description | Required |
---|---|---|
objectClass | The object class of the new entry. | Yes |
filters | The keywords to use in the search. The parameters should be in JSON format as follow: "filters":{ "uid":"john", "mail":"[email protected]"} | Yes |
dn | The distinguished name of the entry you need to search. | Yes |
attributes | The attributes of the LDAP entry that should be included in the search result. | Yes |
onlyOneReference | Boolean value whether to guarantee or not only one reference. | Yes |
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. | Yes |
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>
<onlyOneReference>{$ctx:onlyOneReference}</onlyOneReference>
<limit>1000</limit>
</ldap.searchEntry>
Sample request
{
"providerUrl":"ldap://server.example.com",
"securityPrincipal":"cn=admin,dc=example,dc=com",
"securityCredentials":"admin",
"secureConnection":"false",
"disableSSLCertificateChecking":"false",
"application":"ldap",
"operation":"searchEntity",
"content":{
"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"},
"onlyOneReference":"false"
}
}
updateEntry
The updateEntry operation updates an existing LDAP entry in the LDAP server based on the specified changes.
Parameter Name | Description | Required |
---|---|---|
mode | The mode of the update operation. Possible values are as follows:
|
Yes |
dn | The distinguished name of the entry. | 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>
<objectClass>{$ctx:objectClass}</objectClass>
<dn>{$ctx:dn}</dn>
<filters>{$ctx:filters}</filters>
<attributes>{$ctx:attributes}</attributes>
<onlyOneReference>{$ctx:onlyOneReference}</onlyOneReference>
<limit>1000</limit>
</ldap.searchEntry>
Sample request
{
"providerUrl":"ldap://server.example.com",
"securityPrincipal":"cn=admin,dc=example,dc=com",
"securityCredentials":"admin",
"secureConnection":"false",
"disableSSLCertificateChecking":"false",
"application":"ldap",
"operation":"searchEntity",
"content":{
"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"},
"onlyOneReference":"false"
}
}
deleteEntry
The deleteEntry 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.searchEntry>
<objectClass>{$ctx:objectClass}</objectClass>
<dn>{$ctx:dn}</dn>
<filters>{$ctx:filters}</filters>
<attributes>{$ctx:attributes}</attributes>
<onlyOneReference>{$ctx:onlyOneReference}</onlyOneReference>
<limit>1000</limit>
</ldap.searchEntry>
Sample request
{
"providerUrl":"ldap://server.example.com",
"securityPrincipal":"cn=admin,dc=example,dc=com",
"securityCredentials":"admin",
"secureConnection":"false",
"disableSSLCertificateChecking":"false",
"application":"ldap",
"operation":"searchEntity",
"content":{
"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"},
"onlyOneReference":"false"
}
}