3.1.1 Abstract Data Model

In the DC configuration, this protocol operates over a directory database that is composed of a set of named objects. The name format is an X.501 name [X501]; therefore, the objects are arranged in a hierarchy by name. Each object's name MUST be unique within the directory. In a non-DC configuration, the name format of X.501 is not normative; this specification assumes that the format is X.501 for consistency between the two configurations. This protocol is based largely on the use of RPC context handles to maintain session state between the client and server. The basic context-handle programming model is described in [C706] section 6.1.6. In the Security Account Manager (SAM) Remote Protocol (Client-to-Server), for the context handles that have been returned to clients, the server MUST maintain information that maps those handles to the internal objects they represent.

Each object possesses a collection of attributes. Attributes can be multivalued. Each attribute is identified by a value called ldapDisplayName. For example, the X.501 name of the object is a single-valued attribute with the ldapDisplayName: distinguishedName. This specification describes the constraints on the attributes for behaviors relevant to this protocol. For the DC configuration, [MS-ADTS] section contains additional constraints.

Objects are retrieved from the directory database by specifying attribute-value constraints that the object's attributes (and their values) MUST satisfy. Attribute values are updated by identifying the target object by distinguishedName and specifying the new set of attribute-value pairs. Section and section contain a list of the Active Directory attributes and classes relevant to this protocol.

Implementations MUST support creating, reading, updating, and deleting multiple objects, attributes, and attribute values with ACID (atomic, consistent, isolated, and durable) properties [GRAY]. Such an update is referred to as a transaction in this specification.

A user object refers to a database object whose objectClass attribute is user or derived from user.

A computer object refers to a database object whose objectClass attribute is computer or derived from computer.

A group object refers to a database object whose objectClass attribute is group or derived from group, and whose groupType contains GROUP_TYPE_ACCOUNT_GROUP or GROUP_TYPE_UNIVERSAL_GROUP.

An alias object refers to a database object whose objectClass attribute is group or derived from group, and whose groupType contains GROUP_TYPE_RESOURCE_GROUP.

Two domains are exposed from a given server: an account domain and a built-in domain; this fact is true for both DC and non-DC configurations. The account domain refers to the object with objectClass domainDNS. The built-in domain refers to the object with the objectClass builtinDomain. The built-in domain has the characteristic that its objectSid value is invariant (S-1-5-32) through all deployments and only contains aliases. There is exactly one built-in domain for every account domain. When opening a domain object (through SamrOpenDomain (section a client selects the domain to open based on the DomainId parameter. A domain can be in either mixed mode or native mode, as specified in [MS-ADTS] section

Domain object refers to either the account domain or the built-in domain.

Server object refers to the single object in the account domain with the samServer objectClass.

The following sections normatively describe the database constraints and triggers required for the message processing of this protocol.

  • Constraints are relationships between attributes that MUST be satisfied for a database update to be successful. The constraints are specified in section

  • Triggers are actions that MUST be executed for a database update to be successful. An attribute-scoped trigger is a trigger that is executed when a particular attribute is updated. The attribute-scoped triggers are specified in section

The methods that make up this RPC interface MUST all return STATUS_SUCCESS (0x00000000) on success. Error statuses (also called error codes) generated by a failure to comply with a constraint are in the NTSTATUS space (a long data type), as specified in [MS-ERREF] section 2.3. Unless specifically called out, error codes are returned to the client of the protocol and are not handled by any special processing at the client; therefore, the exact error code is implementation-specific. Cases in which the client might handle a specific error code are called out. The set of such error codes is found in section