Writing LDAP Directory Object Attributes

Directory objects consist of a set of attributes: These are the actual data contents, which are - attached to the regarding object - stored in the directory database. Not all of the possible attributes have to be filled with real data. On the other hand many of the object attributes can consist of several values in an array.

We have several different techniques to read the directory attributes. The necessary basics are outlined in the next paragraphs:

Attribute Names

If you want to access the properties of LDAP objects, you have to know the names of the regarding attributes. The complete set of attributes which can be stored in an object is specified in the directory server's schema.

The names of the attributes can be very different - depending on the directory service. Even the exact number of possible attributes can vary a lot in each case. The only general approach that helps here is a detailed look into the documentation or the usage of a powerful LDAP browser, which can evaluate and display all the attribute names for a single object based on the schema information (an LDAP browser which would be capable of that would be for example LEX - The LDAP Explorer).

I tried to document the attributes for several important object classes of Active Directory and Exchange 5.5. Hereby i concentrated on attributes which are dealt with in the graphical admin tools:

If you don't know the attribute names of an object, you could also read the schema information from the regarding directory server, identify the concerning entries for the object class and extract there all the attribute names which are assigned to this class.

However, there is also a possibility to evaluate the set of attributes of an object in a script and without accessing the schema. But this method shows only the attributes of an actual object which have values and which are not 'Operational Attributes'. Find out more about this in the SelfADSI topic 'Read all Attributes of an Objects'.

Using SetInfo to write the Changes to the Directory

We will discuss several different methods to write an attribute value for an directory object. Whatever approach you choose, you always have to commit your changes to the regarding LDAP directory. Otherwise you just change your local object attribute cache without any effect to the directory server itself:

Download Script

Writing Attributes as an ADSI object property

This is the easiest way to write an LDAP attribute. It is a precondition that you performed a valid LDAP Bind for the regarding object. Either you connected to the actual object or the LDAP Bind connection was made to a parent directory and the scripts loops through the containing objects.

Normal attributes can be accessed often directly like a object property, hereby the attribute name is specified with a period behind the object's name - it's as easy as that:

Download Script

This notation may tempt us to confuse the used attributes with the API properties. Because this properties can be accessed exclusively with the syntax notation 'object.property'. However, these API properties are definitely not attributes from the LDAP directory, but object properties which is provided by the ADSI interface (and contains often information that is somehow related to attribute values). Examples for these properties are ADSPath, Class, Parent and Name. You can read more information about ADSI properties in the topic 'API properties for objects' here in the SelfADSI tutorial.

Writing Attributes with Put

In some cases it is not possible to access an LDAP attribute simply as an object property with the syntax notation 'object.attributename'. An example: An attribute's name could contain a minus character, and therefore the script interpreter cannot decide in the term

           user.msRADIUS-FramedIpv6Prefix = "2001:1638:1899::/48"

whether you want to set a value for an attribute named 'msRADIUS-FramedIpv6Prefix' or to do a subtraction between the values 'user.msRADIUS' and 'FramedIpv6Prefix'.

Another difficulty which has to be dealt with in scripts: Maybe the name of the attribute is not a constant string, but another variable.

In these cases you should use the ADSI method Put:

Download Script

A bit more laborious.... but think about it: That way you are on the safe side, because this is the official method which is described in the ADSI interface specifications.

Changing Multivalued Attributes with PutEx

You should keep in mind that the attribute which you maybe just want to write could be a multivalue attribute. That means that an array of values is stored in one single LDAP attribute. There has to be an possibility to add some values to such an array, to delete some values (but not the entire array) or to replace some values in the array. The ADSI method Put is not suitable for writing arrays - we have to use another function for this: PutEx.

object.PutEx <operation identifier>, <attribute name>, <array of attributes>

In the third parameter, you should always pass an array to the function, even if you only want to call the function with one single value! In this case you simply build an array which consists only of one value.

Additionally, PutEx needs a parameter to specify the kind of operation which is to be performed on the regarding multi valued attribute:

Here are some examples for each write access operation for a multivalue attribute:

Download Script

You should be aware of the fact that if you made an error in specifying one single member in your array which you pass to the PutEx function, the call will fail completely:

Download Script

Special Data Types for Attributes

Attributes are stored in their directories in different data types. The actual data type specification is also called 'attribute syntax'. And when you read attributes from a directory object, it plays certainly an important role whether you have to deal with strings, integer, long integers, date and time values or even with raw hex values. Because if the handling of a string or an integer is easy and also the conversion between such types is easy on he one hand, you could struggling much more when you have to read (display, compare, and so on...) with attributes which represents date and time formats or raw octet strings.

If you connect to an directory object with an LDAP Bind operation and you read the attributes of this object with standard techniques, you will get no information about the data type of the value(s) you read. However, if you use the more complicated ADSI method GetPropertyItem and a special handling of the property cache, you can retrieve the data type from ADSI for all kind of attributes. And then you can handle this accordingly in a script when you read the attributes value with unknown data types. An example for this approach can be examined in the article 'Reading all Attributes of an Object' here in the SelfADSI tutorial.

Interesting articles in the SelfADSI tutorial regarding attribute data types:

	Object attributes of type Octet String: "Octet-String" is an LDAP syntax and one of the standardized data types for raw hexadecimal values. But the according data type Byte[] is not available under VBScript: You have difficulties to handle such attributes without script runtime errors which state that the datatype was wrong or unknown. In this article you learn how to avoid such runtime errors and how to read and handle attributes of type Octet-String.
	Object Attributea of type Provider Specific: I an LDAP server returns this data type, it means something like "datatype could not be evaluated by the script exactly...". It is very complicated to read such attributes and handle their values without runtime errors. The only way to find the correct handling is to look in the directory schema and to apply a special method which can convert the values of such attributes into a usable format.
	The directory schema: General information about attribut data types, attribute syntaxes, and their specification in the directory schema.