PowerShell: Sending password expiration notices via GMail – Part 2

In the first part of this trio of posts, I showed a way to identify users whose password was about to expire. Which is useful, but now you need to notify them. If your company email is in GMail, there's a few gotchas you'll need to watch out for, but I'll show you how to get it all working.

The process to email each of those users you identified in Part 1 has the following component parts:

  • Setup your log file if the -Logging switch was used
  • Get credentials for sending the email from a notification only address.
  • Extract the relevant user details for each user
  • Calculate the number of days before the user's password expires
  • Set the content of the email (subject, body, etc.)
  • Configure logging and testing behaviours
  • Send the actual email

First, to set up our logfile (a CSV file with details on each user we've sent email to):

if ($Logging) { 
   $logFile = 'C:\Temp\emaillogs.csv'
   if (! (Test-Path 'C:\Temp') ) {
      Write-Verbose 'No C:\Temp directory, so creating one...'
      New-Item -Path 'C:\' -Name 'Temp' -ItemType 'Directory'
   }

    # Remove Logfile if it already exists
    if ( (Test-Path $logFile)) { 
      Remove-Item $logFile 
    }
    # Create CSV File and Headers 
    New-Item -Path $logfile -ItemType File 
    Add-Content $logfile "Date,Name,EmailAddress,DaysLeft,ExpiresOn,Notified" 
}

Now there are certainly other was to do this, but this works, so I use it.

When you go to send the email, you'll likely want to use a notification only address, rather than your real one. But for that, you'll need to prompt for credentials. Or store them in a file, as described in an earlier post. To prompt, use:

$gCred = Get-Credential -UserName "it-notification@treyresearch.net" `
                        -Message  "Enter Password for IT-Notification account"

Now, let's start to build the ForEach loop you'll use to do the work of this process for each user. Start by extracting the relevant user details. (Note that $TreyUsers was built in Part 1 of this series).

foreach ($user in $TreyUsers) { 
    $Name  = $user.Name 
    $Email = $user.emailaddress 
    $Sam   = $user.SAMAccountName
    $sent  = "" # Reset Sent Flag 
    $passwordSetDate = $user.PasswordLastSet 
}

Now, continuing in that same ForEach loop, calculate how many days until their password expires, and set some text based on that:

$expiresOn = $passwordSetDate + $maxPasswordAge 
$DaysLeft  = (New-TimeSpan -Start $today -End $Expireson).Days 
         
if (($DaysLeft) -gt "1") { 
    $MessageDays = "in " + "$DaysLeft" + " days." 
} else { 
    $MessageDays = "today." 
}

You'll use that $MessageDays variable as you build your email message. That email message needs to tell them how long they have, and where and how to change their password. This last part is particularly important if you have users who regularly work remote, or whose primary work computer is a non-Windows computer. But even connected Windows users often have problems. :(

So, for the message subject you have:

$subject="Your password will expire $messageDays"

And for the message body, use something like this:

$body =@" 
Dear $name, 
<p>Your TreyReseach.net Active Directory Domain credentials <b>will expire $messagedays</b> 
Please update your credentials as soon as possible! <br> </p>

<p>If you are using a Windows domain joined system and are connected to the intranet, 
press ctrl-alt-delete and select change password. Alternatively, if you are outside of the 
network, connect to the corporate VPN and reset your password with the same process.<br> </p>

<p>If you are not using a Windows based system, ensure you are on the intranet or connected to 
the corporate VPN.  Proceed to https://password.TreyResearch.net <https://password.TreyResearch.net> 
and reset your password.<br> </p>

<p>This process will also sync your newly created AD password to your Gmail password. Please 
allow up to 5 minutes for replication of the passwords to occur.<br><br> </p>

<p><br><b>Problems</b>? <br>Please open a Service Desk request by clicking on the 
Help Agent icon on system. If you are NOT running a Help Agent, please contact a member
of the IT Team for instructions on how to install the agent. It is a strict TreyResearch 
company policy that all company-owned systems run the Help Agent. <br></p>
   
<p>Thanks, <br>  
IT Team
</P>
"@

Now you'll notice two things about that email body. First, it uses PowerShell's Here-String capability, making it easier to edit and even include double-quotes inside it if you want. You can do this without using a Here-String, but for any long text like this, it's easier in the long run. The second thing is that it includes some basic HTML codes. Gmail allows them, so use them for emphasis where appropriate.

 

Next, let's set up the processing of test messages and logging. First, for test messages, you'll want to override the user's email to only send it to yourself, or to your team. Still inside the ForEach loop, do that with:

[string[]]$testRecipient = $Charlie,$AdminUser2,$AdminUser3 
# If Testing Is Enabled--Email Admins, not real users, and cc an external address 
if ($testing) { 
    $email = $testRecipient 
    $Subject = "PasswordExpiration Test Message"
    $cclist = $externalUser
}

You'll also want to handle logging, so write the logging information to the log file you created earlier.

if ($Logging) {
    Add-Content $logfile "$date,$Name,$email,$DaysLeft,$expiresOn,$Sent"  
}

Finally, send the actual message:

Send-MailMessage -smtpServer $smtpServer `
                 -from       $from `
                 -to         $email `
                 -cc         $cclist `
                 -subject    $subject `
                 -body       $body `
                 -bodyasHTML `
                 -priority   High `
                 -Encoding   $textEncoding `
                 -UseSSL `
                 -port       $SMTPPort `
                 -Credential $gCred

You'll notice a couple of things there. One, you need to identify your SMTP server and the SMTP port to use. That's usually smtp.gmail.com and port 587 for mail sent this way. Next, you need to have set the $textEncoding variable somewhere. In most cases, this will be UTF8, and you'll set that with:

$textEncoding = [System.Text.Encoding]::UTF8

Adjust as necessary for your environment.

 

Now, let's finish off by handling testing - you only want to send a single message to yourself if you're testing, not 60 of them! Do that with:

if ($Testing) {
   "Sleeping 5, then breaking so we only process a single record"
   Sleep 5
   Break
}

Finally, outside the ForEach loop, if logging is enabled, display the results of the logging file in a way you can read:

if ($Logging) { 
   # Use the logging file to display a table of the accounts about to expire. 
   $expiringAccts = Import-Csv -Path $logfile
   $expiringAccts | Sort-Object -Property ExpiresOn `
                  | Format-Table -AutoSize `
                    @{Expression={$_.DaysLeft};`
                           Label="#Days";`
                           align="Right";
                           width=7}, `
                    Name,`
                    @{Expression={(Get-Date -Date $_.ExpiresOn -Format 'MMMM dd')};`
                           Label="Expires On:"}
}

I'll post the entire script in Part 3, shortly, complete with comment-based help and full details.

Leave a Reply

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