Establishing a Connection

With the CData Cmdlets users can install a data module, set the connection properties, and start scripting. This section provides examples of using our LDAP Cmdlets with native PowerShell cmdlets, like the CSV import and export cmdlets.

Installing and Connecting

If you have PSGet, installing the cmdlets can be accomplished from the PowerShell Gallery with the following command. You can also obtain a setup from the CData site.

Install-Module LDAPCmdlets

The following line is then added to your profile, loading the cmdlets on the next session:

Import-Module LDAPCmdlets;

You can then use the Connect-LDAP cmdlet to create a connection object that can be passed to other cmdlets:

$conn = Connect-LDAP -User 'MyUserName' -Password 'MyPassword' -Server 'MyServer' -Port 'MyPort'

Connecting to LDAP

The CData driver for the LDAP supports connecting to LDAP server objects. To connect, set the required properties.

Required Properties

Server: The domain name or IP of the LDAP server.
Port: The port setting defaults to port=389. Specifying the port to a different setting is optional.
BaseDN: This property is used for limiting results to specific subtrees. Specifying a narrow BaseDN (Base Distinguished Name) may greatly increase performance. For example, a value of cn=users,dc=domain only returns results contained within cn=users and its children.

Optional Properties

Optional properties can be used to further refine control of the returned results.

FollowReferrals: This property follows referrals when TRUE. The returned response then becomes read only. To modify data returned by a referral server, open a new connection to the server by specifying server and port.
Scope: This property enables more control over the search depth of the LDAP tree, starting with BaseDN. Limiting the Scope can greatly improve search performance. Set the Scope to one of the following values:
- WholeSubtree: Limit the scope of the search to the BaseDN and all of its descendants.
- SingleLevel: Limit the scope of the search to the BaseDN and its direct descendants.
- BaseObject: Limit the scope of the search to the base object only.
LDAPVersion: The LDAP version used to connect to and communicate with the server. Set this property to 2.

Authenticating to LDAP

To authenticate requests, set the User and Password properties to valid LDAP credentials. For example: set User to Domain\\BobF or cn=Bob F,ou=Employees,dc=Domain.

The AuthMechanism properties for the cmdlet are as follows:

SIMPLE: The default plaintext value of the authentication mechanism to login to the server.
NEGOTIATE: Negotiates whether to use NTLN or Kerberos when authenticating to the server.

SSL Configuration

By default, the driver uses plaintext when communicating with the server set to port=389. The driver automatically switches to use SSL when talking to the LDAP on port=636. You can force the connection to use the SSL connection property when set to SSL=TRUE.

Customizing Tables

The cmdlet surfaces the columns most often needed from LDAP entities. However, if you need to work with other data, the tables are easy to modify. Tables are defined in schema files, which have a simple format.

See Working with LDAP Tables for a guide to extending the default schemas or writing your own. To use custom schemas, set the Location property to the folder containing the schema files. For more on tables and views, see Data Model.

Retrieving Data

The Select-LDAP cmdlet provides a native PowerShell interface for retrieving data:

$results = Select-LDAP -Connection $conn -Table "User" -Columns @("Id, CN") -Where "CN='Administrator'"

The Invoke-LDAP cmdlet provides an SQL interface. This cmdlet can be used to execute an SQL query via the Query parameter.

Piping Cmdlet Output

The cmdlets return row objects to the pipeline one row at a time. The following line exports results to a CSV file:

Select-LDAP -Connection $conn -Table User -Where "CN = 'Administrator'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\myUserData.csv -NoTypeInformation

You will notice that we piped the results from Select-LDAP into a Select-Object cmdlet and excluded some properties before piping them into an Export-CSV cmdlet. We do this because the CData Cmdlets append Connection, Table, and Columns information onto each row object in the result set, and we do not necessarily want that information in our CSV file.

However, this makes it easy to pipe the output of one cmdlet to another. The following is an example of converting a result set to JSON:

 
PS C:\> $conn  = Connect-LDAP -User 'MyUserName' -Password 'MyPassword' -Server 'MyServer' -Port 'MyPort'
PS C:\> $row = Select-LDAP -Connection $conn -Table "User" -Columns (Id, CN) -Where "CN = 'Administrator'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "User",
  "Columns":  [

  ],
  "Id":  "MyId",
  "CN":  "MyCN"
}

Deleting Data

The following line deletes any records that match the criteria:

Select-LDAP -Connection $conn -Table User -Where "CN = 'Administrator'" | Remove-LDAP

Modifying Data

The cmdlets make data transformation easy as well as data cleansing. The following example loads data from a CSV file into LDAP, checking first whether a record already exists and needs to be updated instead of inserted.

Import-Csv -Path C:\MyUserUpdates.csv | %{
  $record = Select-LDAP -Connection $conn -Table User -Where ("Id = `'"+$_.Id+"`'")
  if($record){
    Update-LDAP -Connection $conn -Table User -Columns @("Id","CN") -Values @($_.Id, $_.CN) -Where "Id  = `'$_.Id`'"
  }else{
    Add-LDAP -Connection $conn -Table User -Columns @("Id","CN") -Values @($_.Id, $_.CN)
  }
}

Cmdlets for LDAP