Testing the Nodinite LDAP Web API
Validate your Nodinite LDAP Web API installation quickly and confidently using the built-in Swagger UI.
- ✅ Verify LDAP Web API connectivity with built-in Swagger UI
- ✅ Test Active Directory operations using JSON and XML payloads
- ✅ Confirm your connectionId and settings are correct
- ✅ Reach the domain controller with GetDomainControllers, then test credentials with a search
This guide assumes you have completed the Install and Configuration steps.
Before You Begin
Ensure you have completed these prerequisite steps before testing:
- Prerequisites — For IIS hosting, the .NET 10 Hosting Bundle is installed (version 3.1.0 and later)
- Install — The Nodinite LDAP Web API is running in IIS or Azure App Service
- Configuration — You have configured at least one connection in
settings.jsonwith a valid connectionId
Step 1: Open Swagger UI
Navigate to the built-in Swagger UI to explore and test all available API endpoints.
For IIS, use:
http://localhost/LDAPAdapter/swagger/
Replace LDAPAdapter with the virtual directory name you configured during installation. For HTTPS (recommended), use:
https://YOURSERVER/swagger/
Screenshot: The built-in Swagger UI for the Nodinite LDAP Web API.
Tip
If the page returns HTTP Error 500.19 or 500.30 instead of Swagger, the .NET 10 Hosting Bundle is missing or was installed before the IIS features. See Troubleshooting.
Step 2: Set the connectionId
Before executing any LDAP operations, set the connectionId to the GUID you configured in settings.json.
The connectionId identifies which LDAP server and credentials to use for the operation.
Step 3: Test Active Directory Connectivity
Use the GetDomainControllers operation to verify that the API can reach Active Directory. This operation typically does not require administrative rights.
Important
Use a port 389 connection for
GetDomainControllersand the Schema operations. They fail on a port 636 connection.
Set the content type header to match your payload format:
- JSON — Set content type to
application/json - XML — Set content type to
text/xmlorapplication/xml
Note
JSON responses only work from LDAP Web API 4.0.1. In 3.x, every JSON request returns an empty HTTP 500. Use XML with 3.x.
XML Payload
<ns0:LDAP xmlns:ns0="http://integrationsoftware.se/BizTalk/Adapters/LDAP/Request/1.0">
<Batches guid="2B25B9E6-4AF2-4094-9AE7-E1E4C99B6C8D" returnResponseMessageOnExceptions="true">
<Batch guid="3B25B9E6-4AF2-4094-9AE7-E1E4C99B6C8E">
<AD>
<Operations>
<GetDomainControllers/>
</Operations>
</AD>
</Batch>
</Batches>
</ns0:LDAP>
JSON Payload (4.0.1 and later)
In JSON, Operations needs one extra Operations level, because the API converts the object to XML and XML needs one root element. Without it, the request returns HTTP 200 with an empty result.
{
"RequestId": "b7a211d7-20f3-44bc-b078-7f1b6e1c047f",
"ReturnResponseOnExceptions": true,
"Batches": [
{
"continueOnError": false,
"guid": "2b25b9e6-4af2-4094-9ae7-e1e4c99b6c8d",
"AD": {
"Operations": {
"Operations": {
"GetDomainControllers": {}
}
}
}
}
]
}
In JSON:
- Operation attributes use
@, for example{ "GetAllOptionalAttributes": { "@className": "user" } }. - An operation without attributes can be an empty object
{}or an empty string"". ReturnResponseOnExceptionssits at the top level, next toRequestId. It is the JSON name for the XML attributereturnResponseMessageOnExceptions: errors come back in the response instead of as an exception.
Screenshot: Example result from the GetDomainControllers test in Swagger.
Step 4: Verify the Response
A successful response confirms that the Nodinite LDAP Web API can reach the domain controller. It does not test the credentials: GetDomainControllers and the Schema operations ignore AuthenticationType, UserName, and Password. Run Step 5 to test a search.
If the response is empty or returns an error, review your Configuration settings:
DSAServer— DNS name or IP address of your domain controllerDSAServerPort— Use a port 389 connection for this test- JSON on 3.x — Use XML instead (see the note above)
If the configuration is correct but the call times out, test the ports with the TCP and UDP ports user guide.
Step 5: Test a Search
A search uses the connection's credentials and authentication type, so it is the real test of a connection. This request selects up to 5 users from the built-in Users container. Replace the DC value with your domain.
XML Search Payload
<ns0:LDAP xmlns:ns0="http://integrationsoftware.se/BizTalk/Adapters/LDAP/Request/1.0">
<Batches guid="2B25B9E6-4AF2-4094-9AE7-E1E4C99B6C8D" returnResponseMessageOnExceptions="true">
<Batch guid="3B25B9E6-4AF2-4094-9AE7-E1E4C99B6C8E">
<User>
<With OU="CN=Users" DC="DC=wildwest,DC=local" searchScope="Subtree" sizeLimit="5" returnProperties="name"/>
<Operations>
<Select/>
</Operations>
</User>
</Batch>
</Batches>
</ns0:LDAP>
JSON Search Payload (4.0.1 and later)
{
"RequestId": "b7a211d7-20f3-44bc-b078-7f1b6e1c047f",
"ReturnResponseOnExceptions": true,
"Batches": [
{
"continueOnError": false,
"guid": "2b25b9e6-4af2-4094-9ae7-e1e4c99b6c8d",
"User": {
"With": {
"OU": "CN=Users",
"DC": "DC=wildwest,DC=local",
"searchScope": "Subtree",
"sizeLimit": 5,
"returnProperties": "name"
},
"Operations": {
"Operations": {
"Select": {}
}
}
}
}
]
}
Expected result: ReturnStatus Success and up to 5 users.
If the Search Fails
Read the second line of ExceptionMessageExtended. The first line is always the generic "Find objects in directory failed…"; the real cause follows:
Message in ExceptionMessageExtended |
Cause |
|---|---|
The server is not operational |
AuthenticationType doesn't fit the port, see AuthenticationType per port |
The user name or password is incorrect |
Wrong or empty UserName / Password, see Configuration |
Search Tips
- The built-in Users folder is a container, so it is
OU="CN=Users", notOU="OU=Users". CNneeds its prefix:CN="CN=Administrator".- JSON with LDAP.Libraries older than 3.1.1: add
"searchFilter": ""toWithfor Group and OU operations.
Test Everything in One Request (JSON, 4.0.1 and later)
One request can hold several batches. This one runs the three tests in a row on the same connection: GetDomainControllers, a User search, and a Group search, each in its own batch with its own guid. Use a port 389 connection, because GetDomainControllers fails on port 636, and replace the DC value with your domain.
{
"RequestId": "70000000-0000-0000-0000-000000000007",
"ReturnResponseOnExceptions": true,
"Batches": [
{ "guid": "70000000-0000-0000-0000-000000000071", "AD": { "Operations": { "Operations": { "GetDomainControllers": "" } } } },
{
"guid": "70000000-0000-0000-0000-000000000072",
"User": {
"With": { "OU": "CN=Users", "DC": "DC=dev,DC=local", "searchScope": "Subtree", "sizeLimit": 3, "returnProperties": "name" },
"Operations": { "Operations": { "Select": "" } }
}
},
{
"guid": "70000000-0000-0000-0000-000000000073",
"Group": {
"With": { "OU": "CN=Users", "DC": "DC=dev,DC=local", "searchScope": "Subtree", "sizeLimit": 3, "returnProperties": "name" },
"Operations": { "Operations": { "Select": "" } }
}
}
]
}
Expected result: three batches with ReturnStatus Success: the domain controllers, up to 3 users, and up to 3 groups from the built-in Users container. If the first batch succeeds and the others fail, the API reaches the domain controller but the credentials or AuthenticationType are wrong, see If the Search Fails.
Frequently Asked Questions
You will find additional solutions to common problems and the FAQ for the Nodinite LDAP Web API in the Troubleshooting user guide.