Using Powershell to unlock Active Directory account Unlock-ADAccount

OK, this is an easy one. There is a command in the ActiveDirectory module that already takes care of this.

Unlock-ADAccount kevmar 

So quick to type and it works so well. But unlocking the account is only part of the issue. The real question is why is it locked. If your lucky, the user will say they just miss-typed it a few times and you can let it go. Sometimes you find an account that just locks over and over. Here is a simple command that works really well in my environment to find the source of the issue:

function Get-ADAccountLockInfo

{

    [cmdletbinding()]

    param(

        $ComputerName = "servername",

        [pscredential] $Credential

    )

   

    $WinEvent = @{

        ComputerName = $ComputerName

        FilterHashtable = @{logname='security';id=4740}

    }

   

    if($Credential)

    {

        $WinEvent.Credential = $Credential

    }

   

    Get-WinEvent @WinEvent | %{

        [pscustomobject]@{

            TimeCreated  = $_.timecreated;

            Username     = $_.properties[0].value;

            ComputerName = $_.properties[1].value

        }

    }

}

Replace the server name with the name of the domain controller that is the PDC emulator. If you do not know what one that is, you can run this once for each domain controller. What it does is queries the security log for event id 4740. It then tells you who is locked at what time and where the source is.

I added a credentials option because I often execute this cross domain. The $WinEvent is a hashtable that I splat to the Get-WinEvent. That makes it easy for me to add the credential to the hashtable when if it is defined.

Any idea how to troubleshoot this with out knowing the event ID to look for? You start with the cell phone and clear any WiFi settings and emails settings. Then do the same for any tablets they have (even at home). Then exit lync and outlook on their laptop and desktop. Open 'Credential Manager' and delete all the saved credentials (do a start menu search for it). Then check all desktops and servers where they may have used RDP to connect to a session but just disconnected when they are done. Then check for services, jobs, tasks, and reporting services connections that may be using that credential.

Yeh, searching the security log is much easier.

Powershell: how to return value from function?

Returning a value from a function is really easy in Powershell. Sometimes it is too easy if you are not careful about it. One important detail to keep in mind is that Powershell is built around placing objects on the pipe. This makes functions work differently in Powershell than it does from different languages. You are also not limited to just one return value.

Here is a minimal function:

function Test-Function

{

    "Hello World!"

} 

Calling this places a string of "Hello World!" onto the pipe. You can catch it in a variable if you want or pipe it to some other command. The better way to do it is to use the Write-Output cmdlet. It makes it more clear as to what you are doing do debugging and troubleshooting become easier. 

function Test-Function

{

    Write-Output "Hello World!"

}

You can call Write-Output multiple times in a function to return multiple items. You could place it into a loop that runs 10 times and it will output 10 objects. I mention this because Powershell also supports the return keyword but it acts different. When a function gets to any return statement, it exits the function. 

function Test-Function

{

    return "Hello World!"

}

I prefer Write-Output over return but do use return when it is needed. 

I also want to mention that Write-Host is something that you see in scripts from time to time, but it is for host only output. So it is hard to capture into a variable and does not go into the pipe. In most cases, Write-Output is the better choice.

Powershell: how to call a function?

Sometimes it is the simplest thing that can be the most frustrating when learning a new language. Calling a custom function in Powershell can be one of those if you come from a different language. If you are having an issue with this, you have come to the right place. You are probably looking at something like this and wondering why it wont work:

TestFunction($Name, $Count)

If your coming from another language, this looks like it would be perfectly normal. The gotcha in Powershell is that the coma and the parenthesis are not needed here for a function call and actually mean something else. In this example it defines an array.

  

Before I go any further, let's define TestFunction:

function TestFunction ($name, $count)

{

    Write-Output "Name is '$name' and Count is '$count'"

}

It is a simple function that takes two parameters. While this works as a function and looks like something you know, let's do it the Powershell way:

function TestFunction

{

    param($name, $count)

    Write-Output "Name is '$name' and Count is '$count'"

}

So now we have a function that takes two arguments. The first argument is name and the second argument is count. Here are the correct ways to call that function:

TestFunction $Name $Count

TestFunction -name $Name -count $Count

TestFunction -name "Kevin" -count 1 

Now that we know the correct way to make that call and know what the function looks like, I can explain why our initial call fails to work. Because it is the equivalent to this call:

$Array = ($Name,$Count)

TestFunction -name $Array -count $null

So you were basically creating an array that contained your two variables and passing it in as an array to the first argument. You were also leaving the second argument as a null value. Now that you see it, it looks like a silly thing to do. No wonder things were not working as you expected.