Password expiration email notification with PowerShell

• Author
• Recent Posts

Justin Shin

I have been a Windows administrator for eight years and currently focus on Group Policy, backup, and IIS/Apache administration.

Latest posts by Justin Shin (see all)

• Password expiration email notification with PowerShell - Mon, Aug 26 2013
• WSUS basics and troubleshooting tips - Mon, Sep 24 2012
• FREE: SolarWinds Diagnostic Tool for the WSUS Agent - Fri, Jul 13 2012

For most sysadmins, resetting passwords is not a fun part of the job. In most organizations it requires much manual intervention: a frantic phone call or email from a user who cannot login, confirmation of the user’s identity, and a password reset. Not only are such requests time-consuming; frequent resets are also a security risk, as admins who deal with them frequently may slip up and forget to confirm the user’s identity before resetting his or her password.

Windows provides warnings a number of days before passwords expire, yet some users ignore them, others are logged on through the notification period, and still others (often remote users) fail to receive them entirely for a variety of reasons.

Thankfully, we do not have to rely on Windows login notifications to notify users that their passwords are soon to expire. We can actually leverage PowerShell to notify users via email! This makes the warnings harder to ignore and more likely to be delivered, especially when dealing with some remote user setups.

PowerShell password expiration notification

PowerPasswordNotify.ps1 is a PowerShell script I wrote to get you started on notifying users of password expiration. Here’s the gist of how it works:

1. Find the maximum password age for your domain
2. Search for all users in a container you specify
3. Find all users who have a password that a) expires and b) will expire within a certain number of days that you specify
4. Notify those users of their impending password expiration via email

#########################################
# PowerPasswordNotify.ps1               #
#                                       #
# Notifies users of password expiration #
#                                       #
# 4sysops.com                           #
# Author: Justin Shin                   #
#########################################

#################
# CONFIGURATION #
#################

# Variables

$PPNConfig_DebugLevel = 0

$PPNConfig_NotificationTimeInDays = 10
$PPNConfig_SMTPServerAddress = "your.smtp.server.address.or.ip.com"
$PPNConfig_FromAddress       = "noreply@company.com"
$PPNConfig_BodyIsHtml        = $true

$PPNConfig_DirectoryRoot = "LDAP://OU=Employees,DC=corp,DC=company,DC=com"
$PPNConfig_MaxPageSize = 1000

# Functions

function Configure-Notification-Subject($nName, $nNumDays)
{
	return "$nName, your password will expire in $nNumDays days."
}

function Configure-Notification-Body-Plain($nName, $nNumDays)
{
	return "Please be sure to change your password within $nNumDays."
}

function Configure-Notification-Body-Html($nName, $nNumDays)
{
	$bodyHtml =  "<h2>Your password is expiring in $nNumDays days.</h2><p>Please change your password before that time.</p>"

	return $bodyHtml
}

##########################################################################
# Edit below as needed. For most environments, this should be sufficient.#
##########################################################################

#############
# FUNCTIONS #
#############

function Get-Domain-MaxPassword-Age
{
    $ThisDomain = [System.DirectoryServices.ActiveDirectory.Domain]::GetCurrentDomain()
    $DirectoryRoot = $ThisDomain.GetDirectoryEntry()

    $DirectorySearcher = [System.DirectoryServices.DirectorySearcher]$DirectoryRoot
    $DirectorySearcher.Filter = "(objectClass=domainDNS)"
    $DirectorySearchResult = $DirectorySearcher.FindOne()

    $MaxPasswordAge = New-Object System.TimeSpan([System.Math]::ABS($DirectorySearchResult.properties["maxpwdage"][0]))

	return $MaxPasswordAge
}

function Get-Users-With-Expiring-Passwords
{
	$UsersToNotify = @()

	$DirectoryRoot = New-Object System.DirectoryServices.DirectoryEntry($PPNConfig_DirectoryRoot)
    $DirectorySearcher = New-Object System.DirectoryServices.DirectorySearcher($DirectoryRoot)
	$DirectorySearcher.filter = "(&(objectCategory=Person)(objectClass=User)(!userAccountControl:1.2.840.113556.1.4.803:=2)(!(userAccountControl:1.2.840.113556.1.4.803:=65536)))"
    $DirectorySearcher.pagesize = $PPNConfig_MaxPageSize

	$MaxPasswordAge = Get-Domain-MaxPassword-Age
	$MaxPasswordAgeDays = $MaxPasswordAge.Days

	$DirectorySearchResult = $DirectorySearcher.FindAll() |
	ForEach-Object -ErrorAction "SilentlyContinue" `
	-Process `
	{
		$PwdChanged = ([adsi]$_.path).psbase.InvokeGet("PasswordLastChanged")

		$DaysTillExpiring = $MaxPasswordAgeDays - ((Get-Date) - $PwdChanged).Days 

		if ($DaysTillExpiring -le $PPNConfig_NotificationTimeInDays)
		{
			$UserToAdd = New-Object psobject

			$UserToAdd | Add-Member NoteProperty -Name "Name" -Value ([adsi]$_.path).name[0]
			$UserToAdd | Add-Member NoteProperty -Name "Email" -Value ([adsi]$_.path).mail[0]
			$UserToAdd | Add-Member NoteProperty -Name "DaysLeft" -Value $DaysTillExpiring

			$UsersToNotify += $UserToAdd
		}

	}

	return $UsersToNotify
}

function Send-Email-Notification-Of-Expiry($nName, $nEmail, $nDaysLeft)
{
	$SmtpClient = New-Object System.Net.Mail.SmtpClient($PPNConfig_SMTPServerAddress)

	$NewMail = New-Object System.Net.Mail.MailMessage
	$NewMail.From = $PPNConfig_FromAddress
	$NewMail.To.Add($nEmail)
	$NewMail.Subject = Configure-Notification-Subject $nName $nDaysLeft

	if ($PPNConfig_BodyIsHtml)
	{
		$NewMail.IsBodyHtml = $true
		$NewMail.Body = Configure-Notification-Body-Html $nName $nDaysLeft
	}
	else
	{
		$NewMail.IsBodyHtml = $false
		$NewMail.Body = Configure-Notification-Body-Plain $nName $nDaysLeft
	}

	$SmtpClient.Send($NewMail)
}

########
# MAIN #
########

$UsersToNotify = Get-Users-With-Expiring-Passwords

foreach ($User in $UsersToNotify)
{
	if ($PPNConfig_DebugLevel -gt 0)
	{
		Write-Host $User
	}
	else
	{
		Send-Email-Notification-Of-Expiry $User.Name $User.Email $User.DaysLeft
	}
}

At a minimum, you will need to download the script, configure it, and create a scheduled task to run on a reasonable schedule (for instance, every day). You may want to modify or extend the script to suit your needs, though, and I have provided a bit of background on the more opaque aspects of the script at the end of the article.

Configuring the PowerShell script

At the top of the script are the configuration variables and functions that you must modify to make the script work, along with some optional parameters. I have denoted the “required” parameters in red.

• PPNConfig_DebugLevel: 0 is normal operation (sends email notifications); 1 prints the users who would be notified without actually sending the notification.
• PPNConfig_NotificationTimeInDays: The number of days before expiration (inclusive) that you wish to notify users
• PPNConfig_SMTPServerAddress: Your SMTP Server Address
• PPNConfig_FromAddress: Who the email is from
• PPNConfig_BodyIsHTML: Whether or not to send the email body as HTML
• PPNConfig_DirectoryRoot: The LDAP container that you wish to search in; this can be your entire domain (“LDAP://dc=corp,dc=company,dc=com”) or more specific (“LDAP://ou=finance,ou=management,dc=corp,dc=company,dc=com”)
• PPNConfig_MaxPageSize: The maximum number of results you wish to be returned from the directory search

The functions determine the subject and body of the message. Two body functions are defined: one for plain text and the other for HTML email. I have provided some very bare bones implementations.

• Configure-Notification-Subject($nName, $nNumDays)
• Configure-Notification-Body-Plain($nName,$nNumDays)
• Configure-Notification-Body-Html($nName,$nNumDays)

The default notifications are not terribly creative, so adjust to taste!

Schedule the PowerShell script

After you have configured the script and tested it manually in PowerShell, you should create a scheduled task in the Task Scheduler (or Scheduled Tasks for Windows Server 2003/R2) to execute the script on a reasonable interval. Because we are searching through the directory for user’s login details you will need to make sure that the user running it is sufficiently privileged –a domain administrator, for example. Make sure that this interval is shorter than the PPNConfig_NotificationTimeInDays setting, or otherwise some users may not get notifications before their passwords expire!

A scheduled task that executes PowerPasswordNotify.ps1

Many admins like to invoke PowerShell scheduled tasks using a batch file. The scheduler runs the batch file; the batch file starts the script. For instance, suppose you have placed PowerPasswordNotify.ps1 in the folder C:\Tasks\PPN. You might want to create a batch file (in your favorite text editor) named “StartPPN.ps1” in that folder with the text:

"C:\Windows\syswow64\Windowspowershell\v1.0\powershell.exe" -executionpolicy Unrestricted -file "C:\Tasks\PPN\PowerPasswordNotify.ps1"

Of course, depending on your Powershell version and Execution Policy, your mileage may vary.

Some explanations

There are a few places in the script that are not obvious as to how and why they work. I’ve identified the biggest potential sources of confusion – and trouble –to help you debug and extend the functionality.

Get-Domain-MaxPassword-Age

This function returns the maximum password age of the executing computer’s domain. This value is provided as a TimeSpan. You may want to extend it to return the policy of a different domain, which you can do by modifying the directory root of the searcher:

$ThisDomain = [System.DirectoryServices.ActiveDirectory.Domain]::GetCurrentDomain()
$DirectoryRoot = $ThisDomain.GetDirectoryEntry() #or another domain
...
$MaxPasswordAge = New-Object System.TimeSpan([System.Math]::ABS($DirectorySearchResult.properties["maxpwdage"][0]))

Get-Users-With-Expiring-Passwords

In order for us to search the container for enabled users with expiring passwords, we must be narrow down our filter string to include only:

1. Users: (objectCategory=Person)(objectClass=User)
2. who are enabled: (!userAccountControl:1.2.840.113556.1.4.803:=2)
3. with passwords that expire: (!(userAccountControl:1.2.840.113556.1.4.803:=65536)

If you were to delete (3) from the filter string, for example, you would end up with extraneous results – users whose passwords never expire would be notified that their passwords were about to expire.

Finally, you may want to bring over additional information in your implementation of the email notification. This is very easy to do: just add a NoteProperty for the new field that you wish to capture:

if ($DaysTillExpiring -le $PPNConfig_NotificationTimeInDays)
{
	$UserToAdd = New-Object psobject
...
	$UserToAdd | Add-Member NoteProperty -Name "Name" -Value ([adsi]$_.path).NEW_FIELD_TO_CAPTURE[0]

	$UsersToNotify += $UserToAdd
}