PowerShell: Microsoft Active Directory

Overview

Active Directory is the on-premises directory service that underpins most Windows enterprise estates. It holds user accounts, computer accounts for domain-joined machines, security and distribution groups, and the organisational unit hierarchy that expresses how those objects are delegated and administered. It remains the authoritative identity source in the majority of organisations, including those that have also adopted cloud identity.

This connector reads Active Directory by running a PowerShell script, CX_LDAP.ps1, on a Windows host. The connection names the directory server and a port (the default is 3268, the global catalog port, which searches across the whole forest instead of a single domain), an optional organisational unit to scope the search to a subtree, and a temporary working path for the files the script produces during processing. Each job’s Data Selection field is a comma-separated list of directory attributes to retrieve, and the results are written to the named staging table.

In a ReadyWorks context this is the backbone of identity and endpoint reconciliation. Four jobs give you the people, the machines, the groups and the relationships between them, which is what lets the data fabric answer who owns a device, which groups gate an application, and which accounts and machines are stale enough to exclude from a migration wave.

Active Directory carries data that a cloud directory connector does not. Computer objects for domain-joined machines, with their operating system, version, service pack, last logon date, location and managed-by attributes, exist only here. So does the organisational unit and distinguished name hierarchy, which encodes site, region and delegation structure that has no cloud equivalent. So do on-premises group types such as domain-local and distribution groups, and account attributes such as home directory and primary group. If your estate runs both, run the cloud connector and this one, and reconcile on the account identifiers they share.

The connector is inbound only. It reads the directory and writes staging tables, and it makes no changes to any directory object.

NOTE: windows_only is set on this connector. The ReadyWorks ETL host that runs these jobs has to be a Windows machine with PowerShell and the Active Directory module available, and the account the ETL service runs under needs read access to the directory. A Linux-hosted ReadyWorks deployment cannot run this connector.

Connector Properties

Authentication Methods

One method ships. It is a Windows PowerShell connection to a directory server rather than a web API call.

NOTE: There is no credential field on this connection. Access is governed entirely by the Windows account the ReadyWorks ETL service runs as, so that account is what a security review needs to see.

NOTE: Port 3268 returns only attributes that are replicated to the global catalog. If an attribute you listed in Data Selection comes back consistently empty, check whether it is in the global catalog partial attribute set before assuming the directory does not hold it.

Method 1: Microsoft Active Directory (RWS_AD_000a62482f)

Active Directory Connection using Windows Powershell Script

Microsoft Active Directory runs CX_LDAP.ps1 against the server named in Source Server on the port in Source Server Port. The default port 3268 is the global catalog, which returns a partial attribute set across every domain in the forest; use 389 when you need the full attribute set from a single domain. Organizational Unit optionally scopes the search to one subtree, which is the main lever for keeping run times and row counts manageable on a large forest. No username or password fields are presented, so the script authenticates as the Windows identity the ETL process runs under.

Connection Configuration Fields (4)

Authentication Configuration

cURL options:

Inbound Job Fields Enabled (11)

These are the job-level settings exposed for an Active Directory extract. Data Selection holds the attribute list and Request Filter narrows which objects are returned.

Inbound Job Templates (4)

Four inbound templates ship, covering users, computers, groups and group membership. All four are enabled by default and run daily, so they begin returning data as soon as a connection exists.

Job Template Configuration

Settings Common to All Four Templates

Settings That Vary by Template

Job Parameters and Enumeration

AD User Data

Data Selection:

AccountExpirationDate,CanonicalName,City,Company,country,Department,departmentnumber,Description,DisplayName,DistinguishedName,Division,EmployeeID,EmployeeNumber,Enabled,GivenName,HomeDirectory,HomePhone,LastLogonDate,logoncount,mail,Manager,ObjectGUID,OfficePhone,PasswordLastSet,physicalDeliveryOfficeName,POBox,PostalCode,SamAccountName,State,StreetAddress,Surname,Title,UserPrincipalName,whenchanged,whencreated

AD Computer Data

Data Selection: cn,description,distinguishedname,enabled,lastlogondate,location,managedby,Name,objectguid,OperatingSystem,operatingsystemservicepack,operatingsystemversion,PrimaryGroup,whencreated

AD Group Data

Data Selection: CanonicalName,description,distinguishedname,grouptype,mail,managedby,objectguid,samAccountName,whenchanged,whencreated

AD Group Nembership Relationship

Data Selection: MemberOf,ObjectGUID,samAccountName

NOTE: All four jobs read the same directory on the same daily schedule. On a large forest, stagger them or scope them with the Organizational Unit field on the connection so that they do not run concurrently against the same directory servers.

Outbound Job Templates (0)

This connector ships no outbound templates and does not support outbound jobs.