- 11 minutes to read

Configuring the Nodinite LDAP Adapter for Microsoft BizTalk Server

Unlock the full potential of your Nodinite LDAP Adapter for Microsoft BizTalk Server with proper configuration. This comprehensive guide covers license management, connection configuration methods, SSO setup, XSLT transformations, and send port options for secure and flexible integration.

  • ✅ Centralized license management for compliance and control
  • ✅ Four flexible connection configuration methods with clear priority order
  • ✅ Secure SSO Application setup for password-free deployments
  • ✅ XSLT response transformations without Visual Studio artifacts
  • ✅ Context properties for dynamic runtime control

License

You must provide a valid license key to activate the product. Licenses are available as either full or trial versions.

Each license includes two key properties, in the License information category of the send handler:

  1. Customer name: The licensee's name, which appears in the response message Summary record within the <LicenseInformation> element. Enter this value exactly as provided by Integration Software (case sensitive).
  2. License key: The unique, encrypted license key for your organization.

Add this information to the config file (IS.BizTalk.Adapters.LDAP.Windows.ClientTestUtility_v1_0.exe) for the Test Client and to each send handler associated with the Nodinite LDAP Adapter for Microsoft BizTalk Server in the BizTalk administration console.

Repeat the process for each send handler by selecting the handler and clicking 'Properties'.

Add Send Handler dialog with a BizTalk host selected
Associate the appropriate Host Instance(s) as Send Handler.

Send handler properties with the Customer name and License key fields
Enter the License information for each handler.

Click Apply/Ok when you are done editing.

If the license information is invalid, you will see the following error dialog:

Error dialog for invalid license information
Example of invalid license information error.

Navigate to the Nodinite Portal or read more on the Support page to obtain a valid license or resolve any issues with this mandatory step.

LDAP adapter send handlers in the BizTalk Server Administration Console
Image example from the BizTalk Server administration console.

Important

You must apply the license key for each new and/or changed BizTalk host instance associated with the adapter.

For example: If you have 2 send handlers associated with the adapter, you must enter the license key information twice—once for each send handler.

SSO

This step is only required if you intend to use the SSO feature.

The LDAP Adapter 1.0 is built against the BizTalk Server 2013 R2 SSO assembly (Microsoft.BizTalk.Interop.SSOClient, assembly version 9.0.1000.0), but supports all BizTalk Server versions from 2010 onward. The SSO assembly loaded at runtime may differ by environment. The .NET framework version is 4.0.

To determine your SSO version, check the Server and Administration values at:

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\ENTSSO

The assembly Microsoft.BizTalk.Interop.SSOClient.dll can also be used to verify the SSO version. The default location is C:\Program Files\Common Files\Enterprise Single Sign-On. For BizTalk 2013 R2, the file version is 9.0.2096.0 and the assembly version is 9.0.1000.0.

Manual Changes for BizTalk 2010 and 2013

If you run BizTalk Server 2010 or 2013, you must edit your BizTalk configuration file with an assembly redirect as shown below.

Important

Always back up your configuration files before making changes. Invalid files may prevent BizTalk from starting. See How to Back Up The BizTalk Server Configuration for guidance.

Files to edit (usually in C:\Program Files (x86)\Microsoft BizTalk Server 201x):

  • BTSNTSvc.exe.config – for 32-bit enabled host instances
  • BTSNTSvc64.exe.config – for 64-bit enabled host instances

Change the version number according to your installed SSO Assembly version. See the table below for details.

BizTalk 2013 example (newVersion is the BizTalk 2013 SSO assembly version):

<configuration>
 …
 <runtime>
 <assemblyBinding xmlns='urn:schemas-microsoft-com:asm.v1' appliesTo='v4.0.30319'>
 <dependentAssembly>
 <assemblyIdentity name='Microsoft.BizTalk.Interop.SSOClient' publicKeyToken='31bf3856ad364e35' culture='neutral' />
 <bindingRedirect oldVersion='0.0.0.0-1000.0.0.0' newVersion='7.0.2300.0'/>
 </dependentAssembly>
 </assemblyBinding>
 …

Important

Change both 32 and 64 bit versions on all nodes.

Target environment:

BizTalk Version Change required SSO Assembly Version SSO Product Version
BizTalk 2020 No
BizTalk 2016 No
BizTalk 2013 R2 No (built against this version) 9.0.1000.0 9.0.2096.0
BizTalk 2013 Yes 7.0.2300.0 9.0.1865.0
BizTalk 2010 Yes 5.0.1.0 6.0.4219.0

If you changed the configuration files, restart the host instances to apply changes.

Send Port Connection Configuration

The LDAP Adapter provides four ways to specify connection information. The adapter evaluates connection configuration at runtime in the following priority order:

  1. Context Values (highest priority)
  2. SSO Application
  3. Connection Info in Send Port
  4. Not Set (Default) (lowest priority)

Part of the response message includes connection information, regardless of which configuration method you use during runtime.

Note

Some LDAP service providers may require secure connections with DNS names for server names. The LDAP Adapter cannot perform operations without proper privileges and settings.

Context Values

If BizTalk Server runtime context values are provided with connection information, these values take precedence over all other configuration methods—even if configuration exists on the send port.

The property schema IS.BizTalk.Adapters.LDAP.PropertySchema_v1.0.xsd defines the available context properties:

Context property Type Default Description
DSAServerName String - Points to a specific DSA (Directory System Agent) server: the LDAP server name or IP address
Port Positive integer 389 The LDAP server port: 389 for LDAP, 636 for LDAPS, 3268/3269 for the Global Catalog. See the firewall ports
UserName String - Domain\ServiceAccountName for Windows-based AD services, or the user name format of other LDAP services. Honor the principle of least privilege
Password String - The password for the account in UserName
AuthenticationType String - One or more authentication types, comma-separated

Promote the values using either a custom pipeline component or an orchestration.

Example: Setting Context Values in an Orchestration 

// Inside a message assignment expression in Visual Studio
RequestToLDAP(IS.BizTalk.Adapters.LDAP.PropertySchema.DSAServerName) = "dc01.contoso.com";
RequestToLDAP(IS.BizTalk.Adapters.LDAP.PropertySchema.Port) = 389;
RequestToLDAP(IS.BizTalk.Adapters.LDAP.PropertySchema.UserName) = "CONTOSO\\\\ServiceAccount";
RequestToLDAP(IS.BizTalk.Adapters.LDAP.PropertySchema.Password) = "P@ssw0rd";
RequestToLDAP(IS.BizTalk.Adapters.LDAP.PropertySchema.AuthenticationType) = "Secure,SecureSocketsLayer";

Tip

Using context values is recommended when developers need complete control over connection configuration at runtime, bypassing any administrator-configured settings.

Authentication Types

AuthenticationType takes the names of the System.DirectoryServices.AuthenticationTypes values, comma-separated with no spaces (for example Secure,SecureSocketsLayer):

Value Number Description
None 0 Basic authentication (simple bind)
Secure 1 Secure authentication: Kerberos, and possibly NTLM, for Active Directory. Without a user name and password, the adapter binds as the host instance account
Encryption 2 Same flag as SecureSocketsLayer
SecureSocketsLayer 2 SSL/TLS (LDAPS); requires a certificate on the directory server, see SSL-LDAPS for Active Directory
ReadonlyServer 4 A writable server isn't required for a serverless binding
Anonymous 16 No authentication
FastBind 32 Skips the objectClass query for better performance; doesn't verify that objects exist
Signing 64 Verifies data integrity; requires Secure
Sealing 128 Encrypts data using Kerberos; requires Secure
Delegation 256 Delegates the security context, needed to move objects across domains
ServerBind 512 Use when DSAServerName names a specific server; avoids unnecessary network traffic

SSO Application

The LDAP Adapter supports retrieving connection information from an SSO Application. This approach stores sensitive information like passwords securely in the SSO database.

Using SSO Application as the source of connection information is recommended because BizTalk does not preserve passwords in binding files. When you redeploy your BizTalk Server solutions, you would otherwise need to re-enter password information. Using an SSO Application eliminates this problem completely.

Tip

BizTalk environments with multiple nodes benefit from SSO configuration since it's shared across the BizTalk group—you don't need local config files or stores on each node.

Creating an SSO Application

Use the provided SSO Application configuration client tool to create an SSO Application. You must run this tool with a user account belonging to the SSO Administrators role.

Note

Depending on your version, you may need to alter the app.config file for the client tool to use the proper version of the SSO assemblies. See the SSO assembly configuration section earlier in this guide.

In the client tool, you can get and set values for parameters in SSO applications. You can also save and delete SSO applications. This tool works with any SSO Application you may have.

For LDAP Adapter solutions, you must set all 5 properties with exactly the same names as in the Context schema and connection info section:

  • DSAServerName
  • Port
  • UserName
  • Password
  • AuthenticationType

Important

Property names are case sensitive for the LDAP Adapter. Passwords are displayed in the SSO application tool (human readable), protected by your security settings on the SSO Administrators role. The SSO database is highly encrypted and protected.

Testing SSO Configuration

Log on to one of the BizTalk Server nodes and use the provided Windows Forms-based Test Client to test your SSO Application configuration:

  1. Insert a query from the provided examples (e.g., AD | GetDomainControllers)
  2. Enter the name of your SSO Application containing the connection information
  3. Execute the query

You should either get a response or an exception message. If you get an exception, the details should provide enough information to resolve the problem.

Once you confirm your SSO Application works in the Test Client, you can assume it will work in your send port in BizTalk Server.

Configuring Send Port to Use SSO Application

In your send port with the LDAP Adapter selected, press the Configure button.

In the SSO Affiliate text box (category SSO Parameters), enter the name of your SSO Application.

Note

The password field may need an initial value—this appears to be an adapter framework behavior. If you have entered a valid SSO Application name, values will be loaded from the SSO Store. Connection values from Context properties will override SSO values, as context properties take highest priority by design.

Connection Info in Send Port

By specifying parameters in the Connection Info section of the send port transport properties, you can explicitly configure which server to target with connection options.

Configure the following properties in the Connection Info category:

Field Default Description
DSA Server Name - The specific LDAP server/host name to use for LDAP operations
Port 389 The TCP port to use for LDAP connectivity (636 for LDAPS)
UserName - The DOMAIN\UserName to use when connecting to the DSA server
Password - The password to use when connecting to the DSA server
AuthenticationType - One or more authentication types, comma-separated

Note

This method is suitable for single-server environments or when you want explicit configuration visible in the BizTalk Administration Console. For multi-environment deployments, consider using SSO Applications instead.

Not Set (Default)

If you do not provide any connection information through context properties, SSO, or send port configuration, the adapter uses the default behavior:

  • The adapter targets the currently joined Windows domain
  • Uses Windows built-in functionality to dynamically resolve which domain controller (DSA Server) to use for requests
  • Uses the credentials of the BizTalk host instance service account

The connection that was used is available in the Summary record of the response message (DsaServerName, DsaPort, AuthenticationType). See Response.

Tip

Default mode works well for domain-joined servers with proper service account permissions, but provides less control over which specific domain controller is targeted.

Send Port Configuration Options

Comments

On your send ports using this adapter, you can set a Comment (category Maintenance). This comment can describe the reason for setting a property, or document any relevant information. It's simply a text field for documentation purposes.

XSLT Response Transformation

The adapter supports applying an XSLT transformation to the response message. This feature allows you to transform responses without creating or deploying Visual Studio mapping artifacts.

Configure the XSLT Transformation

  1. In the send port transport properties, category Stylesheet, specify the XSLT file path (xsl/xslt)
  2. Ensure the XSLT file is accessible from all BizTalk nodes
  3. If you have multiple BizTalk nodes, use a highly available file share for your XSLT templates

Important

Your XSLT should examine the ReturnStatus fields in the response. You may not always have data returned—perform negative tests when developing and testing this feature.

Example XSLT templates are available in the %Examples%\XSLT Examples folder in the installation directory. You can use these to create custom reports for keeping your LDAP catalog organized and clean.

Common Use Cases for XSLT

  • Filter successful operations from failed ones
  • Extract specific attributes from search results
  • Generate reports for compliance or auditing
  • Transform LDAP responses into formats for downstream systems

Handling Byte Array Data

Some byte array properties in Active Directory are not human-readable due to their binary representation. The adapter base64 encodes these properties in the response message.

The Test Client includes a button to convert base64-encoded strings back into readable strings (Byte array from base64 encoding → String).

Properties Commonly Base64 Encoded

  • objectGUID
  • objectSid
  • thumbnailPhoto
  • jpegPhoto
  • Custom binary attributes

Next Steps