| |
NT4 Connector Functional Specifications and
Software Requirements
1. Overall Description
1.1. Overview
The NT4Connector 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 NT4Connector provides the following connector
modes: Iterator,Lookup, AddOnly, Update, Delete, Passive.
1.2.1. Extract User/Group Data
NT4Connector 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). NT4Connector 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
NT4Connector adds user information to both local
machines and domain controllers. NT4Connector
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
NT4Connector 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
NT4Connector 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
NT4Connector can remove users from both local
machines and domain controllers. NT4Connector 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: |
NT4Connector |
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: |
NT4Connector’s entry |
Description: |
The entry object with which NT4Connector 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 NT4Connector through the inheritance of the base
rscConnector class.
3.1. Obtain User’s Data from NT database
Preconditions: |
NT4Connector’s parameter EntryType is set to User. |
Start action: |
This use case begins
when the assembly line forces the NT4Connector 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: |
NT4Connector 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 NT4Connector 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 (NT4Connector 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: |
NT4Connector’s parameter EntryType is set to Group. |
Start action: |
This use case begins when the assembly line
forces the NT4Connector 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: |
NT4Connector reads from the specified NT
machine group data and populates all group entry’s attributes. |
Exit states: |
The NT4Connector 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 (NT4Connector 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: |
NT4Connector’s parameter EntryType is set to User. |
Start action: |
This use case begins when the assembly line
forces the NT4Connector 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.
If the following Attributes are not
set values (or NULL values are set), they get default values with
the following meaning: o Flags: "don't expire password", "normal
account", "script" ( "script" is required value for Windows
NT/2000) o AccountExpDate: "account never exipres" o
LogonHours: "no time restriction" (the user may logon always)
3. 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.
4. 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.
5. 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 (NT4Connector 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: |
NT4Connector’s parameter EntryType is set to Group. |
Start action: |
This use case begins when the assembly line
forces the NT4Connector 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 (NT4Connector 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: |
NT4Connector’s parameter EntryType is set to User. |
Start action: |
This use case begins when the assembly line
requests that the NT4Connector 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 (NT4Connector 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: |
NT4Connector’s parameter EntryType is set to Group. |
Start action: |
This use case begins when the assembly line
requests that the NT4Connector 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 (NT4Connector 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: |
NT4Connector’s parameter EntryType is set to User. |
Start action: |
This use case begins when the assembly line
requests that the NT4Connector 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 (NT4Connector 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: |
NT4Connector’s parameter EntryType is set to Group. |
Start action: |
This use case begins when the assembly line
requests that the NT4Connector 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 (NT4Connector 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
NT4Connector is implemented in Java and plugged into the java class hierarchy of the Metamerge
Integrator.
NT4Connector 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 NT4Connector 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
NT4Connector requires the standard hardware configuration for Metamerge Integrator.
The specific data it operates with, however, puts additional requirements. Metamerge
Integrator that involves NT4Connector 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.
|
| |
|