Get a Teams Notification the Moment an Active Directory User gets Locked Out with PowerShell Using Webhooks

Get a Teams Notification the Moment an Active Directory User gets Locked Out with PowerShell Using Webhooks

I have been recently using Teams as a central location for my organizations technical notifications instead of email as it provides a way for an entire Help Desk team to openly collaborate on the message and its contents. I recently got a request to get a Teams notification when a user gets locked out of their Active Directory account. By setting up a Webhook connector we can make it happen. The script will be triggered from Task Scheduler on Event ID 4740 which is created when a user gets locked out. By using “Search-ADAccount -LockedOut” we can return an array of locked out accounts, but by ordering it by lockout time we can ensure that we grab the most recent locked out user that corresponds to the security event.

I set the script and scheduled task up on my PDC because as far as I know, the actual lockout event is only logged on the DC holding PDC Emulator FSMO role. 

 

Configure Incoming Webhook

To allow PowerShell to send data to your Teams Channel you will need to configure an incoming Webhook.

  1. In your Team, click on the channel you want the messages to be sent to
  2. Click on the 3 dots underneath the chat window, and then select “Go to store”
  3. Search for Webhook and then select it to begin configuring the Webhook
  4. You can keep the settings as is and press “Install” button located at the bottom
  5. Select the channel you want the incoming webhook to use and then press “Set Up”
  6. Give you webhook a good name. This is what users will see in the Teams chat. Upload an image and then press “Create”
  7. Copy the URL and save it for later, it will be needed. Click “Done” when you have saved the URL in a safe spot.
  8. Back in the Teams channel you can see that the webhook has been created.

Set Scheduled Task

  1. Download the script from GitHub or from below
  2. Add your Teams Webhook URL
  3. Enter the name of your domain controller. I am running mine on a domain controller so 
  4. Save the script somewhere you can reference later. I save all of mine at “C:\Automation”
  5. Open Task Scheduler and create a new Task
  6. Configure the trigger to be “When a specific event is logged”
  7. Set the log to “Security” and the Event ID to “4740”
  8. Set the Action to “Start a program”
  9. The program/script will be pointed to your script that you saved earlier. Before entering the file name enter “powershell.exe -filepath” so it knows to run the file in PowerShell.
  10. When you save your newly created scheduled task, go back in and make sure you enable “Run whether user is logged on or not”

Script / Source Code

The source code is maintained on GitHub but you can download it below as well.

 

11 thoughts on “Get a Teams Notification the Moment an Active Directory User gets Locked Out with PowerShell Using Webhooks

  1. I’m getting an error “Invoke-RestMethod : Invalid URI: The hostname could not be parsed”, my PSVersion is 4.0 so i’m trying to update to 5.1 to see if that helps, any idea why i would be getting that error

  2. Great guide, looking to have fun with it 🙂 I did notice one thing though, under Set Scheduled Task, point 3:
    “Enter the name of your domain controller. I am running mine on a domain controller so ”
    It just cuts off there!
    Thanks, Coen

  3. Thank you Brad, nice script. It encourages me to use Teams for more notifications, for example snapshots on our clusters (which need to be cleaned up, but often don’t get cleaned up).

    Keep up the good work!

  4. Great job! Some notes from our version of doing.

    * Run your script on the DC running the PDC emulator. Lockout events are immediately replicated to the PDC. I *think* bad password attempts are local to each source and not replicated.
    * Have the script also send the event data to syslog and/or email. We find it easier to spot patterns in lockout events when viewing them in Kibana or Outlook.

  5. Experiencing the following error:

    You cannot call a method on a null-valued expression.
    At C:\Scripts\PSPush_LockOut.ps1:37 char:70
    + … ed out at $(($RecentLockedOutUser.LockoutTime).ToString(“hh:mm:ss tt” …
    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : InvalidOperation: (:) [], RuntimeException
    + FullyQualifiedErrorId : InvokeMethodOnNull

  6. The message I receive says ” ‘s account was locked out at and may require additional assistance”

    Basically, the script isn’t getting any of the specific information just that there has been a locked account. Any ideas why this is happening? I am running the script on the domain controller.

    1. how are you tripping the script to run? it should be ran on the eventID thats tripped when an account is locked out, if its being tripped any other time it will return NULL because there may not be any accounts locked out

Leave a Reply

Your email address will not be published. Required fields are marked *