Creating Active Directory Users and Groups

In part 1, I showed how to use the Win32::OLE module to access objects in Active directory. We connected to a user, read an attribute, wrote to an attribute, and called a method. Now, let's create a new object.

Not suprisingly, we'll use the Create method. The Create method is a method of a container object (we're creating an object in a container so we call container->Create). So first, we have to connect to the container. As in part one, this is easy, as long as you know the distinguished name of the container. For example, let's say you have an OU called HR, and you want to create a new user in the HR OU. So, we need to connect to the HR OU.

use Win32::OLE;

$ou=Win32::OLE->GetObject("LDAP://ou=HR,dc=myDomain,dc=net");

Next we call the Create method. The Create method can create any class of object (user, group, etc), so we need to tell it what class of object to create, and give it a cn (commmon name). It's distinguished name will be the cn plus the dn of the container. So, let's create a user called Harry. Each object class has a set of mandatory attributes (and optional attributes). We have to fill out the mandatory attributes before we try to save the new user, otherwise we'll get an error. After calling the Create method, there's only one mandatory attribute missing for our new user: SAMAccountName. This attribute is the the user's logon ID (what they type in the user name field when they logon). Then Finally, we save the user with SetInfo().

use Win32::OLE;

$ou=Win32::OLE->GetObject("LDAP://ou=HR,dc=myDomain,dc=net");
$user=$ou->Create("User","cn=Harry");
$user->put("samAccountName","harry");
$user->SetInfo();

OK, that worked, but wait! Our new user not only doesn't have a password yet, but it's also disabled. So let's take care of those. Things like passwords and account flags are optional attributes, so we can't add them before the user is created. So, we have to add them after the SetInfo(), then call SetInfo() a second time...

use Win32::OLE;

$ou=Win32::OLE->GetObject("LDAP://ou=HR,dc=myDomain,dc=net");
$user=$ou->Create("User","cn=Harry");
$user->put("samAccountName","harry");
$user->SetInfo();
$user->{AccountDisabled}=0;
$user->SetPassword("swordfish");
$user->SetInfo();

Of course you can add additional attributes before you call the last SetInfo(), but we've already done enough to create a working user account that can logon.

Next let's have a look at groups. Let's create a group. A group has similar requirements as a user when creating it. You need to provide the object class, a common name, and a SAMAccountName. However, you also need to specify what type of group you're creating. There are several types of groups.

First, a group can be a distribution list or a security group. Both types of groups may be used to send email to the members of the group, but distribution lists may not be used in an access control list (ACL) because no security identifier (SID) is associated with a distribuition list. The benefit of using a distribution list instead of a security group is that because it does not have a SID, it will not add a SID to the user's security token, thereby avoiding token bloat when the user is a member of many distribution lists. Enough on that.

Then there is group scope. The scope of the group can be universal, global, or domain local. Universal groups can contain users, global and universal groups from any domain in the forest, and can be applied to any ACL in the forest. Global groups can only contain members from their own domain, but can be applied anywhere in the forest, and domain local groups can contain users and groups from anywhere in the forest, but can only be applied to ACLs on computers in their own domain. Anyway, here's the code to create a universal security group.

use Win32::OLE;

$GLOBALGROUP = 2;
$DOMAINLOCALGROUP = 4;
$UNIVERSALGROUP = 8;
$SECURITYGROUP = 2147483648;

$ou=Win32::OLE->GetObject("LDAP://ou=HR,dc=myDomain,dc=net");
$group=$ou->Create("Group","cn=HRUsers");
$group->put("samAccountName","HRUsers");
$group->put("groupType",($UNIVERSALGROUP ¦ $SECURITYGROUP));
$group->SetInfo();

OK, now that we've created our group, let's add a member to it. We just created a user account for Harry, so let's add him to the HRUsers group. To add a user to a group, you connect to the group and call the Add method. The Add method takes one parameter, the ADsPath of the member to add.

use Win32::OLE;

$group=Win32::OLE->GetObject("LDAP://cn=HRUsers,ou=HR,dc=myDomain,dc=net");
$group->Add("LDAP://cn=Harry,ou=HR,dc=myDomain,dc=net");

Simple. Notice that you don't have to call SetInfo() when adding members to a group, the Add method saves the changes for you.

That's the basics of how to create users and groups in Active Directory. Now on to part 3 where I'll discuss enumerating and searching for objects.