*
Metamerge logo
Search

Advanced Search
*
*
*
* HOME DOCUMENTS & RESOURCES DOWNLOADS EARLY TECH ACCESS SUPPORT FAQ KNOWN ISSUES OLD VERSIONS
*

ADSI Connector Functional Specifications and Software Requirements

1. Overall Description

1.1. Overview

The ADSIConnector implements connector functionality for both user and group management on NT systems according to NT definitions and restrictions as outlined below.

1.2. Functionality

The ADSIConnector provides the following connector modes: Iterator,Lookup, AddOnly, Update, Delete, Passive.

1.2.1. Extract User/Group Data

ADSIConnector reads both user and group information from the NT4 repository, including group and user metadata as well as relationship information (i.e., users’ group and groups’ group membership). ADSIConnector reads both local and domain user/group data. Data will be read from NT and organized and provided in the containers expected by the MI engine.

1.2.2. Add User/Group Data

ADSIConnector adds user information to both local machines and domain controllers.
ADSIConnector adds group information to both local machines and domain controllers. When operating with a domain controller, the connector can create both local and global groups. When operating with a machine that is not a domain controller, the connector can only create local groups, according to security restrictions set by NT itself.

1.2.3. Modify Group Membership

ADSIConnector modifies group membership for both local and global groups. In line with NT security restrictions, members can be assigned to groups as follows:
o A global group can only have users from its domain as members.
o A local group can have global groups and users from its domain or any trusted domain as members. A local group, however, cannot contain other local groups.
o Users on a local machine can exist without being members of a group.
o Each user on a domain controller must belong to a “Primary Group”. The Primary Group for a user can be any global group in the domain. While the user’s Primary Group can be changed, he is always a member of his Primary Group.

1.2.4. Modify User/Group Data

ADSIConnector modifies user and group properties on both local machines and domain controllers. When connected to a domain controller, the connector is able to modify the properties of both local and global groups. Modifying user membership in groups is addressed in the previous section (1.2.3).

1.2.5. Delete User/Group Data

ADSIConnector can remove users from both local machines and domain controllers.
ADSIConnector can remove local groups from both local machines and domain controllers. When operating with a domain controller, the connector can remove both local and global groups.

2.Business Objects

2.1. Connector
Name: ADSIConnector
Description: NT connector for Metamerge Integrator
Role: The connector provides bi-directional interaction with the internal NT user database

States: Applicable connector states are fully consistent with MetaMerge-defined states. There is no custom behavior.
Operations: Applicable connector operations are fully consistent with MetaMerge-defined connectors. There is no custom behavior.

Parameters:

Name Type Size Range Required Comments
ComputerName String 15 not NULL Yes The name of the NT machine which database will be accessed. One connector’s action can be applied to exactly one NT machine – the one specified by this parameter.
UserName String not limited can be
NULL
No User name for remote logon in another domain. If NULL or blank no logon is performed.
Password String not limited can be
NULL
No Password of the user account for remote logon in another domain. This value, if entered, will be sent as clear text.
EntryType Lookup - User, Group Yes Specifies whether users or groups will be presented by the connector’s entries.

2.2. Entry
Name: ADSIConnector’s entry
Description: The entry object with which ADSIConnector operates
Role: This is the atomic data structure used by the connector to represent and transfer data

States: The possible states of the entry objects are determined by the EntryType parameter of the connector. There are 2 possible states: User state and Group state. This parameter is set prior to the execution of the connector operation and is constant throughout the operation.
Operations: Applicable connector operations are fully consistent with MetaMerge-defined connectors. There is no custom behavior.

Entry’s User State Attributes:

Name Type Size Range Comments
UserName String 256 not NULL Specifies the name of the user account.
AccountComment String not limited can be NULL Contains a comment to associate with the user account.
FullName String not limited can be NULL Contains the full name of the user.
UserComment String not limited can be NULL Contains a user comment.
Password String 14 0 - 14 Specifies the password for the user identified by the Account name attribute. Password is not encrypted.
PasswordAge Long double word >= 0 Specifies an integer value that indicates the number of days that have elapsed since the user’s password was last changed. This value is determined by the NT System and cannot be modified
PrivilegeLevel Integer double word 0,1,2 Specifies an integer value that indicates the level of privilege assigned to user. Indicates one of the following levels: guest (value 0), user (value 1), administrator (value 2). This value is determined by the NT System and cannot be modified.
HomeDirectory String not limited can be NULL Specifies the path of the home directory of the user.
Flags Integer double word not specified Specifies an integer value that determines several features. Full and detailed description of all possible values and their meanings can be found in the MSDN: USER_INFO_3 structure.
ScriptPath String not limited can be NULL Specifies the path for the user's logon script file.
AuthFlags Integer double word not specified Specifies an integer value that contains a set of bit flags defining the user's operator privileges. This value is determined by the NT System and cannot be modified.
ApplicationsParams String not limited can be NULL Specifies string that is reserved for use by applications. This value is used by Mircosoft products and the connector will not allow its modification.
LogonWorkstations String not limited can be NULL Contains the names of workstations from which the user can log on.
LastLogon Date - not specified Specifies when the last logon occurred. This value is determined by the NT System and cannot be modified.
LastLogoff Date - not specified Specifies when the last logoff occurred. This value is determined by the NT System and cannot be modified.
AccountExpDate Date - not specified Specifies when the account expires.
MaxAccDiskSpace Long double word not specified Specifies an integer value that indicates the maximum amount of disk space the user can use.
UnitsPerWeek Integer double word not specified Specifies an integer value that indicates the number of equal-length time units into which the week is divided. This value is determined by the NT System and cannot be modified. For more information look in the MSDN: USER_INFO_3 structure.
LogonHours byte array 21 not specified Specifies the times during which the user can log on. Detailed specification of this data structure can be found in the MSDN: USER_INFO_3 structure.
BadPasswordCnt Integer double word not specified Specifies an integer value that indicates the number of times the user tried to log on to the account using an incorrect password. A value of –1 indicates that the value is unknown.This value is determined by the NT System and cannot be modified.
LogonsNum Integer double word not specified Specifies an integer value that indicates the number of times the user logged on successfully to this account. A value of – 1 indicates that the value is unknown. This value is determined by the NT System and cannot be modified.
LogonServer String not limited can be NULL Contains the name of the server to which logon requests are sent. This value is determined by the NT System and cannot be modified.
CountryCode Integer double word not specified Specifies an integer value that contains the country/region code for the user's language of choice.
CodePage Integer double word not specified Specifies an integer value that contains the code page for the user's language of choice.
RelativeUserID Integer double word not specified Specifies an integer value that contains the relative ID (RID) of the user. This value is determined by the NT System and cannot be modified.
PrimaryGroupID Integer double word not specified Specifies an integer value that contains the RID of the Primary Global Group for the user.
ProfilePath String not limited can be NULL Specifies a path to the user's profile.
HomeDirectoryDrive String not limited can be NULL Specifies the drive letter assigned to the user's home directory for logon purposes.
PasswordExpired Integer double word not specified Specifies an integer value that contains password expiration information. For more information look at the MSDN: USER_INFO_3 structure.
LocalGroups Vector not limited String elements Contains the names of the local groups that the user is member of.
GlobalGroups Vector not limited String elements Contains the names of the global groups that the user is member of.
PrimaryGroup String> 256 can be NULL Contains the account name of the Primary Group of the user. Applies only to domain users. The NT4UserMetaDataConnector operates with domain users only when its parameter ComputerName specifies primary domain controller. The Primary Group should be a global group.

Entry’s Group State Attributes:

Name Type Size Range Comments
GroupName String 256 not NULL Specifies the account name of the group.
Comment String 256 can be NULL Specifies a remark associated with the group.
IsGlobal Boolean 1 false, true Indicates whether the group is global.
Users Vector not limited String elements Contains the account names of the users that are members of this group.
Groups Vector not limited String elements Contains the account names of the groups that are members of this group.

3. Use Cases

The purpose of this section is to:
o Define what data can be obtained from NT database
o Define the impact of the connector’s actions to the NT database.

These use cases are defined according to the control points leaved to ADSIConnector through the inheritance of the base rscConnector class.

3.1. Obtain User’s Data from NT database
Preconditions: ADSIConnector’s parameter EntryType is set to User.
Start action: This use case begins when the assembly line forces the ADSIConnector to get data from its source (NT database).
The action can happen in 2 states of the connector:
o Iterating through all users.
o Searching a particular user by its name.
Actions: ADSIConnector reads from the specified NT machine user data and populates all available user entry’s attributes except the attribute Password. The attribute Password is set to NULL.
Exit states: The ADSIConnector creates and provides a user entry with the structure specified in section 2.2.
Exceptions: o The MI process does not have access to the requested information.
o The computer name (ADSIConnector ComputerName parameter) is invalid.
o The username/password provided to access the machine are incorrect.
o The user name could not be found in NT database (if a search of a particular user is performed)
3.2. Obtain Group’s Data from NT database
Preconditions: ADSIConnector’s parameter EntryType is set to Group.
Start action: This use case begins when the assembly line forces the ADSIConnector to get data from its source (NT database).
The action can happen in 2 states of the connector:
o Iterating through all groups.
o Searching a particular group by its name
Actions: ADSIConnector reads from the specified NT machine group data and populates all group entry’s attributes.
Exit states: The ADSIConnector creates and provides a group entry with the structure specified in section 2.2.
Exceptions: o The MI process does not have access to the requested information.
o The computer name (ADSIConnector ComputerName parameter) is invalid.
o The group name could not be found in NT database (if a search of a particular group is performed).
3.3. Add User in NT database
Preconditions: ADSIConnector’s parameter EntryType is set to User.
Start action: This use case begins when the assembly line forces the ADSIConnector to add a user into the NT database.
Actions: 1. A new user account is created in the NT database. Values are (can be) set for all user entry’s attributes except the following (they accept system default values):
o PasswordAge
o PrivilegeLevel
o AuthFlags
o ApplicationsParams
o LastLogon
o LastLogoff
o UnitsPerWeek
o BadPasswordCnt
o LogonsNum
o LogonServer
o RelativeUserID

2. The user is added as member to all local groups specified in the LocalGroups attribute. It is assumed that all local group accounts specified in the LocalGroups attribute exist in the local NT database. If the attribute LocalGroups is set to NULL then no local membership is set for the newly created user.

3. The user is added as member to all global groups specified in the GlobalGroups attribute. It is assumed that all global group accounts specified in the GlobalGroups attribute exist in the domain NT database. If the attribute GlobalGroups is set to NULL then no global membership is set for the newly created user.

4. If the user specified is domain user its Primary Group is set to the group specified by the PrimaryGroup attribute. If the PrimaryGroup attribute is NULL then the PrimaryGroup attribute is set to the NT default Primary Group.
Exit states: A new user account is created in the NT database with the attribute values provided and user’s membership is set as specified in the user entry’s Groups attribute.
Exceptions: o The MI process does not have access to the requested information.
o The computer name (ADSIConnector ComputerName parameter) is invalid.
o The specified user account already exists in the NT database. A user account is uniquely identified by the value of the UserName attribute.
o The operation is allowed only on the primary domain controller while the connector’s ComputerName parameter specifies other machine.
o The PrimaryGroup attribute value does not specify a valid group account for a domain user’s Primary Group.
o Some of the group accounts specified in the LocalGroups and GlobalGroups attributes do not exist.
3.4. Add Group in NT database
Preconditions: ADSIConnector’s parameter EntryType is set to Group.
Start action: This use case begins when the assembly line forces the ADSIConnector to add a group into NT database.
Actions: 1. A new group account is created in the NT database. Values are (can be) set to all group entry’s attributes. Local groups can be created for all NT machines. Global groups can be created only for primary domain controllers.

2. The users specified in the Users attribute are added as members of the group. It is assumed that all user accounts specified in the Users attribute exist in the NT database. If the attribute Users is set to NULL then no users are added as members of the newly created group.

3. The groups specified in the Groups attribute are added as members of the group. It is assumed that all group accounts specified in the Groups attribute exist in the NT database. Only the following group-in-group membership type is allowed: global group is a member of local group. If the attribute Groups is set to NULL then no groups are added as members of the newly created group.
Exit states: A new group account is created in the NT database with the attribute values provided. Users and groups membership is set as specified in the user entry’s Users and Groups attributes.
Exceptions: o The MI process does not have access to the requested information.
o The computer name (ADSIConnector ComputerName parameter) is invalid.
o The group already exists. A group account is uniquely identified by the value of the GroupName attribute.
o The operation is allowed only on the primary domain controller of the domain (for example when trying to add global group on non primary domain controller machine).
o The operation is not allowed on certain groups. These groups include user groups, admin groups, local groups, and guest groups. These are groups created, managed and used by NT – for more information consult the MSDN.
3.5. Delete User from NT database
Preconditions: ADSIConnector’s parameter EntryType is set to User.
Start action: This use case begins when the assembly line requests that the ADSIConnector delete a user account from NT database.
Actions: The specified user account is removed from NT database. This will additionally remove all group memberships for the identified user(s).
Exit states: The specified user account is removed from the NT database.
Exceptions: o The MI process does not have access to the requested information.
o The computer name (ADSIConnector ComputerName parameter) is invalid.
o The operation is allowed only on the primary domain controller.
o The user name could not be found.
3.6. Delete Group from NT database
Preconditions: ADSIConnector’s parameter EntryType is set to Group.
Start action: This use case begins when the assembly line requests that the ADSIConnector delete a group account from NT database. Global groups can only be removed from the primary domain controller machine.
Actions: The specified group account is removed from the NT database. This will additionally remove all group membership relationships.
Exit states: The specified group account is removed from NT database.
Exceptions: o The MI process does not have access to the requested information.
o The computer name (ADSIConnector ComputerName parameter) is invalid.
o The operation is allowed only on the primary domain controller.
o The specified group does not exist.
o The operation is not allowed on certain NT’s special groups. These groups include user groups, admin groups, local groups, and guest groups. These are groups created, managed and used by NT – for more information consult the MSDN.
3.7. Modify User Data in NT database
Preconditions: ADSIConnector’s parameter EntryType is set to User.
Start action: This use case begins when the assembly line requests that the ADSIConnector modify user account information.
Actions: 1. The specified user account properties are modified. Values are (can be) set for all user entry’s attributes except the following attributes:
o PasswordAge
o PrivilegeLevel
o AuthFlags
o ApplicationsParams
o LastLogon
o LastLogoff
o UnitsPerWeek
o BadPasswordCnt
o LogonsNum
o LogonServer
o RelativeUserID

2. User’s membership in all groups is canceled (i.e. the user is removed from the members list of all local and global groups it was member of).

3.The user is added as member to all local groups specified in the LocalGroups attribute. It is assumed that all group accounts specified in the LocalGroups attribute exist in the local NT database. If the attribute LocalGroups is set to NULL then no local membership is set for the user.

4.The user is added as member to all global groups specified in the GlobalGroups attribute. It is assumed that all group accounts specified in the GlobalGroups attribute exist in the domain NT database. If the attribute GlobalGroups is set to NULL then no global membership is set for the user.

5.If the user specified is a domain user its Primary Group is set to the group specified by the PrimaryGroup attribute. If the PrimaryGroup attribute is NULL then the PrimaryGroup attribute is set to the NT default Primary Group.
Exit states: The user account properties are modified as set in the user entry’s structure and user’s membership is reset to the groups specified in the Groups attribute.
Exceptions: o The MI process does not have access to the requested information.
o The computer name (ADSIConnector ComputerName parameter) is invalid.
o The user name could not be found.
o The operation is allowed only on the primary domain controller.
o The operation is not allowed on certain NT’s special groups. These groups include user groups, admin groups, local groups, and guest groups. These are groups created, managed and used by NT – for more information consult the MSDN.
o Some of the attributes were set invalid (not allowed from NT) values.
o Invalid value set to the Password attribute.
o The PrimaryGroup attribute value does not specify a valid group account for a domain user’s Primary Group.
o Some of the group accounts specified in the LocalGroups and GlobalGroups attributes do not exist.
3.8. Modify Group Data in NT database
Preconditions: ADSIConnector’s parameter EntryType is set to Group.
Start action: This use case begins when the assembly line requests that the ADSIConnector modify a group account properties.
Actions: 1. The specified group account properties are modified. Values are (can be) set to all group entry’s attributes. Local groups can be modified on all NT machines. Global groups can only be modified on the primary domain controller machine.

2. All group’s members (users and groups) are removed from the group’s members list (i.e. all user and group memberships with this group are canceled).

3.The users specified in the Users attribute are added as members of the group. It is assumed that all user accounts specified in the Users attribute exist in the NT database.

4.The groups specified in the Groups attribute are added as members of the group. It is assumed that all group accounts specified in the Groups attribute exist in the NT database. Only the following group-in-group membership type is allowed: global group is a member of local group.
Exit states: The group account properties are modified as set in the group entry’s structure and group’s members are reset to the users and groups specified respectively in the Users and Groups attributes.
Exceptions: o The MI process does not have access to the requested information.
o The computer name (ADSIConnector ComputerName parameter) is invalid.
o The group name could not be found.
o Some of the attributes were set invalid (not allowed from NT) values.
o The operation is allowed only on the primary domain controller.
o The operation is not allowed on certain NT’s special groups. These groups include user groups, admin groups, local groups, and guest groups. These are groups created, managed and used by NT – for more information consult the MSDN.

4. Hardware and Software Configuration

4.1. Software Requirements
4.1.1 Architecture

ADSIConnector is implemented in Java and plugged into the java class hierarchy of the Metamerge Integrator.

ADSIConnector consists of the following layers:
1. Native C++ code wraps WinAPI functions that operate with NT security database. This native code is compiled into a DLL.
2. JNI is used to call the functions from the DLL. A java class wraps all JNI calls and provides interfaces to access all the functions provided by the DLL.
3. The java implementation of the ADSIConnector uses the interfaces provided by the JNI wrapper class and implements the control points (provided by the base rscConnector class) for defining functionality of the connector in the following modes: Iterator, Lookup, AddOnly, Update, Delete, Passive.

Error Handling

Errors that occurred during the execution of WinAPI functions will be transformed to exceptions in the native C++ code. These exceptions are then transformed to java exceptions and thrown through JNI in the java layer of the connector. From the java layer of the connector they are handled by the MI exception handling mechanism.

Hardware Requirements

ADSIConnector requires the standard hardware configuration for Metamerge Integrator.

The specific data it operates with, however, puts additional requirements. Metamerge Integrator that involves ADSIConnector in its assembly lines should:
o run on a NT machine – server or workstation
o run in a process owned by a user which is member of the local Administrators group and have login privileges to the domain controller for some operations.
o run in a network environment with access to the domain controller, other local machines, or other domains the connector is configured to operate with.



Questions or problems regarding this web site should be directed to webmaster@metamerge.com.
Copyright © 1999-2001 Metamerge AS. All rights reserved.
Last modified: 2001-06-08.
*
  Metamerge Integrator version 4.5 ©Copyright Metamerge AS 2000-2002 Last edited 2002-04-30 contact us