Class LdapConnection

The central class that encapsulates the connection to a directory server through the Ldap protocol. LdapConnection objects are used to perform common Ldap operations such as search, modify and add. In addition, LdapConnection objects allow you to bind to an Ldap server, set connection and search constraints, and perform several other tasks. An LdapConnection object is not connected on construction and can only be connected to one server at one port.

Based on https://github.com/dsbenghe/Novell.Directory.Ldap.NETStandard.

Inheritance

Object

LdapConnection

Implements

IDisposable

Inherited Members

Object.ToString()

Object.Equals(Object)

Object.Equals(Object, Object)

Object.ReferenceEquals(Object, Object)

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Namespace: Swan.Ldap

Syntax

public class LdapConnection : IDisposable

Examples

The following code describes how to use the LdapConnection class:

class Example
{
    using Swan;
    using Swan.Ldap;
    using System.Threading.Tasks;

    static async Task Main()
    {
        // create a LdapConnection object
        var connection = new LdapConnection();

        // connect to a server
        await connection.Connect("ldap.forumsys.com", 389);

        // set up the credentials 
        await connection.Bind("cn=read-only-admin,dc=example,dc=com", "password");

        // retrieve all entries that have the specified email using ScopeSub 
        // which searches all entries at all levels under 
        // and including the specified base DN
        var searchResult = await connection
        .Search("dc=example,dc=com", LdapConnection.ScopeSub, "(cn=Isaac Newton)");

        // if there are more entries remaining keep going
        while (searchResult.HasMore())
        {
            // point to the next entry
            var entry = searchResult.Next();

            // get all attributes 
            var entryAttributes = entry.GetAttributeSet();

            // select its name and print it out
            entryAttributes.GetAttribute("cn").StringValue.Info();
        }

        // modify Tesla and sets its email as tesla@email.com
        connection.Modify("uid=tesla,dc=example,dc=com", 
        new[] { 
            new LdapModification(LdapModificationOp.Replace,
                "mail", "tesla@email.com") 
            });

        // delete the listed values from the given attribute
        connection.Modify("uid=tesla,dc=example,dc=com", 
        new[] { 
            new LdapModification(LdapModificationOp.Delete,
            "mail", "tesla@email.com") 
            });

        // add back the recently deleted property
        connection.Modify("uid=tesla,dc=example,dc=com", 
            new[] { 
                new LdapModification(LdapModificationOp.Add,
                "mail", "tesla@email.com") 
            });    

        // disconnect from the LDAP server
        connection.Disconnect();

        Terminal.Flush();
    }
}

Properties

AuthenticationDn

Returns the distinguished name (DN) used for as the bind name during the last successful bind operation. null is returned if no authentication has been performed or if the bind resulted in an anonymous connection.

Declaration

public string AuthenticationDn { get; }

Property Value

Type	Description
String	The authentication dn.

AuthenticationMethod

Returns the method used to authenticate the connection. The return value is one of the following:.

• "none" indicates the connection is not authenticated.
• "simple" indicates simple authentication was used or that a null or empty authentication DN was specified.
• "sasl" indicates that a SASL mechanism was used to authenticate

Declaration

public string AuthenticationMethod { get; }

Property Value

Type	Description
String	The authentication method.

Connected

Indicates whether the connection represented by this object is open at this time.

Declaration

public bool Connected { get; }

Property Value

Type	Description
Boolean	True if connection is open; false if the connection is closed.

ProtocolVersion

Returns the protocol version uses to authenticate. 0 is returned if no authentication has been performed.

Declaration

public int ProtocolVersion { get; }

Property Value

Type	Description
Int32	The protocol version.

Methods

Bind(Int32, String, String)

Synchronously authenticates to the Ldap server (that the object is currently connected to) using the specified name, password, Ldap version, and constraints. If the object has been disconnected from an Ldap server, this method attempts to reconnect to the server. If the object has already authenticated, the old authentication is discarded.

Declaration

public Task Bind(int version, string dn, string password)

Parameters

Type	Name	Description
Int32	version	The Ldap protocol version, use Ldap_V3. Ldap_V2 is not supported.
String	dn	If non-null and non-empty, specifies that the connection and all operations through it should be authenticated with dn as the distinguished name.
String	password	If non-null and non-empty, specifies that the connection and all operations through it should be authenticated with dn as the distinguished name and passwd as password. Note: the application should use care in the use of String password objects. These are long lived objects, and may expose a security risk, especially in objects that are serialized. The LdapConnection keeps no long lived instances of these objects.

Returns

Type	Description
Task	A Task representing the asynchronous operation.

Bind(String, String)

Synchronously authenticates to the Ldap server (that the object is currently connected to) using the specified name, password, Ldap version, and constraints. If the object has been disconnected from an Ldap server, this method attempts to reconnect to the server. If the object has already authenticated, the old authentication is discarded.

Declaration

public Task Bind(string dn, string password)

Parameters

Type	Name	Description
String	dn	If non-null and non-empty, specifies that the connection and all operations through it should be authenticated with dn as the distinguished name.
String	password	If non-null and non-empty, specifies that the connection and all operations through it should be authenticated with dn as the distinguished name and password. Note: the application should use care in the use of String password objects. These are long lived objects, and may expose a security risk, especially in objects that are serialized. The LdapConnection keeps no long lived instances of these objects.

Returns

Type	Description
Task	A Task representing the asynchronous operation.

Connect(String, Int32)

Connects to the specified host and port. If this LdapConnection object represents an open connection, the connection is closed first before the new connection is opened. At this point, there is no authentication, and any operations are conducted as an anonymous client.

Declaration

public Task Connect(string host, int port)

Parameters

Type	Name	Description
String	host	A host name or a dotted string representing the IP address of a host running an Ldap server.
Int32	port	The TCP or UDP port number to connect to or contact. The default Ldap port is 389.

Returns

Type	Description
Task	A Task representing the asynchronous operation.

Disconnect()

Synchronously disconnects from the Ldap server. Before the object can perform Ldap operations again, it must reconnect to the server by calling connect. The disconnect method abandons any outstanding requests, issues an unbind request to the server, and then closes the socket.

Declaration

public void Disconnect()

Dispose()

Declaration

public void Dispose()

Modify(String, LdapModification[], CancellationToken)

Modifies the specified dn.

Declaration

public Task Modify(string distinguishedName, LdapModification[] mods, CancellationToken ct = default(CancellationToken))

Parameters

Type	Name	Description
String	distinguishedName	Name of the distinguished.
LdapModification[]	mods	The mods.
CancellationToken	ct	The cancellation token.

Returns

Type	Description
Task	A Task representing the asynchronous operation.

Exceptions

Type	Condition
ArgumentNullException	distinguishedName.

Read(String, String[], CancellationToken)

Synchronously reads the entry for the specified distinguished name (DN), using the specified constraints, and retrieves only the specified attributes from the entry.

Declaration

public Task<LdapEntry> Read(string dn, string[] attrs = null, CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
String	dn	The distinguished name of the entry to retrieve.
String[]	attrs	The names of the attributes to retrieve.
CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
Task<LdapEntry>	the LdapEntry read from the server.

Exceptions

Type	Condition
LdapException	Read response is ambiguous, multiple entries returned.

Search(String, LdapScope, String, String[], Boolean, CancellationToken)

Performs the search specified by the parameters, also allowing specification of constraints for the search (such as the maximum number of entries to find or the maximum time to wait for search results).

Declaration

public Task<LdapSearchResults> Search(string base, LdapScope scope, string filter = "objectClass=*", string[] attrs = null, bool typesOnly = false, CancellationToken cancellationToken = default(CancellationToken))

Parameters

Type	Name	Description
String	base	The base distinguished name to search from.
LdapScope	scope	The scope of the entries to search.
String	filter	The search filter specifying the search criteria.
String[]	attrs	The names of attributes to retrieve.
Boolean	typesOnly	If true, returns the names but not the values of the attributes found. If false, returns the names and values for attributes found.
CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
Task<LdapSearchResults>	A Task representing the asynchronous operation.

Implements

System.IDisposable

Comments