JustLDAP Methods

JustLDAP Methods

JustLDAP installs as 2 separate COM+ applications that can be used by code such as ASP to create the available object methods.

The screen shot below shows the 2 COM+ applications after JustLDAP has been installed.

The JustLDAP COM+ application components are JustLDAP.Admin & JustLDAP.Find

The list of methods for the JustLDAP.Admin component are shown below.

Set oLdap = CreateObject("JustLDAP.Admin") ' For VBScript etc.

Set oLdap = Server.CreateObject("JustLDAP.Admin") ' For ASP pages.

The justLDAP.Find component instantiates an object that enables easy and fast LDAP searches for user properties.

The Lookup and LookupUsing methods in the "Admin" component are identical to the "Find" component methods of the same name. NOTE: The "Find" component is included in JustLDAP only to provide code backward compatibility with earlier versions of JustLDAP. There is no need to create a "JustLDAP.Find" component for new projects.

The JustLDAPDomain COM+ application contains the component:

JustLDAPDomain.DomainAdmin component that enables easy administration of 'User' objects in a remote Active Directory domain. Search methods are also available in this component.

Set oLdap = CreateObject("JustLDAPDomain.DomainAdmin") ' For VBScript etc.

Set oLdap = Server.CreateObject("JustLDAPDomain.DomainAdmin") ' For ASP.

Method Details

Some of the methods below are used to set or get user properties that also appear in the Microsoft Active Directory Users and Computers mmc (Microsoft Management Console) snap-in. (Often referred to as the ADUC tool).

It is important to note that not all user properties appear in the graphical tool. For example the employeeID does not appear in the tool for the basic schema.

To relate the Active Directory properties to the GUI tool see the following article that describes this mapping in detail:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/ad/ad/user_object_user_interface_mapping.asp

Methods for the "justLDAPDomain.DomainAdmin" component are also shown below. They are identical to the local domain methods however most methods take the 3 extra required parameters: Domain, AuthUser, AuthPassword

Domain is the remote domain name in DNS format (mycompany.com) or IP address.
AuthUser is a User account on the remote AD Domain with enough rights to use the method called.
AuthPassword is the remote AuthUser password in plain text.

NOTE: For DomainAdmin methods, the username and password do not travel over the network in plain text. The security support provider used by JustLDAP protects the credentials.

The method names have the letters "Dom" appended to easily distinguish them from the local domain methods.

AddUserToGroup(Group, uid)

AddUserToGroupDom(Group, uid, Domain, AuthUser, AuthPassword)

Adds an existing user to a named group.

Group is a group name in the directory.
uid is the user login ID (sAMAccountName)

Returns a Variant - typically 0 (Integer) indicating success.

CanUserChangePassword(uid)

CanUserChangePasswordDom(uid, Domain, AuthUser, AuthPassword)

Tests if a user has the right to change their own password or not.

uid is the user login ID (sAMAccountName)

Returns Boolean (True or False). [True if the user can change their password.]

CreateUser(uid, Name, InitialPassword)

CreateUserDom(uid, Name, InitialPassword, Domain, AuthUser, AuthPassword)

Creates a normal user.

uid is the user login ID (sAMAccountName)
Name is typically the users full name.
InitialPassword is set as the password for the account.

Returns Variant - typically 0 (Integer) indicating success.

CreateUserEx(uid, UPN, Name, FirstName, LastName, InitialPassword)

CreateUserExDom(uid, UPN, Name, FirstName, LastName, InitialPassword, Domain, AuthUser, AuthPassword)

Creates a normal user with full name fields and UPN.

uid is the user login ID (sAMAccountName)
UPN is the users Universal Principal Name in the format: user@domain.com
Name is the users full name.
FirstName is typically the users given name.
LastName is typically the users surname.
InitialPassword is sets the password for the account.
(All the above are required parameters).

Returns Variant - typically 0 (Integer) indicating success.

DaysUntilPwExpire(uid)

DaysUntilPwExpireDom(uid, Domain, AuthUser, AuthPassword)

IMPORTANT NOTES:

If the account is set such that the user is required to change their password at next logon, this method will return an error.

Call the method "IsUserRequiredToChangePWAtNextLogon" before calling this method.

If the user account is set to never expire the password, then this test returns the current domain default password expiry period.

Therefore, you should call the method "DoesUserPasswordExpire" before calling this method.

Returns the number of days remaining until the users password expires.

uid is the user login ID (sAMAccountName)

Returns Variant (Integer) with the number of days remaining.

DeleteUser(uid)

DeleteUserDom(uid, Domain, AuthUser, AuthPassword)

Deletes a user account.

uid is the user login ID (sAMAccountName)

Returns Variant - typically 0 (Integer) indicating success.

DeleteUserFromGroup(Group, uid)

DeleteUserFromGroupDom(Group, uid, Domain, AuthUser, AuthPassword)

Deletes a user account from a group.

Group is the group name in the directory.
uid is the user login ID (sAMAccountName)

Returns Variant - typically 0 (Integer) indicating success.

DisableUserAccount(uid)

DisableUserAccountDom(uid, Domain, AuthUser, AuthPassword)

Disables a user account.

uid is the user login ID (sAMAccountName)

Returns Variant - typically 0 (Integer) indicating success.

DoesUserPwExpire(uid)

DoesUserPwExpireDom(uid, Domain, AuthUser, AuthPassword)

Tests if the users account is set to never expire the password.

uid is the user login ID (sAMAccountName)

Returns boolean (True or False). [True if the password never expires.]

EnableUserAccount(uid)

EnableUserAccountDom(uid, Domain, AuthUser, AuthPassword)

Enables a user account.

uid is the user login ID (sAMAccountName)

Returns Variant - typically 0 (Integer) indicating success.

ErrorOccurred()

Special method call to test if any error occurred
in the most recent JustLDAP method call.

Typically all ASP / VBScripts should call this method after all regular
JustLDAP method calls.

Must be called in the context of a normal JustLDAP method call code sequence
to determine if any error occurred in the method just used.

Returns Boolean (True or False).

GetAccountExpiryDate(uid)

GetAccountExpiryDateDom(uid, Domain, AuthUser, AuthPassword)

Returns the date that the users account will expire.

uid is the user login ID (sAMAccountName)

NOTE: If the account is set to never expire, a date in the past will
be returned. It is better to call the JustLDAP method IsAccountSetToExpire
before calling this function. See below.

Returns VB / VBScript 'Date' value.

GetDateUserPasswordLastChanged(uid)

GetDateUserPasswordLastChangedDom(uid, Domain, AuthUser, AuthPassword)

Returns the date that the users password was changed or the
password settings were altered.

uid is the user login ID (sAMAccountName)

Returns VB / VBScript 'Date' value.

GetDomainDnsName()

[Not available for justLDAPDomain.DomainAdmin]

Returns the Active Directory Domain DNS name of the Domain where JustLDAP is currently installed.

Returns the DNS Domain name in the form "mycompany.com" etc.
Can be useful for scripts that may need this information.

Returns Variant - String.

GetDomainNetBIOSName()

[Not available for justLDAPDomain.DomainAdmin]

Returns the Active Directory Domain NetBIOS name of the Domain where JustLDAP is currently installed.

Returns the NetBIOS Domain name in the form "MYCOMPANY" etc.
Can be useful for scripts that may need this information.

Returns Variant - String.

GetGroupType(Group)

GetGroupTypeDom(Group, Domain, AuthUser, AuthPassword)

Returns the type of group as an integer, either 1 (Security) or 2 (Distribution).

Group is the group name in the directory.

Returns Variant (Integer)
0 = Error
1 = Group is Security type
2 = Group is Distribution type.

GetInformationMessage()

Special method call to return an information message for the
most recent JustLDAP method called.

Must be called in the context of a normal JustLDAP method call code sequence.

Returns information that is useful if you are unsure of a result.
For example, the "IsUserMemberOfGroup" method returns True or False
which is sufficient for normal ASP or VBS flow control.

The additional information message in this example may contain either:
"User does not exist in this group." or
"User does exist in this group."
etc.

Returns a String

GetJustLDAPVersion()

Returns the JustLDAP version and build number as a single string.

Returns a String in the form "4.0\0409"
To the left of the "\" is the version. To the right of the "\" is the build number.

Version number increases indicate major updates to JustLDAP.
Build number increases indicate minor bug fixes or added / enhanced methods.

Returns a String

GetLastErrorAsMessage()

Special method call to return any error message for the
most recent JustLDAP method called.

Must be called in the context of a normal JustLDAP method call code sequence
to determine if any error occurred in the method just used.

This is a popular method for returning information in interactive sessions such as
an administrative Web based applications or for logging to a log or result file in administrative scripts.

Call this method if the "ErrorOccurred()" method returned True to obtain
descriptive error information.

Returns a String

GetUserArrayProperty(uid, PropertyToGet)

GetUserArrayPropertyDom(uid, PropertyToGet, Domain, AuthUser, AuthPassword)

Returns a Variant array of values for the property collection.

For example, the user may have several "otherTelephone" numbers. The Active
Directory "otherTelephone" property is actually a multi-valued array.
See the sample code which uses the VB "For Each / Next" construct to step through
the array returned.

uid is the user login ID (sAMAccountName)
PropertyToGet is a user property that is known to be an array of values in the
Microsoft Active Directory schema - or locally modified schema.

Returns Variant Array of strings.

GetUserProperty(uid, PropertyToGet)

GetUserPropertyDom(uid, PropertyToGet, Domain, AuthUser, AuthPassword)

Returns a Variant value for the property.

uid is the user login ID (sAMAccountName)
PropertyToGet is a user property such as "employeeID"

Returns Variant string.

IsAccountSetToExpire(uid)

IsAccountSetToExpireDom(uid, Domain, AuthUser, AuthPassword)

Tests if the user account is set to expire.

uid is the user login ID (sAMAccountName)

Returns Boolean (True or False).

IsDomainSetToExpirePasswords()

IsDomainSetToExpirePasswordsDom(Domain, AuthUser, AuthPassword)

Tests if the Active Directory Domain where JustLDAP is installed has a
Domain Policy setting that forces password expiry or not.

Returns boolean (True or False).

IsUserDisabled(uid)

IsUserDisabledDom(uid, Domain, AuthUser, AuthPassword)

Tests if the user account is disabled.

uid is the user login ID (sAMAccountName)

Returns boolean (True or False).

IsUserLockedOut(uid)

IsUserLockedOutDom(uid, Domain, AuthUser, AuthPassword)

Tests if the user account is locked out.

uid is the user login ID (sAMAccountName)

Returns boolean (True or False).

IsUserMemberOfGroup(Group, uid)

IsUserMemberOfGroupDom(Group, uid, Domain, AuthUser, AuthPassword)

Tests if a user account is a member of a named group.

Group is the Active Directory unique Group name
uid is the user login ID (sAMAccountName)

Returns boolean (True or False).

IsUserMemberOfGroupDN(GroupDN, uid)

IsUserMemberOfGroupDNDom(GroupDN, uid, Domain, AuthUser, AuthPassword)

Tests if a user account is a member of a group specified by the full Group Distinguished Name.

NOTE: This method is much faster than the "IsUserMemberOfGroup" as JustLDAP does not need to locate the group before testing membership of the user.

However you need to supply the Full DN of the group in the format:
"CN=Internal Sales,OU=Canada,OU=West,DC=yourcompany,DC=com"

GroupDN is the Active Directory full distinguished name of the group
uid is the user login ID (sAMAccountName)

Returns boolean (True or False).

IsUserRequiredToChangePWAtNextLogon(uid)

IsUserRequiredToChangePWAtNextLogonDom(uid, Domain, AuthUser, AuthPassword)

Tests if a user account has this setting enabled or not.

uid is the user login ID (sAMAccountName)

Returns boolean (True or False).

ListAllGroups()

ListAllGroupsDom(Domain, AuthUser, AuthPassword)

Lists all groups in the domain that JustLDAP is installed for.

Returns ADO Recordset of all groups in the domain in distinguished name format.

ListMembersOfGroup(Group)

ListMembersOfGroupDom(Group, Domain, AuthUser, AuthPassword)

Lists all members of a group.

Group is the group name in the directory.

Returns a simple string list of group members in distinguished name format.

ListUserGroupMembership(uid)

ListUserGroupMembershipDom(uid, Domain, AuthUser, AuthPassword)

Lists all groups that the user account belongs to.

uid is the user login ID (sAMAccountName)

Returns a simple string list of groups in the format:
CN=International Sales
CN=Administrators
etc.

Lookup(AttributeName, AttributeValue, Results)

LookupDom(AttributeName, AttributeValue, Results, Domain, AuthUser, AuthPassword)

High efficiency LDAP search for "User" attributes.

Separately documented below here.

LookupSort(AttributeName, AttributeValue, SortCommand, Results)

LookupSortDom(AttributeName, AttributeValue, SortCommand, Results, Domain, AuthUser, AuthPassword)

Identical to "Lookup" with the added extra parameter "SortCommand".

The returned recordset results are sorted in either Ascending or Descending order based on the following syntax.

For example. If you are returning "sn,telephoneNumber,givenName,mail"
and you wish to sort a number of users based on givenName, simply specify the SortCommand text string as "givenName ASC" (for ascending order A->Z).

Or "givenName DESC" for descending order.

LookupUsing(AttributeName, AttributeValue, Results, Domain, Username, Password)

[LookupDom replaces LookupUsing for justLDAPDomain.DomainAdmin]

High efficiency LDAP search for "User" attributes where the computer that JustLDAP is installed on is not a member of the domain.

Separately documented below here.

MoveUserTo(uid, TargetOU)

MoveUserToDom(uid, TargetOU, Domain, AuthUser, AuthPassword)

Moves the user from their current container to a new Organizational Unit (OU).

uid is the user login ID (sAMAccountName)
TargetOU is the fully specified distinguished name of the OU where the user will be moved to for example:

"ou=Sales,ou=Canada,dc=yourcompany,dc=com"

Returns Variant - typically 0 (Integer) indicating success.

SelfChangePassword(uid, OldPassword, NewPassword)

SelfChangePasswordDom(uid, OldPassword, NewPassword, Domain, AuthUser, AuthPassword)

Allows a user to change their own password.
This method can be used to allow a user to reset their own password from a Web interface, ASP ASP.NET or other application.

NOTE: The user must know their current password to use this function.

If the password has expired, the password expiry is reset to non-expired (normal) if the function succeeds.

If the user account is locked out or expired, an error is returned.

uid is the user login ID (sAMAccountName)
OldPassword is the users current password
NewPassword is the new password that will be set for the user

Returns Variant - typically 0 (Integer) indicating success.

SetAccountExpiryDate(uid, ExpiryDate)

SetAccountExpiryDateDom(uid, ExpiryDate, Domain, AuthUser, AuthPassword)

Sets a user account to expire on the 'ExpiryDate'.

NOTE: To set an account to "Never Expire", pass "0" as
the ExpireDate. (Integer).

Note: Any valid VB / VBScript date may be entered. Examples:

"February 19, 2006" or "05/23/2007" etc. (Use your Domain Date
format for the relevant culture / locale.)

uid is the user login ID (sAMAccountName)
Expire date - string e.g. "05/04/2006"

Returns Variant - typically 0 (Integer) indicating success.

SetUserAccountToNormal(uid)

SetUserAccountToNormalDom(uid, Domain, AuthUser, AuthPassword)

Sets a user account to normal.

Note: All account settings cleared except the password requirements.
The password settings for the account will behave as appropriate by taking into
consideration the current settings.

See the Active Directory documentation for further information.

Returns Variant - typically 0 (Integer) indicating success.

SetUserArrayProperty(uid, PropertyToSet, Value)

SetUserArrayPropertyDom(uid, PropertyToSet, Value, Domain, AuthUser, AuthPassword)

Sets (adds) a value to a multi-valued user property.

For example the "otherTelephone" field in a user account is an array of
phone numbers. Use this function to set an initial value for an array property,
or to add additional values to the property. i.e. More phone numbers in this case.

uid is the user login ID (sAMAccountName)
PropertyToSet is a multi-valued property.
Value is the actual value to add to this property.

Returns Variant - typically 0 (Integer) indicating success.

SetUserPassword(uid, Password)

SetUserPasswordDom(uid, Password, Domain, AuthUser, AuthPassword)

Sets a password for a user account.

Overwrites any existing password.

uid is the user login ID (sAMAccountName)
Password that will be assigned to this user account.

Returns Variant - typically 0 (Integer) indicating success.

SetUserProperty(uid, PropertyToSet, Value)

SetUserPropertyDom(uid, PropertyToSet, Value, Domain, AuthUser, AuthPassword)

Sets the value of a user property.

For example the users telephoneNumber

uid is the user login ID (sAMAccountName)
PropertyToSet is a user property.
Value is the actual value for this property.

Returns Variant - typically 0 (Integer) indicating success.

TestUserCredentials(uid, Password)

TestUserCredentialsDom(uid, Password, Domain)

NOTE: AuthUser and AuthCredentials are not required for this domain method.

Tests if the uid and password (typically supplied from a user input form) are valid for any user account.

NOTE: Several tests on the user LoginID should be performed before testing the LoginID and Password for validity.

That is, call the JustLDAP methods: "IsUserDisabled" & "IsUserLockedOut" first, as there is no point progressing to the TestUserCredentials method if the user is unable to authenticate for other reasons.

uid is the user login ID (sAMAccountName)
Password is the password that should be the current users actual password.

Returns Variant - 0 (Integer) indicating that the Username & password credential set were valid.

Simply test for returned value = 0 to determine if the credentials are valid.

Otherwise an error number is returned. Call the GetLastErrorAsMessage() function if more information is desired.

UnlockUserAccount(uid)

UnlockUserAccountDom(uid, Domain, AuthUser, AuthPassword)

Unlocks a user account.

uid is the user login ID (sAMAccountName)

Returns Variant - typically 0 (Integer) indicating success.

UserCannotChangePassword(uid, TrueOrFalse)

UserCannotChangePasswordDom(uid, TrueOrFalse, Domain, AuthUser, AuthPassword)

Denies or permits the user the right to change their own account password.

uid is the user login ID (sAMAccountName)
TrueOrFalse is either True or False

Returns Variant - typically 0 (Integer) indicating success.

UserMustChangePasswordAtNextLogon(uid, TrueOrFalse)

UserMustChangePasswordAtNextLogonDom(uid, TrueOrFalse, Domain, AuthUser, AuthPassword)

Sets or clears the user account flag for this option.

Note: If set to true, the flags "User cannot change password" and
"User password never expires" will be cleared.

uid is the user login ID (sAMAccountName)
TrueOrFalse is either True or False

Returns Variant - typically 0 (Integer) indicating success.

UserPasswordNeverExpires(uid, TrueOrFalse)

UserPasswordNeverExpiresDom(uid, TrueOrFalse, Domain, AuthUser, AuthPassword)

Sets the "user password never expires" setting to True or False

Note that if the the account option "User must change password at next logon" is set
Then that option will be automatically cleared if the password is set to never expire
i.e the 2nd parameter is 'True'

uid is the user login ID (sAMAccountName)
TrueOrFalse is a VBScript True or False value.

Returns Variant - typically 0 (Integer) indicating success.

JustLDAP Search Functions "Lookup and LookupUsing".

"Lookup" Parameters: AttributeName, AttributeValue and ReturnAttributes

The "Lookup" method, takes 3 parameters.

The first parameter is the user attribute name that you will be providing in the second parameter.

The second parameter is the specific (or "wild carded" [by using an asterisk '*']) item you are searching for.

The last parameter is a simple comma separated string list of the attributes you require to be returned from the search.

All parameters passed as strings must be enclosed in double quotes. (Of course, if you are using VBScript variables already containing the string text, do not include the quotes.)

Important Note: The first and last parameters must use the Microsoft Active Directory attribute names. These names are case sensitive! For example, looking for Telephonenumber will return an error.
The correct case and spelling is telephoneNumber.

For a list of attribute spelling and case see this file.

Example search requests showing parameter values for the "Lookup" method call
Search required	AttributeName	AttributeValue	ReturnAttributes
Find "bobuser" and return his Employee ID, Surname, Given Name, Phone Number and Email address.	"sAMAccountName"	"bobuser"	"employeeID, sn, givenName, telephoneNumber, mail"
Find employee with Employee ID 2312442 and return their login ID, department and ADsPath.	"employeeID"	"2312442"	"sAMAccountName, department, ADsPath"

Partial example in VBScript:

Set objLdap = CreateObject("JustLDAP.Admin")

Set objRS = objLdap.Lookup("sAMAccountName", "bobuser", "employeeID, sn, givenName, telephoneNumber, mail")

This will return a RecordSet in objRS for "bobuser" containing his employee ID, Surname, Given Name, Phone number and email address.

"LookupUsing" Parameters: AttributeName, AttributeValue, ReturnAttributes, Domain, Username, Password

Use this method when the computer is either not authenticated to the Active Directory domain, or you are querying a different Microsoft Active Directory domain. For this method, you must provide authenticating credentials that are valid for the domain being queried and the DNS domain name must be supplied in the fourth parameter.

NOTE: The Domain must be the DNS Domain name e.g. "mycompany.com".

This fourth parameter (Domain) can also specify an actual specific Domain Controller if you wish. E.g. dc0005.toplevel.mycompany.com or even a server IP address.

Example search requests with parameter values for the "LookupUsing" method call
Search required	AttributeName	AttributeValue	ReturnAttributes	Domain	Username	Password
Find "bobuser" and return his Employee ID, Surname, Given Name, Phone Number and Email address.	"sAMAccountName"	"bobuser"	"employeeID, sn, givenName, telephoneNumber, mail"	"mycorp.com"	"robot36"	"secretpw"
Find employee with Employee ID 2312442 and return their login ID, department and ADsPath.	"employeeID"	"2312442"	"sAMAccountName, department, ADsPath"	"mycorp.com"	"robot36"	"secretpw"

Partial example in VBScript:

Set objLdap = CreateObject("JustLDAP.Admin")

Set objRS = objLdap.LookupUsing("sAMAccountName", "bobuser", "employeeID, sn, givenName, telephoneNumber, mail", "mycorp.com", "robot36", "secretpw")

This will return a RecordSet in objRS for "bobuser" containing his employee ID, Surname, Given Name, Phone number and email address.

NOTE: By using the above method, the Active Directory domain is specified. This means the the Server or Workstation querying the domain does not need be an actual member of the domain. However, valid domain credentials (Username and Password) must be provided to allow JustLDAP to authenticate to the Active Directory Domain Controllers so that LDAP searching will be permitted. For LDAP searches, ordinary user credentials typically give sufficient privileges to read (search) using LDAP.

NOTE: The "domain" in the context of the LookupUsing method call refers to the DNS domain name for your Active Directory domain.

Only "indexed" user attributes should be specified as a search attribute. Indexed attributes can be found in a fraction of the time that non-indexed attributes take when searching Active Directory. Indexed attributes can be determined from the Active Directory Schema. A simple VBS script may be used to determine which user attributes are indexed in your Active Directory domain.

For example, these two standard (Microsoft default) attributes usually are indexed: sAMAccountName (the username) and employeeID. A example of a non-indexed attribute is the telephoneNumber. Searching may still be performed on non-indexed attributes, however the search time is greatly increased.

For example, searching for a user by specifying their phone number would not be a good Web based application of JustLDAP. However, for a desktop client application, this could be an useful feature (to find someone based on the phone number only).

Many different combinations of these parameters can be used.

The following examples demonstrate the wide range of user searching you can perform. (Assuming that Active Directory has been implemented.)

1. Find all Phone Numbers for employees whose Surnames begin with "Sa". Return the Surname and the Phone Number.

Set objRS = objLdap.Lookup("sn", "Sa*", "sn, telephoneNumber")

2. Find several details (15) for a single employee that just hit the company Intranet home page. (Assume the userID has been derived from the IIS Web server "LOGON_USER")

        attrs = "sAMAccountName, sn, givenName, physicalDeliveryOfficeName, title, &_
                   department, company, employeeID, wWWHomePage, Manager, &_
                   telephoneNumber, facsimileTelephoneNumber, mail, displayName, ADsPath"

        Set objRS = objLdap.Lookup("sAMAccountName", userID, attrs)

3. Find all user objects in the Active Directory and return the email address and the Surname.

Set objRS = objLdap.Lookup("sAMAccountName", "*", "mail, sn")

As you can see, there are many combinations of searching available. Also, JustLDAP is written to correctly query Active Directory to return several thousand "recordset rows" with its single method call. It is not restricted by the typical 1000 item administrative limit for single queries.

By using JustLDAP, large data sets can be returned but may take several minutes, or much longer. Care must be taken not to query unnecessarily. An entire "dump" of all users in Active Directory for a large company should be scheduled to run at a quiet time (e.g. 2 AM) using Task Scheduler and a VBScript file.