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:

1. Customer Name: The licensee's name, which appears in the XML response message summary 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'.

Associate the appropriate Host Instance(s) as Send Handler.

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:

Example of invalid license information error.

Contact support@nodinite.com to obtain a valid license or resolve any issues with this mandatory step.

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 targets BizTalk Server 2013 R2, 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 .NET version is 9.0.1000.0.

Manual changes:

If your BizTalk version is not 2013 R2, 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 R2 example:

<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	Yes	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:

• DSAServer - The LDAP server name or IP address
• DSAServerPort - The LDAP server port (typically 389 for LDAP, 636 for LDAPS)
• UserName - The username for authentication
• Password - The password for authentication
• AuthenticationType - The authentication type (comma-separated values)

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.DSAServer) = "dc01.contoso.com";
RequestToLDAP(IS.BizTalk.Adapters.LDAP.PropertySchema.DSAServerPort) = 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.

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:

• DSAServer
• DSAServerPort
• 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, 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:

• DSA Server - The LDAP server name or IP address
• DSA Server Port - The LDAP server port (typically 389 for LDAP, 636 for LDAPS)
• User Name - The username for authentication (e.g., DOMAIN\Username)
• Password - The password for authentication
• Authentication Type - The authentication type from the dropdown list

The authentication types are comma-separated in the adapter and can be easily selected within the send port configuration dialog.

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

This connection information is available in the Summary record in the response message.

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. 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.

To configure XSLT transformation:

1. In the send port transport properties, specify the XSLT file path
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 Step

• Review User Management to understand LDAP operations
• Explore the Test Client for testing and validation
• Learn about Request and Response message schemas

Related Topics

• BizTalk LDAP Adapter Overview
• Prerequisites
• Installation Guide