LDAP Adapter for Microsoft BizTalk
Requirements: /n software Adapters for Microsoft BizTalk
Introduction
The /n software Adapters for Microsoft BizTalk include fully-managed .NET Adapters that seamlessly integrate with the BizTalk Messaging Pipeline. The /n software Adapters extend the features of BizTalk with advanced Internet communications and secure messaging capabilities.
There are many different BizTalk adapters currently supported: AS2 Adapters for EDI communications, FTPS, FTP, SFTP, SSH, Email adapters, etc. These adapters have completed the official adapter certification program (administered by Unisys) established by Microsoft for BizTalk server, which tests for scalability and interoperability with Microsoft BizTalk Server.
This guide will focus specifically on the LDAP adapter, which is used to communicate with LDAP servers. This tutorial will cover using the adapter to perform a variety of operations.
Contents
- Adapter Overview
- Add Operation
- Authenticate Operation
- Change Password Operation
- Delete Operation
- Modify Operation
- Search Operation
Adapter Overview
The LDAP send adapter is designed to be used as a solicit response adapter. Some operations require a message that adheres to a schema while others to not place any restrictions on the message content and rely solely on the adapter property values.
The operation performed by the adapter is controlled by the Operation property. To begin, specify the connection information in Server, and Port. SSL may be enabled via the SSLStartMode property.
To perform an authenticated bind, set BindDN to your username and Password.
All operations will populate the ResultCode, ResultDescription, and ResultSuccess context properties in the message returned by the adapter. These should be checked to determine the result of the operation that was requested.
For more information on how to use the adapters dynamically or within an orchestration please see KB 07060701.
Below is an overview of the available operations.
Add Operation
The Add operation allows you to create new entries in your directory. The message must adhere to the schema defined in "LDAPAdd.xsd" that is located in the "schemas" folder of the installation. To add attributes to an existing entry use the Modify operation instead.
To write code in an orchestration first reference the "nsoftware.BizTalk.LDAPAdapter.dll" from the lib directory of the installation. Then you can use code like below to configure the adapter from a message assignment shape.
Message_2(nsoftware.BizTalk.LDAP.Server) = "testserver";
Message_2(nsoftware.BizTalk.LDAP.Port) = 636;
Message_2(nsoftware.BizTalk.LDAP.SSLStartMode) = nsoftware.BizTalk.LDAP.LdapSSLStartModes.sslImplicit;
Message_2(nsoftware.BizTalk.LDAP.SSLAcceptServerCertAcceptAny) = true;
Message_2(nsoftware.BizTalk.LDAP.DN) = "CN=NewUser,CN=Users,DC=DomainComponent";
Message_2(nsoftware.BizTalk.LDAP.BindDN) = "Domain\\Administrator";
Message_2(nsoftware.BizTalk.LDAP.Password) = "password";
Message_2(nsoftware.BizTalk.LDAP.Operation) = nsoftware.BizTalk.LDAP.LdapOperations.opAdd;
Since the Add operation requires the message adhere to the LDAPAdd.xsd schema, make sure your message meets this requirement. Note that the adapter will accept Base64 encoded data in the LDAPAttribute element if the Value attribute is absent. This can be useful for adding a thumbnailPhoto for users, or other applications when binary data is needed. Below is a simple example.
<LDAPAdd> <LDAPAttribute Type="objectClass" Value="top" /> <LDAPAttribute Value="person" /> <LDAPAttribute Value="organizationalPerson" /> <LDAPAttribute Value="inetorgperson" /> <LDAPAttribute Type="thumbnailPhoto"> dGVzdA== </LDAPAttribute> </LDAPAdd>
After executing, the response message returned by the adapter will hold values for ResultSuccess, ResultCode, ResultDescription. These context properties can be checked to determine if the operation succeeded. If ResultSuccess is False, ResultCode and ResultDescription will provide details on the error. For Example:
if(Message_2(nsoftware.BizTalk.LDAP.ResultSuccess))
{
System.Diagnostics.EventLog.WriteEntry("LDAP Orchestration", "Success");
}
else
{
System.Diagnostics.EventLog.WriteEntry("LDAP Orchestration", "Failure: " +
System.Convert.ToString(Message_2(nsoftware.BizTalk.LDAP.ResultCode)));
}
Authenticate Operation
The Authenticate operation is used simply to verify that a user can bind to the LDAP server successfully. The request message does not need to adhere to any schema. For example:
Message_2(nsoftware.BizTalk.LDAP.Server) = "testserver";
Message_2(nsoftware.BizTalk.LDAP.Port) = 636;
Message_2(nsoftware.BizTalk.LDAP.SSLStartMode) =
nsoftware.BizTalk.LDAP.LdapSSLStartModes.sslImplicit;
Message_2(nsoftware.BizTalk.LDAP.SSLAcceptServerCertAcceptAny) = true;
Message_2(nsoftware.BizTalk.LDAP.BindDN) = "Domain\\Administrator";
Message_2(nsoftware.BizTalk.LDAP.Password) = "password";
Message_2(nsoftware.BizTalk.LDAP.Operation) = nsoftware.BizTalk.LDAP.LdapOperations.opAuthenticate;
To determine if the authentication succeeded check the ResultSuccess context property on the response message. For instance:
if(Message_2(nsoftware.BizTalk.LDAP.ResultSuccess))
{
System.Diagnostics.EventLog.WriteEntry("LDAP Orchestration", "Success");
}
else
{
System.Diagnostics.EventLog.WriteEntry("LDAP Orchestration", "Failure: " +
System.Convert.ToString(Message_2(nsoftware.BizTalk.LDAP.ResultCode)));
}
Change Password Operation
The Change Password operation allows you to define a new password for the user specified in the DN property. The new password is set in the NewPassword property. The request message does not need to adhere to any schema. Below is an example:
Message_2(nsoftware.BizTalk.LDAP.Server) = "testserver";
Message_2(nsoftware.BizTalk.LDAP.Port) = 636;
Message_2(nsoftware.BizTalk.LDAP.SSLStartMode) = nsoftware.BizTalk.LDAP.LdapSSLStartModes.sslImplicit;
Message_2(nsoftware.BizTalk.LDAP.SSLAcceptServerCertAcceptAny) = true;
Message_2(nsoftware.BizTalk.LDAP.DN) = "CN=MyUser,CN=Users,DC=DomainComponent";
Message_2(nsoftware.BizTalk.LDAP.NewPassword) = "newpassword1";
Message_2(nsoftware.BizTalk.LDAP.BindDN) = "Domain\\Administrator";
Message_2(nsoftware.BizTalk.LDAP.Password) = "password";
Message_2(nsoftware.BizTalk.LDAP.Operation) = nsoftware.BizTalk.LDAP.LdapOperations.opChangePassword;
To determine if the operation succeeded check the ResultSuccess context property on the response message. For instance:
if(Message_2(nsoftware.BizTalk.LDAP.ResultSuccess))
{
System.Diagnostics.EventLog.WriteEntry("LDAP Orchestration", "Success");
}
else
{
System.Diagnostics.EventLog.WriteEntry("LDAP Orchestration", "Failure: " +
System.Convert.ToString(Message_2(nsoftware.BizTalk.LDAP.ResultCode)));
}
Delete Operation
The Delete operation deletes the entry specified by DN. The request message does not need to adhere to any schema. Below is an example:
Message_2(nsoftware.BizTalk.LDAP.Server) = "testserver";
Message_2(nsoftware.BizTalk.LDAP.Port) = 636;
Message_2(nsoftware.BizTalk.LDAP.SSLStartMode) = nsoftware.BizTalk.LDAP.LdapSSLStartModes.sslImplicit;
Message_2(nsoftware.BizTalk.LDAP.SSLAcceptServerCertAcceptAny) = true;
Message_2(nsoftware.BizTalk.LDAP.DN) = "CN=UserToDelete,CN=Users,DC=DomainComponent";
Message_2(nsoftware.BizTalk.LDAP.BindDN) = "Domain\\Administrator";
Message_2(nsoftware.BizTalk.LDAP.Password) = "password";
Message_2(nsoftware.BizTalk.LDAP.Operation) = nsoftware.BizTalk.LDAP.LdapOperations.opDelete;
To determine if the operation succeeded check the ResultSuccess context property on the response message. For instance:
if(Message_2(nsoftware.BizTalk.LDAP.ResultSuccess))
{
System.Diagnostics.EventLog.WriteEntry("LDAP Orchestration", "Success");
}
else
{
System.Diagnostics.EventLog.WriteEntry("LDAP Orchestration", "Failure: " +
System.Convert.ToString(Message_2(nsoftware.BizTalk.LDAP.ResultCode)));
}
Modify Operation
The Modify operation allows you to update an entry by adding, deleting, or modifying attributes. The message must adhere to the schema defined in "LDAPModify.xsd" that is located in the "schemas" folder of the installation. For example:
Message_2(nsoftware.BizTalk.LDAP.Server) = "testserver";
Message_2(nsoftware.BizTalk.LDAP.Port) = 636;
Message_2(nsoftware.BizTalk.LDAP.SSLStartMode) = nsoftware.BizTalk.LDAP.LdapSSLStartModes.sslImplicit;
Message_2(nsoftware.BizTalk.LDAP.SSLAcceptServerCertAcceptAny) = true;
Message_2(nsoftware.BizTalk.LDAP.DN) = "CN=MyUser,CN=Users,DC=DomainComponent";
Message_2(nsoftware.BizTalk.LDAP.BindDN) = "Domain\\Administrator";
Message_2(nsoftware.BizTalk.LDAP.Password) = "password";
Message_2(nsoftware.BizTalk.LDAP.Operation) = .BizTalk.LDAP.LdapOperations.opModify;
Since the Modify operation requires the message adhere to the LDAPModify.xsd schema, make sure your message meets this requirement. Note that the adapter will accept Base64 encoded data in the LDAPAttribute element if the Value attribute is absent. This can be useful for adding a thumbnailPhoto for users, or other applications when binary data is needed. Below is a simple example.
<LDAPModify> <LDAPAttribute Type="telephoneNumber" Value="phoneNumber1" ModifyOperation="add"/> <LDAPAttribute Type="description" Value="changed" ModifyOperation="replace"/> <LDAPAttribute Type="givenName" Value="TestName" ModifyOperation="delete"/> <LDAPAttribute Type="thumbnailPhoto"> dGVzdA== </LDAPAttribute> </LDAPModify>
After executing, the response message returned by the adapter will hold values for ResultSuccess, ResultCode, ResultDescription. These context properties can be checked to determine if the operation succeeded. If ResultSuccess is False, ResultCode and ResultDescription will provide details on the error. For Example:
if(Message_2(nsoftware.BizTalk.LDAP.ResultSuccess))
{
System.Diagnostics.EventLog.WriteEntry("LDAP Orchestration", "Success");
}
else
{
System.Diagnostics.EventLog.WriteEntry("LDAP Orchestration", "Failure: " +
System.Convert.ToString(Message_2(nsoftware.BizTalk.LDAP.ResultCode)));
}
Search Operation
The Search operation allows you to perform a search for entries in your directory. The message must adhere to the schema defined in "LDAPSearch.xsd" that is located in the "schemas" folder of the installation. This message is how the parameters of the search are defined. The response adheres to the "LDAPSearchResult.xsd" schema and will contain the search results. For example:
Message_2(nsoftware.BizTalk.LDAP.Server) = "testserver";
Message_2(nsoftware.BizTalk.LDAP.Port) = 636;
Message_2(nsoftware.BizTalk.LDAP.SSLStartMode) =
nsoftware.BizTalk.LDAP.LdapSSLStartModes.sslImplicit;
Message_2(nsoftware.BizTalk.LDAP.SSLAcceptServerCertAcceptAny) = true;
Message_2(nsoftware.BizTalk.LDAP.DN) = "CN=Users,DC=DomainComponent";
Message_2(nsoftware.BizTalk.LDAP.BindDN) = "Domain\\Administrator";
Message_2(nsoftware.BizTalk.LDAP.Password) = "password";
Message_2(nsoftware.BizTalk.LDAP.Operation) = nsoftware.BizTalk.LDAP.LdapOperations.opSearch;
Since the Search operation requires the message adhere to the "LDAPSearch.xsd" schema, make sure your message meets this requirement. Below is a simple example.
<LDAPSearch SearchFilter="CN=*"> </LDAPSearch>
Or to search using an attribute:
<LDAPSearch > <LDAPAttribute Type="givenName"/> </LDAPSearch>
After executing, the response message returned by the adapter will hold values for ResultSuccess, ResultCode, ResultDescription. These context properties can be checked to determine if the operation succeeded. If ResultSuccess is False, ResultCode and ResultDescription will provide details on the error. If the operation succeeded the response message will adhere to the "LDAPSearchResult.xsd" schema. For Example to check the result status:
if(Message_2(nsoftware.BizTalk.LDAP.ResultSuccess))
{
System.Diagnostics.EventLog.WriteEntry("LDAP Orchestration", "Success");
}
else
{
System.Diagnostics.EventLog.WriteEntry("LDAP Orchestration", "Failure: " +
System.Convert.ToString(Message_2(nsoftware.BizTalk.LDAP.ResultCode)));
}
An example response message:
<LDAPSearchResults> <ResultEntry DN="CN=Users,DC=DomainComponent"> <LDAPAttribute Type="objectClass" Value="top" /> <LDAPAttribute Type="" Value="container" /> <LDAPAttribute Type="cn" Value="Users" /> <LDAPAttribute Type="description" Value="Default container for upgraded user accounts" /> <LDAPAttribute Type="distinguishedName" Value="CN=Users,DC=DomainComponent" /> <LDAPAttribute Type="instanceType" Value="4" /> <LDAPAttribute Type="whenCreated" Value="20080501223648.0Z" /> <LDAPAttribute Type="whenChanged" Value="20080501223648.0Z" /> <LDAPAttribute Type="uSNCreated" Value="4304" /> <LDAPAttribute Type="uSNChanged" Value="4304" /> <LDAPAttribute Type="showInAdvancedViewOnly" Value="FALSE" /> <LDAPAttribute Type="name" Value="Users" /> <LDAPAttribute Type="systemFlags" Value="-1946157056" /> <LDAPAttribute Type="objectCategory" Value="CN=Container,CN=Schema,CN=Configuration,DC=DomainComponent" /> <LDAPAttribute Type="isCriticalSystemObject" Value="TRUE" /> </ResultEntry> <ResultEntry DN="CN=Administrator,CN=Users,DC=DomainComponent"> <LDAPAttribute Type="objectClass" Value="top" /> <LDAPAttribute Type="" Value="person" /> <LDAPAttribute Type="" Value="organizationalPerson" /> <LDAPAttribute Type="" Value="user" /> <LDAPAttribute Type="cn" Value="Administrator" /> <LDAPAttribute Type="description" Value="Built-in account for administering the computer/domain" /> <LDAPAttribute Type="distinguishedName" Value="CN=Administrator,CN=Users,DC=DomainComponent" /> <LDAPAttribute Type="instanceType" Value="4" /> <LDAPAttribute Type="whenCreated" Value="20080501223651.0Z" /> <LDAPAttribute Type="whenChanged" Value="20080501231601.0Z" /> <LDAPAttribute Type="uSNCreated" Value="8194" /> <LDAPAttribute Type="memberOf" Value="CN=Group Policy Creator Owners,CN=Users,DC=DomainComponent" /> <LDAPAttribute Type="" Value="CN=Domain Admins,CN=Users,DC=DomainComponent" /> <LDAPAttribute Type="" Value="CN=Enterprise Admins,CN=Users,DC=DomainComponent" /> <LDAPAttribute Type="" Value="CN=Schema Admins,CN=Users,DC=DomainComponent" /> <LDAPAttribute Type="" Value="CN=Administrators,CN=Builtin,DC=DomainComponent" /> <LDAPAttribute Type="uSNChanged" Value="16416" /> <LDAPAttribute Type="name" Value="Administrator" /> <LDAPAttribute Type="userAccountControl" Value="66048" /> <LDAPAttribute Type="badPwdCount" Value="0" /> <LDAPAttribute Type="codePage" Value="0" /> <LDAPAttribute Type="countryCode" Value="0" /> <LDAPAttribute Type="badPasswordTime" Value="129775010552968750" /> <LDAPAttribute Type="lastLogoff" Value="0" /> <LDAPAttribute Type="lastLogon" Value="129775010570156250" /> <LDAPAttribute Type="pwdLastSet" Value="128437683631093750" /> <LDAPAttribute Type="primaryGroupID" Value="513" /> <LDAPAttribute Type="adminCount" Value="1" /> <LDAPAttribute Type="accountExpires" Value="9223372036854775807" /> <LDAPAttribute Type="logonCount" Value="11972" /> <LDAPAttribute Type="sAMAccountName" Value="Administrator" /> <LDAPAttribute Type="sAMAccountType" Value="805306368" /> <LDAPAttribute Type="objectCategory" Value="CN=Person,CN=Schema,CN=Configuration,DC=DomainComponent" /> <LDAPAttribute Type="isCriticalSystemObject" Value="TRUE" /> <LDAPAttribute Type="msNPAllowDialin" Value="TRUE" /> </ResultEntry>
We appreciate your feedback. If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.