Benp's Guide to Stuff : Active Directory

Tech Ed 2008 - Demo 2 - Administering Servers in Bulk

benp — Thu, 12 Jun 2008 20:39:00 GMT

Bonjour Bonjour

It’s time for Demo 2 – Administering Servers in Bulk. I’ve attached the 4 scripts that I used.

Demo 2 – Administering Servers in Bulk

BulkServers1.ps1 – This script reads in a text file, containing 1 server per line. It simply then writes the server names back to the console

BulkServers2.ps1 – This script extends the first script and simply gets the hostname, operating system and service pack level for each server listed in the input file.

BulkServers3.ps1 – This script gets a little bit more complex and in fact is rather exciting. It again reads an input file and for each server, gets operating system information, bios information, writes this to a CSV file and then opens the csv file in your default CSV file handler.

BulkServers4.ps1 – The piece de resistance! This script is very similar to the above script, except that rather than read an input file with server names, it connects to the Domain Controller container in the Active Directory, and gets information from all computers in that container.

Please note, there is no error checking in these scripts, and are purely working illustrations. I would flesh these scripts out a bit more before I used them in anything other than a test infrastructure.

All done, stay tuned for Demo 3 – How Do I Know Which Classes to Use

That is all.

BenP

Creating an AD Shell

benp — Tue, 10 Apr 2007 18:28:00 GMT

Hello Again

This is my third post in the Active Directory and PowerShell series. In this post I want to talk about how to create your own pseudo-cmdlets to manage the AD. I`m going to talk about how to present scripts to PowerShell that behave in a similar way to Cmdlets, that then allow easy administration of the AD. You may well think I`m mad, but how cool would it be to do this in a shell:

PS C:\> get-dn benp

'LDAP://CN=benp,OU=Admins,DC=umpadom,DC=com'

PS C:\> enable-user benp

User: benp enabled

PS C:\> disable-user benp

User: benp disabled

PS C:\> Set-ADProp benp GivenName Ben

GivenName property set for user benp

PS C:\> Get-ADProp benp GivenName

Ben

Wait a minute! There is no native support for Active Directory that does this. What magic is this!

Well in this post I`m going to show you how to create these example pseudo-cmdlets, and show you that whilst they are mighty cool, there is nothing that difficult or clever about them.

Creating the Pseudo-Cmdlets

First thing I want to be clear about is that these commands are not real Cmdlets. They have not been added via a snapin, and do not behave in the same way as Cmdlets. The command “get-dn” is simply a function that calls a script, and passes in some arguments. The script then does some stuff and returns some text. It does not return an object! Cmdlets normally return objects – these don’t. However, we can use them to create a shell like interface to do common tasks.

The Script

Let’s take Enable-User as an example. Probably best you read my previous 2 posts before you look at this, might make it a bit easier to understand:

# Function to enable user

# Takes SAM Name

$Error.clear()

$ErrorActionPreference = "silentlycontinue"

function get-dn ($SAMName)

{

$root = [ADSI]''

$searcher = new-object System.DirectoryServices.DirectorySearcher($root)

$searcher.filter = ("(sAMAccountName= $SAMName)")

$user = $searcher.findall()

if ($user.count -gt 1)

{

$count = 0

foreach($i in $user)

{

write-host $count ": " $i.path

$count = $count + 1

}

$selection = Read-Host "Please select item: "

return $user[$selection].path

}

else

{

return $user[0].path

}

$userdn = get-dn $Args[0]

$user = [ADSI] $userdn

$user.psbase.invokeset("AccountDisabled", "False")

$user.setinfo()

if ($error.count -ne 0)

{

"Error enabling user: " + $Args[0]

$error[0].exception

}

else

{

"User: " + $Args[0] + " enabled"

}

Most of this code is the same as get-dn, which I explained in my previous post. There only difference is what we do to the AD, and a bit of basic error checking. Let’s go through what happens in the code once we have the path to the user object we want to manipulate:

$userdn = get-dn $Args[0]

$user = [ADSI] $userdn

$user.psbase.invokeset("AccountDisabled", "False")

$user.setinfo()

All we do is create an object with the user object path as a constructor. Once we have this we simply set the user property AccountDisabled to be False. Then we commit the change to the AD. Simple! I use the invokeset method here, because it’s really easy to use. If you use the ADSI provider its actually a bit harder than the .Net Framework method.

The error handling here is very basic. I might write a post on error handling soon. The basic algorithm for error handling is:

Clear the $error.count

Do Stuff

If the $error.count is greater than 0 (we had an error)

Output anerror message

Else

Output operation successful text

Turning the script to a Pseudo-Cmdlet

To make the script accessible from just typing “enable-user”, all we need to do is create a function that utilises that script. To create a function we use the new-item Cmdlet. Here’s the code I use:

new-item -path function:enable-user -value {& 'C:\scripts\enable-user.ps1' $args[0]}

There we go. An easy way to enable user accounts.

That function will be loaded in PowerShell until the instance of PowerShell closes. So how can we make the function persistent? Well there are 2 ways. The simple way is to add this line to your profile. The profile file can be found by typing $profile in the shell. That means that every time you load PowerShell the function will be loaded.

However, I don’t really want that. I want to be able to load a script with all these functions when I want to administer the AD. Therefore I collected all my function definitions into 1 file: ADSupport.ps1. This file contains this:

new-item -path function:get-dn -value {& 'C:\scripts\getuserdn.ps1' $args[0]}

new-item -path function:get-adprop -value {& 'C:\scripts\get-adprop.ps1' $args[0] $args[1]}

new-item -path function:set-adprop -value {& 'C:\scripts\set-adprop.ps1' $args[0] $args[1] $args[2]}

new-item -path function:disable-user -value {& 'C:\scripts\disable-user.ps1' $args[0]}

new-item -path function:enable-user -value {& 'C:\scripts\enable-user.ps1' $args[0]}

Problem: if I run .\adsupport.ps1 it does not import these functions. If you try it you’ll find that none the functions are available. This is because by default the script is executed in a different scope. We want it executed in the PowerShell scope and therefore we must use an extra full stop (period if you live across the atlantic).

. .\adsupport.ps1

Now all your functions will be available to use.

Other Scripts

Here is the code to get all the above functions working.

Get-DN

See previous post

Disable User

# Function to disable user

# Takes SAM Name

$error.psbase.clear()

$erroractionpreference = "silentlycontinue"

function get-dn ($SAMName)

{

$root = [ADSI]''

$searcher = new-object System.DirectoryServices.DirectorySearcher($root)

$searcher.filter = ("(sAMAccountName= $SAMName)")

$user = $searcher.findall()

if ($user.count -gt 1)

{

$count = 0

foreach($i in $user)

{

write-host $count ": " $i.path

$count = $count + 1

}

$selection = Read-Host "Please select item: "

return $user[$selection].path

}

else

{

return $user[0].path

}

$userdn = get-dn $Args[0]

$user = [ADSI] $userdn

$user.psbase.invokeset("AccountDisabled", "True")

$user.setinfo()

if ($error.count -ne 0)

{

"Error disabling user: " + $Args[0]

$error[0].exception

}

else

{

"User: " + $Args[0] + " disabled"

}

Get-ADProp

# Function to query AD Object Properties

# Takes SAM, Property

$Error.psbase.clear()

$ErrorActionPreference = "SilentlyContinue"

#Use the below line in the profile to assign to get-adprop

#new-item -path function:get-adprop -value {& 'C:\store\ps scripts\get-adprop.ps1' $args[0] $args[1]}

function get-dn ($SAMName)

{

$root = [ADSI]''

$searcher = new-object System.DirectoryServices.DirectorySearcher($root)

$searcher.filter = ("(sAMAccountName= $SAMName)")

$user = $searcher.findall()

if ($user.count -gt 1)

{

$count = 0

foreach($i in $user)

{

write-host $count ": " $i.path

$count = $count + 1

}

$selection = Read-Host "Please select item: "

return $user[$selection].path

}

else

{

return $user[0].path

}

$username = get-dn $Args[0]

$user = [ADSI] $username

$user.Get($Args[1])

if ($error.count -ne 0)

{

"Error getting property " + $Args[1] + " for " + $Args[0]

$error[0].exception

}

Set-ADProp

# Function to set AD Object Properties

# Takes SAM, Property, Value

#Use the below line in the profile to assign to get-adprop

#new-item -path function:set-adprop -value {& 'C:\store\ps scripts\set-adprop.ps1' $args[0] $args[1] $args[2]}

function get-dn ($SAMName)

{

$root = [ADSI]''

$searcher = new-object System.DirectoryServices.DirectorySearcher($root)

$searcher.filter = ("(sAMAccountName= $SAMName)")

$user = $searcher.findall()

if ($user.count -gt 1)

{

$count = 0

foreach($i in $user)

{

write-host $count ": " $i.path

$count = $count + 1

}

$selection = Read-Host "Please select item: "

return $user[$selection].path

}

else

{

return $user[0].path

}

$username = get-dn $Args[0]

$user = [ADSI] $username

$user.put($Args[1], $Args[2])

$user.setinfo()

if ($error.count -ne 0)

{

"Error setting " + $Args[1]

$error[0].exception

}

else

{

$Args[1] + " property set for user" + $Args[0]

}

Well ladies and gents. Hope you enjoyed this. Coding errors on a post card please J

That is all

BenP

Searching the Active Directory with PowerShell

benp — Mon, 26 Mar 2007 17:53:00 GMT

Hello world

It’s time for my second post and I thought I would talk about searching the active directory. I ran a PowerShell course yesterday and the delegates were itching to find out a bit more about searching an AD. So I said I would make sure I posted something on the blog.

So let’s get going! To start with I`m going to introduce a script that I would be lost without: “get-dn.ps1”. This script takes a SAM account name as input and returns the objects full CN as output. We can then use this output to then connect directly to the object. Here’s the code:

function get-dn ($SAMName)

{

$root = [ADSI]''

$searcher = new-object System.DirectoryServices.DirectorySearcher($root)

$searcher.filter = "(&(objectClass=user)(sAMAccountName= $SAMName))"

$user = $searcher.findall()

if ($user.count -gt 1)

{

$count = 0

foreach($i in $user)

{

write-host $count ": " $i.path

$count = $count + 1

}

$selection = Read-Host "Please select item: "

return $user[$selection].path

}

else

{

return $user[0].path

}

$Name = $args[0]

$path = get-dn $Name

"'" + $path + "'"

So now let’s look at this code in a bit more detail.

The first bit of the code simply creates a function to do most of the work. We take an argument in $SAMName that will hold the name of the account we wish to search for

function get-dn ($SAMName)

{

The next bit of code creates 2 objects. $root is a standard ADSI object that connects to the domain we are in. $searcher is a DirectorySearcher object, and we pass the ADSI object $root in as a constructor. Effectively we’re saying search the domain we’re in.

$root = [ADSI]''

$searcher = new-object System.DirectoryServices.DirectorySearcher($root)

Now we have created a DirectorySearcher object we need to set the search criteria. To do his we use the filter property of $searcher. See the LDAP Search Strings section below for more information. Once we have the criteria, we simply use the findall() method to find all instances that match the filter in the domain and return the results to $user

$searcher.filter = "(&(objectClass=user)(sAMAccountName= $SAMName))"

$user = $searcher.findall()

$user actually contains a collection of objects that match the search criteria. If we have more than one match, the collection has more than one element. This bit of code says “If we have more than 1 result, write all the results to screen and allow the user to select which object they mean”. The shrewd among you may think, “SAMAccountName is unique, we can’t have 2 of them”. You’re right however, we could implement wildcard searching, or searching by surname which might result in multiple matches making this really useful. Finally we return the path to the object. We return the object path because it includes the “LDAP://” which we would need to connect to the object directly.

if ($user.count -gt 1)

{

$count = 0

foreach($i in $user)

{

write-host $count ": " $i.path

$count = $count + 1

}

$selection = Read-Host "Please select item: "

return $user[$selection].path

}

The last bit of the if statement simply returns the path of the 1^st element, if there is only 1 element in the collection. Then we finish of the function with a }.

else

{

return $user[0].path

}

The final section simply assigns the passed in argument to the variable $Name. We then call the get-dn function passing in $Name, and put the result in $path. At the very end we wrap the path in a ‘ and ‘ so that you can then copy and paste the returned line straight into an [ADSI] constructor. (see the previous post)

$Name = $args[0]

$path = get-dn $Name

"'" + $path + "'"

This function is really useful. Once I have got a hit I can use the output to quickly connect to an object in the Active Directory. I could for example type the following in PowerShell:

PS C:\store\ps scripts> .\get-dn.ps1 administrator

'LDAP://CN=Administrator,CN=Users,DC=umpadom,DC=com'

PS C:\store\ps scripts> $user = [ADSI] 'LDAP://CN=Administrator,CN=Users,DC=umpadom,DC=com'

PS C:\store\ps scripts> $user

distinguishedName

-----------------

{CN=Administrator,CN=Users,DC=umpadom,DC=com}

DirectorySearcher Object

For more information on the DirectorySearcher object check out MSDN here:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfSystemDirectoryServicesDirectorySearcherMembersTopic.asp

Some members of DirectorySearcher that you might want to look at in more detail are:

PageSize – this limits the amount of results that get returned, and can be really handy when you are searching big domains.

Filter – This is the search criteria that is used to search the Active Directory. It uses LDAP search strings. See the below section for more information

LDAP Search String’s

The DirectorySearcher filter property takes LDAP search strings. These strings use their own language. More information can be found here.

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemdirectoryservicesdirectorysearcherclassfiltertopic.asp

Basically, these are the four things to bear in mind when creating LDAP search strings.

1. The string must be enclosed in parentheses.

2. Expressions can use the relational operators: <, <=, =, >=, and >. An example is "(objectClass=user)". Another example is "(lastName>=Davis)".

3. Compound expressions are formed with the prefix operators & (and) and | (or). An example is"(&(objectClass=user)(lastName= Davis))". Another example is "(&(objectClass=printer)(|(building=42)(building=43)))".

4. Wildcards can be used. Use * operator

As ever, here are some examples. Below are some LDAP search strings that could be assigned to the DirectorySearcher.Filter property.

Find all users by explicit SAMName

"(&(objectClass=user)(sAMAccountName= $SAMName))"

Find all users where SAMName begins with xyz

"(&(objectClass=user)(sAMAccountName= $SAMName*))"

Find all users where Surname begins with xyz

"(&(objectClass=user)(sn= $Name*))"

Find all computers where computer name starts with xyz

"(&(objectClass=computer)(sAMAccountName= $ComputerName*))"

Well ladies and gentleman, here endeth the lesson.

That is all

BenP

Benp’s Basic Guide to Managing Active Directory Objects with PowerShell

benp — Mon, 05 Mar 2007 16:59:00 GMT

Guys + Gals

So here is my first post! How exciting!

The last few weeks I have been writing a private 1 day workshop entitled “Introduction to PowerShell”. This is a classroom based workshop run in the UK. As part of the workshop I decided to put in a section on how to interact with the Active Directory, and soon found it to be a bit harder than I thought. Not that working with the AD is hard; it’s just there isn’t too much documentation. I spent a day or two trawling though various blogs, but soon got pretty frustrated. So I thought I’d put together “Benp’s Basic Guide to Managing Active Directory Objects with PowerShell”. Catchy title huh .....

Agenda

People might be wondering if they can need to read this blog. Well here is a quick overview of what I will talk about:

· Active Directory manipulation in PowerShell is really powerful.

· [ADSI] is a wrapper on the DirectoryEntry class and provides its own methods.

· Full support of System.DirectoryServices.DirectoryEntry is provided. Just remember psbase is the key.

· You can interchange using [ADSI] and raw DirectoryEntry commands

PowerShell Basics

Before we start, this Blog assumes a bit of prior knowledge of PowerShell. I`m going to assume PowerShell is installed correctly, and that you have a basic understanding of Cmdlets and their use. To get up to speed with PowerShell check out the PowerShell homepage:

http://www.microsoft.com/windowsserver2003/technologies/management/powershell/default.mspx

In particular, I watched the PowerShell Week Webcasts, and found them excellent. Find them here:

http://www.microsoft.com/technet/scriptcenter/webcasts/ps.mspx

There are 5, 1 hour Webcasts that take you from absolute beginner, to PowerShell guru. Most Excellent!

Right, enough chatter – let’s get down to business!

[ADSI] and System.DirectoryServices.DirectoryEntry Overview

Firstly, there are two main ways to interact with the AD using PowerShell, and both are closely linked. Let’s get an overview and see how they relate to each other.

The basic building block is the .Net Framework Object “System.DirectoryServices.DirectoryEntry”. This is a well documented class that anyone using C# or managed code might have come across before. This object is pretty raw, and you’re allowed to feel like a hardcore dev guy when you’re using it. This class isn’t quite as easy to use as you might hope. More on that later! However, you can always use this class and its methods and properties, but in PowerShell they’re hidden from you.

Let me introduce the other player [ADSI]. [ADSI] is essentially a wrapper that we have put around the DirectoryEntry object. The question has to be asked “Why the heck have you done that?!?” The answer is as follows: this wrapper feels a bit more like the VBScript ADSI provider. You can use the same sort of syntax in PowerShell that you might use in VBScript. So, if you’re coming from a C# background the raw DirectoryEntry object will feel nicer, if you’re coming from VBScript, [ADSI] will feel nicer.

So let’s look at both methods in a bit more detail:

[ADSI]

PowerShell provides a really nice way of learning about objects. By using Get-Member you can view exactly what properties and methods are exposed for an object. Sadly, this doesn’t work with an [ADSI] object in PowerShell. Doh! The code below creates a variable $Dom that is bound to the root of your AD. Try for yourself: (For more info see the “Binding to Objects” section below)

$Dom = [ADSI]'’

$Dom| Get-Member

See, there’s a list of properties but no methods! Why!!!???!!

Good question, and one with a deeply technical answer. Check out this post from Arul Kumaravel, PowerShell Development Manger for a bit more info:

http://pathologicalscripter.wordpress.com/2006/09/28/invisible-methods-for-adsi/

So I guess it might be handy to list some of the key invisible methods for ADSI:

Create()

Get()

Put()

Delete()

SetInfo()

The above is not a definitive list, but certainly covers lots of things that you might want to do with the Active Directory.

System.DirectoryServices.DirectoryEntry

The other way to manipulate the AD is the DirectoryEntry class. As this is an existing .Net Framework class, there is a lot more documentation. In fact all properties and methods are documented here:

Properties

Methods

However, we saw above in the [ADSI] sections that there are no methods. Here a quick reminder:

$Dom | Get-Member

Zero methods are returned.

Due to the wrapping of the DirectoryEntry object we need to get back to the base class properties and methods. To do this we use psbase. When we use the psbase keyword we are effectively peeling back all wrappers on the object, and getting back to the raw base object. Try this:

$Dom.psbase | Get-Member

Sweet! Loads of members, and looks pretty darn similar to the MSDN documentation. So now you can just add .psbase to access all DirectoryEntry methods and properties:

$Dom.psbase.get_children()

Code to do stuff

“Enough chatting!” I hear you cry, “Show me some code that I can rampantly plagiarize! I wanna get out of here!”.

Settle down, settle down the information you so desperately want is at hand. I`ll give some code samples, and because we can, let’s use both the [ADSI] syntax, and the DirectoryEntry syntax.

Code in the blue font is using [ADSI]

Code in the red font is using DirectoryEntry

Binding to an object

$MyVar = [ADSI] ‘<Enter Connection String Here>’

$MyVar = New-Object system.directoryservices.directoryentry '<Enter Connection String Here>'

$MyDom = [ADSI] ‘’ # connects to root domain

$MyDom = New-Object system.directoryservices.directoryentry''

Now let’s connect to a specific object.

$User = [ADSI] 'LDAP://CN=Ben Pearce,OU=London,DC=umpadom,DC=com'

$User = New-Object system.directoryservices.directoryentry ‘LDAP://CN=Ben Pearce,OU=London,DC=umpadom,DC=com’

Once you have bound to an object you can interchange whether you use [ADSI] commands or DirectoryEntry commands. So the result of either of the commands executing is the same. Therefore I always use the [ADSI] method. Much less typing!

Create a User

$username = ‘benp’

#Bind to OU

$adminsOU = [ADSI] 'LDAP://OU=admins,DC=umpadom,DC=com'

#Create the user

$user = $adminsOU.create('User','CN='+ $username)

#Commit Changes

$user.setinfo()

#Set the SAMAccountName

$user.sAMAccountName = $username

#Commit Changes

$user.setinfo()

$username = ‘benp’

#Bind to OU

$adminsOU = New-Object System.DirectoryServices.DirectoryEntry("LDAP://OU=admins,DC=umpadom,DC=com")

#Create the user

$user = $adminsOU.psbase.get_children().add(‘CN=’ + $username,'User')

#Commit Changes

$user.psbase.CommitChanges()

#Set the SAMAccountName

$user.psbase.invokeset(‘sAMAccountName’,$username)

#Commit Changes

$user.psbase.CommitChanges()

Both sets of the above code do exactly the same thing. So like Binding to Objects I take the [ADSI] approach every time.

Read a Property

If the parameter is exposed by the ADSI interface it is really easy to read a parameter.

$user = [ADSI] 'LDAP://CN=Ben Pearce,OU=London,DC=umpadom,DC=com'

$user.Title

However, not all properties of an object are exposed there. The below code can be used to get any property whether exposed in ADSI or not.

$user = [ADSI] 'LDAP://CN=Ben Pearce,OU=London,DC=umpadom,DC=com'

$user.get(‘Title’)

$user = System.DirectoryServices.DirectoryEntry 'LDAP://CN=Ben Pearce,OU=London,DC=umpadom,DC=com'

$user.psbase.invokeget(‘Title’)

$user.psbase.commitchanges()

Modify a Property

Again if the properties are exposed, modifying a property is really easy.

$user = [ADSI] 'LDAP://CN=Ben Pearce,OU=London,DC=umpadom,DC=com'

$user.Title

$user.setinfo()

However, not all properties of an object are exposed there. The below code can be used to set any property whether exposed in [ADSI] or not.

$user = [ADSI] 'LDAP://CN=Ben Pearce,OU=London,DC=umpadom,DC=com'

$user.put(‘Title’,’IT Pro’)

$user.setinfo()

$user = System.DirectoryServices.DirectoryEntry 'LDAP://CN=Ben Pearce,OU=London,DC=umpadom,DC=com'

$user.psbase.invokeset(‘Title’,’IT Pro’)

$user.psbase.commitchanges()

$user = [ADSI] 'LDAP://CN=Ben Pearce,OU=London,DC=umpadom,DC=com'

$user.psbase.invokeset(‘Title’,’IT Pro’)

$user.psbase.commitchanges()

See, I`m mixing it up now!

Delete a User

$username = ‘benp’

# Connect to parent OU

$adminsOU = [ADSI] 'LDAP://OU=admins,DC=umpadom,DC=com'

# Delete user

$user = $adminsOU.delete('User','CN='+ $username)

$username = 'LDAP://CN=benp,OU=Admins,DC=umpadom,DC=com'

#Bind to user

$user = New-Object System.DirectoryServices.DirectoryEntry $username

#Delete User

$user.psbase.DeleteTree()

$username = 'LDAP://CN=benp,OU=London,DC=umpadom,DC=com'

#Bind to user

$user = [ADSI] ‘$username’

#Delete User

$user.psbase.DeleteTree()

Conclusion

Well that’s the end of the blog. Here’s a quick summary to consolidate today’s information:

· Active Directory manipulation in PowerShell is really powerful.

· [ADSI] is a wrapper on the DirectoryEntry class and provides its own methods.

· Full support of System.DirectoryServices.DirectoryEntry is provided. Just remember psbase is the key.

· You can interchange using [ADSI] and raw DirectoryEntry commands

Comments are welcome and any feedback much appreciated. I hope you found this useful, if so let me know. If alternatively you think it’s a big steaming pile of tosh, let me know.

That is all

BenP