Microsoft ADS Agent

ADSAgent is the DirX Identity agent that handles the import and export of Active Directory user and group objects to and from a Microsoft Windows Active Directory. ADSAgent uses the ADSI LDAP provider to bind to the Active Directory and runs on Windows.

ADSAgent can:

  • Perform a full or a delta export of object classes from an Active Directory, including multiple attribute values and using LDAP search filters

  • Perform a full or a delta import of object classes into an Active Directory, including multiple attribute values

  • Generate an import error file that records all user and group entries that it fails to import

  • Generate a log file (for tracing)

The following figures illustrate the components of the ADSAgent export and import operations.

ADSAgent Export Components
Figure 1. ADSAgent Export Components
ADSAgent Import Components
Figure 2. ADSAgent Import Components

This section describes:

  • ADSAgent command line format for export and import operations

  • ADSAgent configuration files for export and import operations

  • The export data file format that ADSAgent generates

  • The import data file format that ADSAgent recognizes

  • ADSAgent import error file format

  • How to create Exchange mail-enabled and mailbox-enabled users in Active Directory

Sample ADSAgent configuration files and scripts are provided in the \Samples\ADS directory of the DirX Identity installation. See the file ADSReadme.txt for a description of these files and scripts.

Command Line Format

The command line format to invoke ADSAgent is as follows:

AdsAgent.exe sync_switch data_file configuration_file error_file [/a]>initial_error_file
[-Enc encryption_mode -Timeout timeout_value -AuditLevel audit_level -CryptLogLevel crypt_level]

Parameters

sync_switch

Specifies the type of directory synchronization that ADSAgent is to perform. Possible values are:

/e Invokes the ADSAgent export function
/i Invokes the ADSAgent import function

data_file

For export: specifies the pathname of the target export data file that is to contain the entries that ADSAgent extracts from an Active Directory.*
For import:* specifies the pathname of the source file that contains the data to be imported into an Active Directory.

configuration_file

Specifies the name of the file that contains the specifications for the export and import procedure.

If the file is located in the working directory, you must explicitly indicate this fact by using the .\ notation before the file name, as shown in the example. It is not sufficient to specify only the file name, as it is for the data_file and error_file parameters.
error_file

Specifies the name of the file to which ADSAgent is to write error messages about errors that occur during the export or import process. For export errors, the format is:

  • ###date_and_time command_line
    Error! error_message
    ###date_and_time command_line

where error_message contains the function name that failed and an error code and error text.

For example:

### 04/07/2001 08:16:57 AM AdsAgent /e Data\ExportDirx.adr
.\ExportDirx.ini ExportDirx.log
Error! ADsOpenObject failed. Error Code: 80005000 Error Text:
An invalid Active Directory Pathname was passed.
### 04/07/2001 08:16:58 AM End

See "Import Error File Format" for a description of import error format.

/a (On export only)

Specifies that ADSAgent is to append the results of the export operation to data_file and error_file and write a timestamp at the start and end of the results. Use this switch on an export operation to append extracted entries to an existing export data file and to append error information to an existing error log file.

If the switch is not specified, ADSAgent overwrites the contents of the specified data_file and error_file, if they already exist.

initial_error_file

Specifies the name of the file to which ADSAgent is to write error messages for errors that occur before it creates error_file.

-ENC encryption_mode

Specifies the security mode. Valid modes are ATTRIB_ADMIN_PW or ADMIN_PW.

This functionality only works correctly in an appropriate security environment like in the DirX Identity environment configured in security mode. (See DirX Identity Connectivity Administration Guide).

-Timeout timeout_value

Specifies the timeout value for the security mode. Values must be given in microseconds.

This functionality only works correctly in an appropriate security environment like in the DirX Identity environment configured in security mode. (See DirX Identity Connectivity Administration Guide).

-AuditLevel audit_level

Specifies the audit level value for the security mode. Valid values are in the range of 0 and 4.

This functionality only works correctly in an appropriate security environment like in the DirX Identity environment configured in security mode. (See DirX Identity Connectivity Administration Guide).

-CryptLogLevel crypt_level

Specifies the logging level of the crypt library for the security mode. Valid values are greater or equal to 0.

This functionality only works correctly in an appropriate security environment like in the DirX Identity environment configured in security mode. (See DirX Identity Connectivity Administration Guide).

The following table describes the codes provided when ADSAgent.exe finishes running:

Exit Code Description

0

ADSAgent completed successfully.

1

ADSAgent completed with errors, which are described in the specified error_file unless this file cannot be created due to a file exception error.

60

ADSAgent completed with warnings, which are described in the specified error_file.

Configuration File Formats

ADSAgent uses the following configuration files:

  • ADS export configuration file - controls the export of data from an Active Directory

  • ADS import configuration file - controls the import of data into an Active Directory

Templates of these configuration files are provided with the ADSAgent installation. The filenames are:

  • ExportAds.ini (to export all object classes (Users, Groups, Sites, Services, Computers, Schema Objects))

  • ImportAds.ini (to import all User and Group object classes to Active Directory)

In general, you must customize these files to support the requirements of your Active Directory import and export operations.

This section also describes the general structure of a configuration file.

General Structure of a Configuration File

An ADSAgent configuration file consists of sections and fields defined within those sections. A configuration file has the following structure:

[SectionName]

<comment> _
sectionField_*=*fieldValue
.
.
.
[SectionName]

<comment>
sectionField=fieldValue
.
.
.

SectionName is a keyword enclosed in square brackets ([ ]) that identifies the purpose of the section. sectionField is a keyword that identifies the field and fieldValue is the value assigned to the section field, preceded by the equal sign (=). For example:

SearchScope=2

Comments can be inserted anywhere in a configuration file and are identified by any character-for example, a # character or a semicolon (;)-that appears at the beginning of a line.

Export Configuration File Format

The ADSAgent export configuration file consists of the following sections:

  • The Version section (required)

  • The Connection section (required)

  • The SearchPreferences section (optional)

  • The SearchFilter section (optional)

  • The SelAttributes section (optional)

  • The Attributes section (optional)

  • The Configuration section (optional)

  • The DeltaExport section (optional)

The Version Section

The Version section consists of a single field that specifies the export configuration file version. The syntax is:

Version=version_number

where version_number is the version number assigned to the configuration file, in the format n*.*nn. The current version is:

Version=1.05

This is a mandatory field. This document describes the latest version of the ADSAgent export configuration file. The ADSAgent is able to process configuration files with version number 1.05 or lower as well as "old" files that do not contain a Version section. The following table provides information about the differences between export configuration file versions and about the support of older export configuration file versions for compatibility reasons:

"Old" 1.00 1.01 or higher

TraceLevel

Supported

Not supported

Not supported

Trace

Not supported

Supported (1)

Supported

(1) TraceLevel has been replaced by Trace.

The following new sections or section fields have been added to the specified version and do not conflict with older versions. These sections and fields are optional: if present, they are performed, if not, the default behavior is performed.

Version 1.03:

[Connection]
UseSealing

Version 1.04:

[SearchPreferences]
ChaseReferrals

Version 1.05:

[Connection]
UseSigning
UseDelegation

The Connection Section

The Connection section is a mandatory section that consists of fields that define the parameters of an export operation for ADSAgent. The next sections describe these fields.

SearchBase

The SearchBase field specifies the base within the Active Directory from which to export entries. The syntax is:

SearchBase=LDAP://host_name[:port_number][/distinguished_name]

where:

  • host_name specifies a computer name, an IP address, or a domain name. This is an optional component when ADSAgent is running on a Windows system. If it is not specified, the ADSI protocol locates the best domain controller in the system’s site (the local area network to which the machine belongs) and connects to that controller.

  • port_number specifies the port on host_name on which the Microsoft Active Directory LDAP server listens for requests. If port_number is not specified, ADSAgent uses the default LDAP port number 389.

  • distinguished_name specifies the name of the target Active Directory root, in top-down (DAP-style) or bottom-up (LDAP-style) naming format.

For example:

SearchBase=LDAP://Saturn/DC=MyCompany/DC=DirXIdentity/OU=Development

or:

SearchBase=LDAP://DC=MyCompany/DC=DirXIdentity/OU=Development

on Windows systems. Any comma (,) and forward slash (/) characters that are present in naming attribute values of distinguished_name must be "escaped" with the backslash character. For example:

SearchBase=LDAP://Venus/DC=OpTech\, Inc./DC=Talk2/OU=Sales

Active Directory supports the concept of "server-less" binding, which means that you can bind to Active Directory on the default domain without having to specify the name of a domain controller. When processing a server-less binding call, ADSI finds the "best" Windows domain controller in the default domain, which is the domain associated with the current security context of the thread that is performing the bind (the logged-on user on the machine on which the ADSAgent runs). ADSI uses DNS to find the domain controller and first looks in the client’s computer’s site, which is usually defined as an IP subnet.

The SearchBase field is a mandatory field.

UserName

The UserName field specifies the Windows account that ADSAgent is to use when binding to the Active Directory server during the export procedure. The syntax is:

UserName=Windows_account_name

For example:

UserName=Smith@dirxidentity.mycompany

This is an optional field; if it is not specified or is not present in the configuration file, ADSAgent uses the Windows account that invoked it when binding to the Active Directory server. If you specify a UserName field value, you must also specify a Password field value.

You can specify UserName in user principle name (UPN) format (which is the recommended form) as in the example just shown, or in a DN format, like cn=Smith,ou=sales,dc=dirxidentity,dc=mycompany or in the format of previous Windows versions like dirxidentity\Smith, where dirxidentity is the domain_name and Smith the account_name. If you use this format, you must set the UseSecureAuthentication field to 1.

If ADSAgent runs on a Windows NT system, you must specify the UserName in the form for previous Windows versions or specify no UserName (and consequently set UseSecureAuthentication field to 1) if you want to set passwords for the users to be imported to ADS.
On Windows XP you must also set the UseSecureAuthentication field to 1 if you want to set passwords for the users to be imported to ADS. For further hints concerning password setting for users see the section Import Data File Format → Setting a Password for a User.
If you want to get the deleted objects in a delta export the account specified under UserName must be a member of the DomainAdmin group of the domain from which the entries are exported.
Password

The Password field specifies the password for the Windows account name specified in the UserName field. The syntax is:

Password=password

For example:

Password=fidlajsks

This is an optional field; if no value is specified in this field or the field is not present in the configuration file, ADSAgent uses the password used with the Windows account that invoked it when binding to an Active Directory server during an export procedure. If you specify a Password field value, you must also specify a UserName field value.

UseSecureAuthentication

The UseSecureAuthentication field controls the level of authentication that ADSAgent uses when binding to an Active Directory server during the export procedure. The syntax is:

UseSecureAuthentication=switch

where switch is one of the following values:

  • 0 - Use simple authentication (default)

  • 1 - Use secure authentication

The UseSecureAuthentication field is used in conjunction with the UseEncryption field to set the level of security services used during the export procedure. If the UseSecureAuthentication field is set to 1, a secure authentication is requested using the Security Support Provider Interface (SSPI). In Windows 20xx, an SSP for Kerberos and an SSP for NT LAN Manager (NTLM) is included. Either of these protocols can be used for authentication. The SSP used depends on the capabilities of the computer on the other side of the connection, but Kerberos is always the first choice. When the UserName and Password are NULL, ADSI binds to the object using the security context of the calling thread, however in simple binds when using NULL credentials, ADSI does an anonymous bind.

The UseSecureAuthentication field must be set to 1 on Windows NT and Windows XP systems in order to set user passwords. However, on Windows NT (due to a bug in the Adsi NT version), a bind to the deleted objects container fails if this field is set. As a result, you must use different bind settings for ADSAgent import (set UseSecureAuthentication to 1) and ADSAgent export (set UseSecureAuthentication to 0).
UseEncryption

The UseEncryption field controls whether or not the Secure Socket Layer (SSL) port is used to provide a secure channel during the export procedure. The syntax is:

UseEncryption=switch

where switch is one of the following values:

  • 0 - Do not use SSL encryption (default)

  • 1 - Use SSL encryption

The UseEncryption field is used in conjunction with the UseSecureAuthentication field to set the level of security services used during the export procedure. If the UseEncryption field is set to 1 data will be encrypted using SSL. Active Directory requires that the Certificate Server is installed to support SSL encryption.

ADSI is designed to use simple binds when using SSL. Simple binds send UserName and Password in clear text across the network. Without using SSL this is not acceptable method under security aspects, but using SSL the network traffic is encrypted and the UserName and Password are protected. Because ADSI does an anonymous bind when using NULL credentials in simple binds, which would result in not having sufficient permissions to view and modify objects in the Active Directory, we recommend the following combination of the flags if a secure connection is wanted:

Set the UseSecureAuthentication field to 0 and the UseEncryption field to 1 to establish an SSL connection and pass a UserName and a Password. You can pass the UserName either in DN form, such as cn=Smith,ou=Development, dc=dirxidentity,dc=mycompany or in the UPN form, such as Smith@dirxidentity.mycompany. We recommend the UPN form. To use the UPN form, you must have assigned the appropriate UPN value for the userPrincipalName attribute of the targeted user object.

Another possible method is to specify the SSL channel in the SearchBase field, such as

LDAP://Saturn.dom.comp:636/dc=mycompany/dc=dirxidentity/ou=development

and also passing the UserName with a Password. This has the same effect as setting the UseEncryption field.

Prerequisites for running ADSAgent with SSL:

If you want to run ADSAgent with SSL you must perform the following steps:

  • Install a CA (Certificate Authority) on the Active Directory Server. This installation generates the root certificate which must be named with the full qualified server name.

  • Import the certificate generated in the step above to the Windows client certificate store on the machine where the agent runs. To import the certificate you can use the Internet Explorer. (Menu Tools → Internet Options → Content → Certificates → Trusted Root Certification Authorities → Import.)

  • Note: When importing the certificate into the Trusted Root Certification Authorities as described above you must be logged in into Windows as the same user as the ADSAgent runs with. The ADSAgent runs under the user the C-Server Service was started with or if you explicitly configured a user in the ADS Job Configuration Authentication Tab it runs with that user.

See section "LDAP SSL Setup" in chapter "Identity Connectors" how to setup an SSL connection to an Active Directory Server.

UseSealing

The UseSealing field controls whether or not the data is encrypted using Kerberos during the export procedure. The syntax is:

UseSealing=switch

where switch is one of the following values:

  • 0 - Do not use Kerberos encryption (default)

  • 1 - Use Kerberos encryption

If the UseEncryption field is set to 1 data will be encrypted using Kerberos. The UseSecureAuthentication field must also be set to 1 in order to use the sealing. Kerberos encryption and authentication work under the following conditions:

  • The client computer must be a member of a Windows mixed mode or native mode domain.

  • The client must be logged on to the Windows domain, or to a domain trusted by a Windows domain.

UseServerBind

The UseServerBind field can be used for Windows versions greater than Windows 2000 SP1 if a server name is specified in the SearchBase (instead of a serverless bind) to reduce network traffic . The syntax is:

UseServerBind=switch

where switch is one of the following values:

  • 0 - for serverless binds and as default for binds to a specific server (default)

  • 1 - If a servername is specified and network traffic is very high.

UseSigning

The UseSigning field can be used to verify data integrity. The UseSecureAuthentication flag must also be set to use signing. The syntax is:

UseSigning=switch

where switch is one of the following values:

  • 0 - no signing (default)

  • 1 - verifies data integrity.

UseDelegation

The UseDelegation field can be used to delegate the bind user security context to another domain. The syntax is:

UseDelegation=switch

where switch is one of the following values:

  • 0 - no delegation (default)

  • 1 - delegates the bind user security context to another domain.

The SearchPreferences Section

The SearchPreferences section is an optional section that consists of fields that specify parameters for search operations in Active Directory. The next sections describe these fields.

SearchScope

The SearchScope field specifies the search scope for search filters specified in the SearchFilter section. The syntax is:

SearchScope=number

where number is one of the following values:

  • 0 - Limits the search scope to the entry specified in the SearchBase field

  • 1 - Limits the search scope to the children of the entry specified in the SearchBase field

  • 2 - Limits the search scope to the subtree below the entry specified in the SearchBase field (default)

PageSize

The PageSize field controls how Microsoft Active Directory server is to return search results to ADSAgent for a single search operation. The syntax is:

The syntax is:

PageSize=number

where number is one of the following values:

  • 0 - Processes the entire search result set before returning it to ADSAgent (default)

  • n - Processes and returns the search result in pages, where each page has a maximum of n entries. When a search results page contains n entries, Active Directory server returns the page to ADSAgent.

You can use the PageSize field to maintain client-server performance in cases where large result sets are being processed and returned. Specifying a number in PageSize directs the Active Directory server to process only that number of entries before returning the data to ADSAgent; this prevents large amounts of Active Directory server memory from being tied up while the server acquires the search results data and allows for scalable search operations. If you have more than 1000 entries to export, you must set a PageSize field value. We recommend that you set this field to a value between 100 and 500 for best performance.

PagedTimeLimit

The PagedTimeLimit field controls the length of time that Microsoft Active Directory server is to search for a single page. The syntax is:

The syntax is:

PagedTimeLimit=number

where number is one of the following values:

  • 0 - No time limit on the search of one page (default)

  • n - The maximum number of seconds to search for one page; specify a non-negative integer

AsynchronousSearch

The AsynchronousSearch field controls whether Microsoft Active Directory server performs synchronous or asynchronous search operations. The syntax is:

AsynchronousSearch=switch

where switch is one of the following values:

  • 0 - A single search operation must complete before a new search operation can begin (default)

  • 1 - A new search operation can start while a current search operation is being processed

When AsynchronousSearch is set to 1, a new search can be started when the Active Directory server returns the first entry. When a number in PageSize is specified and AsynchronousSearch is set to 1, a new search can be started when the Active Directory server returns the first page of search results. If AsynchronousSearch is set to 0, a new search operation cannot be started until Active Directory server returns the entire results set.

CacheResults

The CacheResults field controls whether ADSAgent caches search results in its local memory. The syntax is:

CacheResults=switch

where switch is one of the following values:

  • 0 - Do not cache results

  • 1 - Cache results (default)

TimeLimit

The TimeLimit field controls whether ADSAgent imposes a time limit for search results to be returned from Microsoft Active Directory server. The syntax is:

The syntax is:

TimeLimit=number

where number is one of the following values:

  • 0 - No time limit is imposed on search operations (default)

  • n - A time limit n is imposed on search operations, where n is the time in seconds after which ADSAgent is to abandon the search operation

ChaseReferrals

The ChaseReferrals field controls whether and how ADSAgent chases referrals. When an Active Directory server determines that another server holds relevant information (for example, when you have child domains and search in the parent domain), it may refer the ADsAgent to another server to obtain the result. Referral chasing is the action taken by a client to contact the referred-to server to continue the directory search. When the ADSAgent receives a referral message, it can decide whether to ignore or chase (follow) this referral. The syntax is:

ChaseReferrals=switch

where switch is one of the following values:

  • 0 - Referrals are not chased (default).

  • 1 - Referrals are chased in subordinate namespaces (turned off for paged searches)

  • 2 - Referrals are chased in external namespaces.

  • 3 - Referrals are always chased.

The SearchFilter Section

The SearchFilter section is an optional section that specifies the Active Directory entries that are to be exported from the Active Directory and can control whether or not ADSAgent performs a delta export. The section consists of one or more LdapFilter fields. Each LdapFilter field specifies a collection of entries to locate and export. The syntax is as follows:

LdapFilter=filter

where filter is a search string specified in LDAP filter syntax; see RFC 2254 for an explanation of this syntax. For example:

LdapFilter=(objectClass=*)

The following table shows some sample LDAP filters and their results.

Filter Value Action Taken

(objectClass=*)

Export all entries

(objectClass=user)

Export all user entries

(objectClass=group)

Export all group entries

(&(objectClass=*) (sn=a*))

Export all entries whose surname begins with "a"

(&(objectCategory=attributeSchema) (isMemberOfPartialAttributeSet=TRUE))

Export all attributeSchema entries which are in the Global Catalog

When specifying attributes in filter, you must use the LDAP names for the attributes.

ADSAgent creates one export data file. If the DeltaExport field in the DeltaExport section is set to 0, this file contains all of the entries extracted from the Active Directory that match the search criteria specified in the SearchPreferences and SearchFilter sections. This file is called the "export data file" (or "full export data file").

Use the Delta Export fields DeltaExport (set to 1) and the HighestCommittedUSN field to create a search filter that performs a "delta" export of modified entries into the generated export data file. See the description of the DeltaExport section for further details.

Active Directory moves deleted entries ("objects", in Active Directory terminology) to the "Deleted Objects" container in the naming context in which the entries originally existed. For example, the user Smith in //Saturn/DC=mycompany/DC=DirXIdentity/OU=Development is moved to //Saturn/DC=mycompany/DC=DirXIdentity/CN=Deleted Objects. Since the Deleted Objects container is itself marked as deleted, it is not seen in a normal search. When Active Directory deletes an entry, it sets the entry’s "isDeleted" attribute to TRUE; the entry is then known as a tombstone. Active Directory retains a tombstone for a configurable period of time (60 days by default), after which it completely removes it. The RDN and objectGUID attribute values of deleted entries are always saved; the schema determines the other attributes that are to be saved. The RDN is changed to ensure uniqueness within the Deleted Objects container.

This is an optional field. If no value is specified or the field is not present in the configuration file, ADSAgent exports all entries.

The SelAttributes Section

The SelAttributes section is an optional section of the export configuration file that controls whether or not ADSAgent retrieves all entry attributes with a value, or only those attributes set to 1 in the Attributes section. The section consists of one field, which is SelectAttributes. The syntax is:

SelectAttributes=switch

where switch is one of:

  • 0 - Export all attributes with a value (default)

  • 1 - Export only those attributes set to 1 in the Attributes section

This field must be set to 1 to perform a delta export operation. See the DeltaExport section for more information about the delta export operation.

The Attributes Section

The Attributes section is an optional section of the export configuration file that specifies a set of Active Directory attributes to be exported from a Active Directory. The syntax is:

attribute_name=switch

where attribute_name is the name of an Active Directory attribute and switch is one of the following values:

  • 0 - Do not export the attribute value for attribute_name

  • 1 - Export the attribute value for attribute_name

For example:

[Attributes]
#Attributes of the Object Class Person
#Subclass of Top
#
seeAlso=0
sn=1
telephoneNumber=1
#
#Attributes of the Object Class organizationalPerson
#Subclass of Person
#
co=1
company=0
countryCode=1
department=1
facsimileTelephoneNumber=1
...
#

Use the switch parameter to select or exclude attributes in the list for export.

If the Attributes section is not specified in the configuration file and SelectAttributes is set to 0 in the SelAttributes section, ADSAgent exports all of the attributes of Active Directory entries that match the search criteria specified in the SearchPreferences and SearchFilter sections. If SelectAttributes is set to 1 and the Attributes section does not contain any attributes that are set to 1, nothing is exported.

The Configuration Section

The Configuration section is an optional section that contains information that ADSAgent is to use when evaluating entry attributes during the export procedure. The next sections describe the fields in the Configuration section.

MultiValueSeparator

The MultiValueSeparator field specifies a value to be used to separate the individual attribute values of a multi-valued attribute. The syntax is:

MultiValueSeparator=[character]

where character is a character or a string used as a multi-valued attribute separator. For example:

MultiValueSeparator=#

This field is optional. If it is not specified (or not present in the configuration file), ADSAgent uses the pound sign (#) as the multi-valued attribute separator.

Trace

The Trace field controls whether ADSAgent performs program flow tracing on an export operation. The syntax is:

Trace=[switch]

where switch is one of the following values:

  • 0 - Do not perform program flow tracing on the export operation (default)

  • 1 - Perform program flow tracing on the export operation

If 1 is specified, ADSAgent writes information about the export operation to the pathname specified in the TraceFileName field.

TraceFileName

The TraceFileName field specifies the pathname of the trace file to which ADSAgent is to write information about the export operation. The syntax is:

TraceFileName=pathname

where pathname is the name for the trace file. For example:

TraceFileName=c:\Adssync\ExportTraceFile

This field is optional unless Trace is set to 1. ADSAgent does not evaluate this field if Trace is set to 0.

The DeltaExport Section

The DeltaExport section is an optional section that provides information that can be used to direct ADSAgent to perform a delta export of entries from the Active Directory.

The next sections describe the fields in the DeltaExport section.

DeltaExport

The DeltaExport field controls whether ADSAgent performs a full or delta export of the Active Directory. The syntax is:

DeltaExport=[switch]

where switch is one of the following values:

  • 0 - Export all entries (or those entries specified with the LDAPFilter field) from the directory (default)

  • 1 - Export only those entries whose uSNChanged attribute value is greater than or equal to the value of the HighestCommittedUSN field.

If the DeltaExport field is set to 1:

  • The Delta Export section must contain the HighestCommittedUSN field and value

  • The SelectedAttributes field in the SelAttributes section must be set to 1.

This is an optional field. If it is not specified (or the field is not present in the configuration file), ADSAgent exports all entries in the directory (or all the entries selected using the specifications in the LDAPFilter field, if it is present in the configuration file) from the Active Directory.

HighestCommittedUSN

The HighestCommittedUSN field specifies the highest-numbered uSNChanged attribute value in the Active Directory. The syntax is:

HighestCommittedUSN=USN

where USN is an integer that represents the highest-number USN assigned to an Active Directory container entry in the directory. For example:

HighestCommittedUSN=6426

The uSNChanged attribute is a Microsoft Active Directory attribute that is assigned to every entry in the Active Directory. When the Active Directory server carries out a modification to an entry, it assigns the highest USN to the entry’s uSNChanged attribute as its value.

For the initial delta export, you must:

  • Set the value of HighestCommittedUSN to 0:

  • Set the DeltaExport field to 1

ADSAgent appends the search filter in LdapFilter with the part (uSNChanged greater than or equal to 1) to select only those entries modified after the uSNChanged value provided in the filter (all entries, in this export run). When it completes the export, ADSAgent updates the HighestCommittedUSN field with the current highest uSNChanged attribute value.

On subsequent exports, each time ADSAgent performs an export and the DeltaExport field is set to 1, it writes the value in the HighestCommittedUSN field to the LdapFilter field, performs the export, and updates the HighestCommittedUSN field with the current highest uSNChanged attribute value.

that performing incremental delta exports works only if you do not change the search filters in the export configuration file. If you make changes to search filters in the SearchFilter section, you will need to perform a full export and re-set the HighestCommittedUSN attribute.

Import Configuration File Format

The ADSAgent import configuration file consists of three sections:

  • The Version section (required)

  • The Connection section (required)

  • The Configuration section (optional)

  • The Ignore Empty Attributes section (optional)

  • The Encrypted Attributes section (optional)

  • The AttributeTypes section (required)

The Version Section

The Version section consists of a single field that specifies the import configuration file version. The syntax is:

Version=version_number

where version_number is the version number assigned to the configuration file, in the format n*.*nn. The current version is:

Version=1.02

This is a mandatory field. This document describes the latest version of the ADSAgent import configuration file. This document describes the latest version of the ADSAgent import configuration file. The ADSAgent is able to process configuration files with version number 1.03 or lower as well as "old" files that do not contain a Version section. The following table provides information about the differences between import configuration file versions and about the support of older import configuration file versions for compatibility reasons:

"Old" 1.00 1.01 and higher

TraceLevel

Supported

Not supported

Not supported

Trace

Not supported

Supported (1)

Supported

SearchBase

Not supported

Not supported

Supported

(1) TraceLevel has been replaced by Trace.

The following new sections or section fields have been added in the specified version and do not conflict with older versions. These sections and fields are optional: if present, they are performed, if not, the default behavior is performed.

Version 1.02:

[IgnoreEmptyAttrValues]
[EncryptedAttributes]
Version 1.03:
[Connection]
UseSealing

The Connection Section

The Connection section is a mandatory section that consists of fields that define the parameters of an import operation for ADSAgent. The next sections describe these fields.

UserName

The UserName field specifies the Windows account that ADSAgent is to use when binding to the Active Directory server during the import procedure. It has the same syntax as the UserName field in the export configuration file.

Password

The Password field specifies the password for the Windows account name specified with the UserName field. It has the same syntax as the Password field in the export configuration file.

UseSecureAuthentication

The UseSecureAuthentication field controls the level of authentication that ADSAgent uses when binding to an Active Directory server during the import procedure. It has the same syntax as the UseSecureAuthentication field in the export configuration file.

UseEncryption

The UseEncryption field controls whether or not the Secure Socket Layer (SSL) port is used to provide a secure channel during the import procedure. It has the same syntax as the UseEncryption field in the export configuration file.

UseSealing

The UseSealing field controls whether or not data is Kerberos-encrypted during the import procedure. It has the same syntax as the UseSealing field in the export configuration file.

UseServerBind

The UseServerBind field can be used in Windows versions greater than Windows 2000 SP1 if a server name is specified in the Ads Bind Path (instead of a serverless bind) to reduce network traffic. It has the same syntax as the UseServerBind field in the export configuration file.

UseSigning

The UseSigning field controls whether or not data integrity is verified during the import procedure. It has the same syntax as the UseSigning field in the export configuration file.

UseDelegation

The UseDelegation field controls whether or not the bind user security context is delegated to another domain during the import procedure. It has the same syntax as the UseDelegation field in the export configuration file.

SearchBase

The SearchBase field specifies the base within the Active Directory from which to search for matching entries using the search criteria specified in the "ldapFilter" attribute of each entry in the import data file. The syntax is:

SearchBase=LDAP://host_name[:_port_number_][/distinguished_name]

where:

  • host_name specifies a computer name, an IP address, or a domain name. This is an optional component when ADSAgent is running on a Windows system. If it is not specified, the ADSI protocol locates the best domain controller in the system’s site (the local area network to which the machine belongs) and connects to that controller.

  • port_number specifies the port on host_name on which the Microsoft Active Directory LDAP server listens for requests. If port_number is not specified, ADSAgent uses the default LDAP port number 389.

  • distinguished_name specifies the name of the target Active Directory root, in top-down (DAP-style) or bottom-up (LDAP-style) naming format.

For example:

SearchBase=LDAP://Saturn/DC=MyCompany/DC=DirXIdentity/OU=Development

or

SearchBase=LDAP://DC=MyCompany/DC=DirXIdentity/OU=Development

on Windows systems. Any comma (,) and forward slash (/) characters that are present in naming attribute values of distinguished_name must be "escaped" with the backslash character. For example:

SearchBase=LDAP://Venus/DC=OpTech\, Inc./DC=Talk2/OU=Sales

The SearchBase field is a mandatory field when the import data file uses the "ldapFilter" attribute. See the section "Import Data File Format" for further details.

The Configuration Section

The Configuration section is an optional section that consists of fields that contain information that ADSAgent is to use when evaluating entry attributes in an import data file. The next sections describe these fields.

MultiValueSeparator

The MultiValueSeparator field specifies a value to be used to separate the individual attribute values of a multi-valued attribute. The syntax is the same as the MultiValueSeparator field in the export configuration file.

IgnoreObjectClass

The IgnoreObjectClass field controls whether ADSAgent evaluates or ignores the objectClass attribute of entries for which the "modify" LDIF changetype operation has been specified. The syntax is:

IgnoreObjectClass=switch

where switch is one of the following values:

  • 0 - Evaluate the objectClass attribute when the changetype operation is "modify"

  • 1 - Ignore the objectClass attribute when the changetype operation is "modify" (default)

Active Directory server does not currently permit the modification of the objectClass attribute through an LDIF "changetype" operation. Consequently, you can set the IgnoreObjectClass field to 1 to direct ADSAgent not to pass the ObjectClass attribute to the Active Directory server. However, other LDAP servers do permit the modification of the objectClass attribute. Setting IgnoreObjectClass to 0 in this case permits ADSAgent to pass the objectClass attribute to the LDAP server for evaluation.

Trace

The Trace field controls whether ADSAgent performs program flow tracing on an import operation. It has the same syntax as the Trace field in the export configuration file and is an optional field.

TraceFileName

The TraceFileName field specifies the pathname of the trace file to which ADSAgent is to write information about the import operation. It has the same syntax as the TraceFileName field in the export configuration file and is an optional field unless the Trace field is specified.

RejectSpecialCharacters

The RejectSpecialCharacters field controls whether ADSAgent evaluates the ADsPath attribute of entries in the import data file for special characters. The syntax is:

RejectSpecialCharacters=switch

where switch is one of the following values:

  • 0 - Do not evaluate the ADsPath attribute for special characters (default)

  • 1 - Evaluate the ADsPath attribute for special characters

If 1 is specified, ADSAgent scans the Common-Name (cn) RDN of each import entry’s ADsPath attribute for the characters specified in the RejectedCharacters field and rejects the entry for import if it contains one of these characters.

RejectedCharacters

The RejectedCharacters field specifies the characters in the import entries' AdsPath attribute that ADSAgent is to scan for; ADSAgent is to reject the entry for import if it contains one of these characters. The syntax is:

RejectedCharacters=characters

Where characters specifies the characters in the Common-Name RDN of the AdsPath attribute for which ADSAgent is to search.

This field is optional unless RejectSpecialCharacters is set to 1. ADSAgent does not evaluate this field if RejectSpecialCharacters is set to 0.

The Ignore Empty Attributes Section

The Ignore Empty Attributes section is an optional section that lists attributes which are ignored if they exist in the import data file and if they are empty. Normally an attribute with an empty value results in clearing that attribute in the Active Directory. The attributes are listed in the format:

name_of_attribute=1

where name_of_attribute is the name for the attribute to be imported.

For example:

[IgnoreEmptyAttrValues]
description=1
Password=1

The Encrypted Attributes Section

The Encrypted Attributes section is an optional section that lists attributes which are encrypted in the import data file and have to be decrypted by the agent before they are passed to the Adsi Interface. This functionality only works correctly in an appropriate security environment like in the DirX Identity environment configured in security mode. (See DirX Identity Connectivity Administration Guide). The attributes are listed in the format:

name_of_attribute=1

where name_of_attribute is the name for the attribute to be imported.

For example:

[EncryptedAttributes]
Password=1

The Attribute Types Section

The Attribute Types section is a mandatory section that specifies the attribute syntax for each Active Directory attribute to be imported into the Active Directory. The section consists of one or more attribute syntax specifications in the format:

LDAP_name_of_attribute=attribute_syntax

where LDAP_name_of_attribute is the LDAP name for the Active Directory attribute to be imported and attribute_syntax is one of the following keywords:

  • Boolean
    CaseExactString
    CaseIgnoreString
    DNstring
    Integer
    LargeInteger
    NumericString
    ObjectClass
    OctetString
    PrintableString
    ProviderSpecific
    UTCTime

Each of these keywords corresponds to a data type that can be passed over the Active Directory Services Interface (ADSI). Because ADSAgent uses this interface, it must specify the data type of each attribute it passes over the interface. The Attribute Types section provides ADSAgent with the information it needs about each attribute’s ADSI data type.

For example:

[Attribute Types]
changetype=CaseIgnoreString
objectClass=CaseIgnoreString
company=CaseIgnoreString
cn=CaseignoreString
department=CaseIgnoreString
member=DNString
userAccountControl=Integer

Export and Import Data File Format

The ADSAgent import and export data files use a tagged file format. This section describes:

  • The general characteristics of export and import data file formats

  • The specific features of the import data file format

General Data File Format

The ADSAgent import and export data files have the following characteristics:

  • Each entry attribute is contained on one line; line continuation is not permitted.

  • The representation of each attribute is attribute_name:attribute_value(s)

  • Leading and trailing whitespace between attribute_name and attribute_value is ignored. For example, in the attribute:

           cn:   SallyAnn K. Quebec

    The whitespace between the colon (:) and the start of the attribute value is ignored, but the whitespace within the attribute value is returned

  • The form-feed character (0x0c) is used as a record (entry) separator

  • The form-feed character can optionally appear as the first line in the file

  • There is no special character processing (there is no "escaping" mechanism)

Here is an example:

(0x0c is here as a record (entry) separator)
changetype: delete
objectClass: user
cn: Robert Amber
telephoneNumber: 603 555 8845
givenName: Robert
l:Nashua, New Hampshire
postalAddress: 110 Spitbrook Road
postalCode: 03060
sn: Amber
(0x0c is here as the record (entry) separator)
...

Import Data File Format

ADsPath

Individual entries in a single import data file can be targeted for import to different containers or Active Directory servers. Consequently, each entry in an ADSAgent import data file must contain an ADsPath attribute that identifies the fully-qualified pathname of the user or group entry to be added, modified, or deleted. The attribute syntax is:

ADsPath:LDAP://host_name[:_port_number_][/distinguished_name]

where:

  • host_name specifies a computer name, an IP address, or a domain name. This is an optional component when ADSAgent is running on a Windows system. If it is not specified, the ADSI protocol locates the best domain controller in the system’s site (the local area network to which the machine belongs) and connects to that controller.

  • port_number specifies the port on host_name on which the Microsoft Active Directory LDAP server listens for requests. If port_number is not specified, ADSAgent uses the default LDAP port number 389.

  • distinguished_name specifies the name of the target Active Directory root, in top-down (DAP-style) or bottom-up (LDAP-style) naming format.

For example:

ADsPath: LDAP://Mars/DC=MyCompany/DC=DirXIdentity/OU=TestUsers/CN=Hans Hase

or

ADsPath: LDAP://DC=MyCompany/DC=DirXIdentity/OU=TestUsers/CN=Hans Hase

on Windows systems.

ldapFilter

The ADSAgent import data file format also supports a per-entry ldapFilter attribute. The value of this attribute is a search filter that specifies an attribute that acts as a unique key for matching the entry in the import data file with an entry in an Active Directory. The attribute syntax is:

ldapFilter: filter

where filter is a search string specified in LDAP filter syntax (see RFC 2254 for an explanation of this syntax) that uses an attribute as a unique identifier. For example:

ldapFilter: (&(objectClass=user) (sAMAccountName=Hase4))

We recommended using the sAMAccountName attribute as the unique key in the ldapFilter attribute; however, other attributes can be defined and used as keys. If a new attribute is defined for use as a unique key, the meta directory schema must be extended to include this attribute definition.

When a "modify" or "delete" entry (see the per-entry changetype attribute) in the import data file contains an ldapFilter attribute, and an ADsPath attribute is not present, ADSAgent uses the ldapFilter attribute to search the Active Directory specified in the SearchBase field using the scope specified in the SearchScope field (or the default). If ADSAgent finds one entry ("object" in Active Directory terminology) that matches the filter criteria, ADSAgent modifies or deletes the entry, according to its changetype attribute. If ADSAgent finds more than one matching entry, or does not find a matching entry at all, it writes an error to the import error file.

Per-Entry Changetype

The ADSAgent import data file format supports the LDIF per-entry "changetype" attribute that indicates the type of modification to be made to the entry in the Active Directory and the attribute operation codes "add" or "delete". The value for "changetype" is one of "add", "modify", "delete", or "move". The changetype attribute name and its values are case-insensitive and can appear anywhere in the entry. If a changetype attribute is not present (or does not contain a value), ADSAgent attempts an "add" operation for the entry. If the "add" operation fails with the error code "entry already exists", it attempts a "modify" operation. If the "modify" operation fails with the error code "no such object", ADSAgent attempts a "move" operation if either the attribute AdsPathOld or ldapFilter exists in the entry. After every move operation, the ADSAgent performs a modify on the attributes contained in the entry.

Entries that contain the "add" "modify" or "delete" changetype attributes must contain the ADsPath attribute or the ldapFilter attribute (or both). Entries with a "modify" changetype attribute value must also contain at least one attribute to be modified. If the modify operation fails with the error code "no such object", it attempts to find the object using the ldapFilter attribute, if present, and then performs the modify operation. Entries with an "add" changetype must contain an object class attribute. Entries that contain the "move" changetype attribute must contain the ADsPath attribute, and either the ADsPathOld attribute or the ldapFilter attribute (in the "move" case, the ADsPath attribute specifies the destination for the entry and ADsPathOld or ldapFilter are used to identify the entry to be moved.)

In a "modify" operation, attributes can be deleted either by setting their values to an empty string or by setting them to the string value <clear>.

In a "modify" or a "delete" operation, the AdsPath can contain the GUID of an object, which is kept in the attribute "objectGuid", instead of its distinguished name. For example:

changetype: delete

ADsPath: LDAP://Saturn/<GUID=2e7330f0e8d24f49bc98de7045bf54b5>

Mandatory Attributes

Depending on the object class attribute value, the following attributes must also be present in the entry:

  • For users (objectClass=user), the attribute sAMAccountName must be present and should be fewer than 20 characters in length. The second mandatory attribute cn (=RDN) is taken from ADsPath and for the third mandatory attribute userAccountControl a default is taken. Mailbox-enabled user entries must have the mandatory attributes mail, legacyExchangeDN, proxyAddresses, showInAddressBook, textEncodedORAddress, msExchHideFromAddressLists, homeMTA, homeMDB, msExchHomeServerName, mailNickName, and mDBUseDefaults. When it creates a mailbox-enabled user in the Active Directory, ADSAgent uses the value in msExchHomeServerName to create the mandatory attribute msExchMailboxSecurityDescriptor. Mail-enabled user entries must have the mandatory attributes mail, legacyExchangeDN, proxyAddresses, showInAddressBook, textEncodedORAddress, msExchHideFromAddressLists, mailNickName, and mDBUseDefaults.

  • For groups (objectClass=group) the attribute sAMAccountName must be present. Also here the mandatory attribute cn is taken from ADsPath and for the mandatory attribute groupType a default is taken.

  • All other objects with different object classes can also be imported, if the mandatory attributes for this object class are passed in the correct syntax and if the administrative rights of the user specified in the import configuration file are sufficient for this operation.

userAccountControl

In the following Microsoft Knowledge Base article describes how the values for the attribute userAccountControl can be set to manipulate user account properties:

http://support.microsoft.com/default.aspx?scid=kb;en-us;305144

Multi-Valued Attributes and Operation Codes for Attributes

The attributes for a multi-valued attribute appear on one line and are separated by the multi-valued attribute separator specified in the MultiValueSeparator field in the import configuration file. For example:

...

member: cn=Test1,ou=TestUsers,DC=DirXIdentity,DC=MyCompany#cn=Test2,ou=TestUsers,DC=DirXIdentity,DC=MyCompany#Test3,ou=TestUsers,DC=DirXIdentity,DC=MyCompany

For entries with a "modify" changetype, ADSAgent overwrites the specified attributes with the new values and the other attributes retain their old value. If an operation code for an attribute is specified, values for this attribute can be added or deleted. A sample for the syntax is given for the following entry:

changetype: modify
ADsPath: LDAP://Server1/CN=Hans Hase6,OU=TestUsers,DC=DirXIdentity,DC=mch,DC=sni,DC=de
sn: Hase6
add: otherTelephone
otherTelephone: 113#114#115
delete: otherTelephone
otherTelephone: 114#115

When a "move" entry in the import data file contains the ldapFilter attribute, ADSAgent uses the ldapFilter attribute to search the Active Directory specified in the SearchBase field. If ADS finds one matching entry, it moves the entry to the destination specified in the ADsPath attribute for the entry in the import data file. When a "move" entry contains the OldADsPath attribute, ADSAgent uses this ADsPath to locate the entry, then moves it to the destination specified in the ADsPath attribute. An ADS entry can be moved within the same domain or from different domains in the same directory tree. The following restrictions apply for cross-domain moves:

  • The destination domain must be in native mode.

  • The object to be moved must be a leaf object or an empty container

  • The operation requires Kerberos authentication (NTLM will not work). Set the UseSecureAuthentication field to 1 to enable Kerberos authentication.

  • When ADSAgent moves a security principal (user, group, computer and so on), a new SID for the object is created at the destination. However, the old SID from the source (stored in the sIDHistory attribute) and the object’s password are preserved.

  • Security principals that belong to a global group cannot be moved.

Comments

The import data file can contain comments, which are identified by a # character at the beginning of a line.

Setting a Password for a User

When a user entry in the import data file contains the Password attribute, ADSAgent passes the specified value to the Adsi function IADsUser::SetPassword, which sets the password for that user. The password is stored in the Active Directory user object attribute unicodePwd, which can be written under restricted conditions but cannot be read. In order for the Adsi function to work correctly, the following rules apply:

  • The user account specified in the import configuration file must have administrative rights in the Active Directory domain to which the user entry is imported.

  • If ADSAgent runs on a Windows NT system, the UserName field in the import configuration file must be specified in the form domain_name_username_ or not specified at all and the UseSecureAuthentication field must be set to 1.

  • If ADSAgent runs on a Windows XP system, the UseSecureAuthentication field must be set to 1.

  • The user account under which ADSAgent runs must have administrative rights in the destination domain, because the Adsi function setting the password calls Windows Security functions that use the credentials of the calling thread. On Windows XP, this function has changed: the password function uses the credentials specified in the configuration file.

  • For both Windows NT and Windows XP, if the machine on which ADSAgent runs is a member of a domain that is different from the domain into which the user entry is to be imported, a trust relationship must be established between both domains.

  • In a DirX Identity environment, a DirX Identity agent can be run with a special account (see the authentication tab in the job object), if the account of the DirX Identity server has advanced user rights in the Windows operating system. See the DirX Identity Connectivity Administration Guide for information about how to set these rights.

  • The AdsPath attribute of the entry in the import data file must either contain the server name of the destination Active Directory domain controller or an IP address without a port number. The reason for this restriction is that the Adsi function IADsUser::SetPassword does not work properly if the user object has bound with an AdsPath that contains an IP address and a port number.

  • If Windows password policies are set for the domain make sure that the user password and account flags contained in the attribute userAccountControl for each user are consistent with those domain policy settings. If for example the domain policies require a password for a user you must set the password_not_required flag (which is the default) in the userAccountControl attribute to be able to create the user by temporarily overwriting the domain settings. After creation of the user the password is set. For a detailed description of the attribute userAccountControl see the link mentioned above under the userAccountControl section.

Attributes of type OctetString

If an attribute in the import.ini file is specified with the OctetString data type, ADSAgent expects it to be base64-encoded in the import data file. In the export direction, ADSAgent writes attributes with type OctetString base64-encoded into the export data file.

Import Error File Format

During the import process, ADSAgent writes the original attributes and values of user or group entries that it is unable to import into the error file specified on the command line along with an error message that describes the error that caused the import to fail on the entry. Each error record in the import error file has the following format:

#warning_message
source_entry
#error_message

Where warning_message contains a warning text, source_entry is the original entry that ADSAgent was unable to import and error_message contains the function name that failed and an error code and error text. Entries can have either warning_message or error_message or both of them. Here is an example of an import error record:

#Warning! Cannot find Attribute Type of xxx. Attribute Ignored.
changetype: add
objectClass: organizationalPerson
ADsPath: LDAP://Mars:390/DC=MyCompany/DC=DirXIdentity/OU=TestUsers/CN=Hans Hase
sAMAccountName: Hase
userPrincipalName: Hase@DirXIdentity.mchp.mycompany.de
displayName: Hans Hase3
givenName: Hans
sn: Hase
userAccountControl: 544
streetAddress: Otto-Hahn-Ring 36
info: Notes1
company: MyCompany
department: MDS
description: Description1
xxx: test
mail: hans.hase@icn.mycompany.de
#Error! CreateDSObject of LDAP://Mars:390/DC=MyCompany/DC=DirXIdentity/OU=TestUsers/CN=Hans Hase failed. Error Code: 80071392 Error Text: The object already exists.

Any entry that cannot be imported into the Active Directory is written into the import error file. Consequently, you can use the error file as an input file and re-run the import operation, after first fixing the errors reported in the file. A timestamp is written at start and end of the import error file.

Creating Mail- and Mailbox-Enabled Users in Active Directory

When installing Exchange the schema of Active Directory is extended by Exchange related object classes and attributes. This allows the ADS Agent to create mail- and mailbox-enabled objects in Active Directory. A mail-enabled object can receive messages at an external address. A mailbox-enabled object has an Exchange mailbox associated with it, and can thus send and receive messages.

During the DirX Identity setup some sample import data files are installed to the samples subfolder, which show you how to create mail-enabled and mailbox-enabled users and mail-enabled groups and contacts.

Provisioning Exchange 2007 and Newer

The ADS Agent from Version 1.1.9.2 on supports mailbox guid generation, which is necessary for a full-functioning Exchange 2007 SP1 and newer mailbox.

If a data record in the import data file for the ADS Agent contains the attribute msExchRecipientTypeDetails it is assumed that an Exchange mailbox is supposed to be created or modified. The ADS Agent then generates a random globally unique mailbox identifier and modifies the user in Active Directory with the msExchMailboxGuid attribute set to this generated identifier in case the user’s msExchMailboxGuid attribute is not already set. The msExchMailboxGuid attribute of the Active Directory user is the link to the mailbox object in the Exchange Server Mailbox database and should not be overwritten.

Deleting Non-Leaf Objects

The ADS Agent supports the deletion of non-leaf objects. Non-leaf objects in Active Directory are no container objects, like OUs, but objects that are usually expected to be leaf objects, like users. Nevertheless, sometimes these objects are non-leaf objects because they have subentries in certain cases. For example, Active Directory creates subentries for mailbox-enabled users in special situations. Those subentries are only shown by the "Active Directory Users and Computers" tool if the "Users, Contacts, Groups and Computers as containers" setting is checked in the View menu entry.

If such a non-leaf object is to be deleted the ADS Agent automatically deletes this object with all its subentries.