Charlie Russel's Blog

So, as I mentioned the other day, we needed to do some major cleanup of defunct and orphaned computer accounts. Most computers that hadn’t been logged in to in the last year needed to go. And there were a LOT of them! Certainly more than anyone wanted to try to do in the GUI. So, having found them, it was time to remove them, using:

$oneyear = (Get-Date).AddDays(-365)
Get-ADComputer -Filter {(LastLogonDate -lt $oneyear ) -AND `
((Name -like "ws-*")
-OR (Name -like "Desktop*")
-OR (Name -like "XP-*"))}
-Properties LastLogonDate | Remove-ADComputer -Confirm:$False -Verbose

And I started watching the deletions go by on the screen. Honestly, a fairly scary moment. Especially when I started to see some errors scroll by..

VERBOSE: Performing the operation "Remove" on target "CN=WS-DCOVENTRY-02,OU=\#Workstations,DC=Contoso,DC=com".
VERBOSE: Performing the operation "Remove" on target "CN=WS-VTAWARE-02,CN=Computers,DC=Contoso,DC=com".
VERBOSE: Performing the operation "Remove" on target "CN=WS-VIMALG-02,CN=Computers,DC=Contoso,DC=com".
VERBOSE: Performing the operation "Remove" on target "CN=WS-FHEMMATI-02,OU=\#Workstations,DC=Contoso,DC=com".
VERBOSE: Performing the operation "Remove" on target "CN=WS-BGL-ECOM,CN=Computers,DC=Contoso,DC=com".
Remove-ADComputer : The directory service can perform the requested operation only on a leaf object
At line:1 char:228
+ ... LogonDate | Remove-ADComputer
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : NotSpecified: (CN=WS-BGL-ECOM,...C=Contoso,DC=com:ADComputer) [Remove-ADComputer], ADExce
ption
+ FullyQualifiedErrorId : ActiveDirectoryServer:8213,Microsoft.ActiveDirectory.Management.Commands.RemoveADCompute
r


I ended up with about 15% of the computer accounts refusing to be removed with Remove-ADComputer. So I checked the man pages for Remove-ADComputer, and there were no additional parameters that would overcome it. Well, phooie!

OK, so time to haul out the seriously powerful tool, Remove-ADObject -Recursive. A word of warning here — you can do some serious damage with this command.  First, I verified the cause of the failures — the offending computer accounts had subsidiary objects that they probably shouldn’t ever have had. OK, all that was before my time, but none of them were any longer relevant. So, now, my command needed to morph due to the somewhat more annoying syntax of Remove-ADObject. I couldn’t just pipe the results of Get-ADComputer to it, I needed to return a list of objects and walk through them with a ForEach loop, like this:

$oneyear = (Get-Date).AddDays(-365)
$adFilter = {(LastLogonDate -lt $oneyear ) -AND ((Name -like "ws-*") -OR (Name -like "Desktop*") -OR (Name -like "XP-*"))}

ForEach ($Computer in (Get-ADComputer -Filter $adFilter -Properties LastLogonDate)) {
Remove-ADObject $Computer -Recursive -Confirm:$False -Verbose
}

And there go the last of the orphaned accounts! Notice, by the way, the use of a variable to hold the filtering criteria. This is a useful trick if you’re iterating through a bunch of filters, or dealing with a fairly long and complicated one. You need to edit the variable with each iteration, but the actual command stays the same. Plus, IMHO, it makes the whole thing more readable.

The other day we decided it was time and more to do some cleanup of orphaned computer accounts in our AD. We are about to do some AD restructuring, and figured it was a good opportunity to clean up and remove old computer accounts for machines that no longer existed. Now there are probably lots of ways to do this, but the way I chose was to look at the AD properties of the computer to see when it was last logged on to. Then arbitrarily deciding that any computer that hadn’t been logged on to in the last year was a good candidate. At first glance, that’s not part of the properties that are returned with Get-ADComputer:

Get-ADComputer -Identity srv2


DistinguishedName : CN=SRV2,OU=Servers,DC=contoso,DC=com
DNSHostName       : srv2.contoso.com
Enabled           : True
Name              : SRV2
ObjectClass       : computer
ObjectGUID        : 0ce3c9fa-4b07-4dde-8323-ff94153d2bf9
SamAccountName    : SRV2$
SID               : S-1-5-21-2576220272-3971274590-1167723607-15115
UserPrincipalName :

But wait, I know there have to be more than that — let’s try making sure that we get all the properties, not just the most common:

Get-ADComputer -Identity srv2 -Properties *

AccountExpirationDate                :
accountExpires                       : 9223372036854775807
AccountLockoutTime                   :
AccountNotDelegated                  : False

...

DistinguishedName                    : CN=SRV2,OU=Servers,DC=contoso,DC=com
DNSHostName                          : srv2.contoso.com

...

KerberosEncryptionType               : {RC4, AES128, AES256}
LastBadPasswordAttempt               : 4/25/2016 6:28:41 PM
LastKnownParent                      :
lastLogoff                           : 0
lastLogon                            : 131689942478668713
LastLogonDate                        : 4/18/2018 10:18:47 PM
lastLogonTimestamp                   : 131685887279055446

...

whenCreated                          : 4/23/2015 6:28:41 PM

Ah, that’s more like it. Now I can see that there’s a LastLogonDate property. That should do it. Now, it’s just a case of simple math. And because we’re looking for more than a single computer, we need to switch to using the -Filter parameter of Get-ADComputer. Plus I’ll specify which server to query, and the account credentials to use to run the query:

Get-ADComputer `
        -Server dc01 `
        -Credential $cred `
        -Filter * `
        -Properties LastLogonDate `
              | Where-Object LastLogonDate -lt (Get-Date).AddDays(-365) `
              | Select-Object Name,LastLogonDate

Now that’s fine for moderately sized Active Directories, but could be a bit of a problem for large ones. So, instead of grabbing every computer in the domain and then filtering them, let’s only get the one’s that fit our one year criteria.

$oneyear = (Get-Date).AddDays(-365)
Get-ADComputer `
        -Server dc01 `
        -Credential $cred `
        -Filter {LastLogonDate -lt $oneyear } `
        -Properties LastLogonDate `
             | Select-Object Name,LastLogonDate `
             | ConvertTo-CSV -NoTypeInformation > C:\Temp\Defunct.csv

And now we have the list usefully exported to a CSV where we can manipulate it and verify the names really are those of orphaned computers. From there, I could feed the list of computers into Remove-ADComputer, or I can do it directly by piping this result to Remove-ADComputer, complete with a -Force parameter. Yeah. Right. And maybe a good idea to just verify the list first.

ETA: Well, it might be a good idea to check the available parameters for Remove-ADComputer before I post something. Sigh. There is no -Force parameter. Instead, you need to use -Confirm:$False if you want Remove-ADComputer to just do its work without prompting. And if the computer has any objects associated with it, you’ll have to use Remove-ADObject. But more on that in another post.

When building out a workstation for an AD Domain user, in some environments the user is added to the local Administrators group to allow the user to install and configure applications. Now there are some of us who think that’s a Bad Idea and a Security Risk, but the reality is that it’s policy in some organizations. Doing this with the GUI is easy, but who wants to have to use the GUI for anything? Especially for a highly repetitive task that you’re going to have to do on every user’s workstation. So, let’s use PowerShell and [ADSI] to do the heavy lifting.

The first step is to define the target we want to add the user to:

$ComputerName = "workstation01"
$Group = "Administrators"
$target=[ADSI]"WinNT://$ComputerName/$Group,group"

Next, we invoke the Add method on that target to add the user to the group.

$Domain = 'TreyResearch'
$UserName = 'Charlie.Russel'
$target.psbase.Invoke("Add",([ADSI]"WinNT://$Domain/$UserName").path)

And that’s really all there is to it.

(Note, by the way, that this is one of the only places in PowerShell where CASE MATTERS. the WinNT commands are case sensitive so don’t change that to winnt or WINNT. It won’t work. )

Finally, let’s pull all that together into a script that accepts the user name, the target computer, and the AD Domain as parameters:

<#
.Synopsis
Adds a user to the Local Administrators group
.Description
Add-myLocalAdmin adds a user to the local Administrators group on a computer. 
.Example
Add-myLocalAdmin Charlie.Russel 
Adds the TreyResearch user Charlie.Russel to the Administrators local group on the localhost.
.Example
Add-myLocalAdmin Charlie.Russel -ComputerName ws-crussel-01
Adds the TreyResearch user Charlie.Russel to the Administrators local group on ws-crussel-01.
.Example
Add-myLocalAdmin -UserName Charlie.Russel -ComputerName ws-crussel-01 -Domain Contoso
Adds the Contoso user Charlie.Russel to the Administrators local group on ws-crussel-01.
.Parameter UserName
The username to add to the Administrators local group. This should be in the format first.last. 
.Parameter ComputerName
[Optional] The computer on which to modify the Administrators group. The default is localhost
.Parameter Domain
[Optional] The user's Active Directory Domain. The default is TreyResearch.
.Inputs
[string]
[string]
[string]
.Notes
    Author: Charlie Russel
 Copyright: 2017 by Charlie Russel
          : Permission to use is granted but attribution is appreciated
   Initial: 21 June, 2017 (cpr)
   ModHist:
          :
#>
[CmdletBinding()]
Param(
     [Parameter(Mandatory=$True,Position=0)]
     [alias("user","name")]
     [string]
     $UserName,
     [Parameter(Mandatory=$False,Position=1)]
     [string]
     $ComputerName = 'localhost',
     [Parameter(Mandatory=$False)]
     [string]
     $Domain = 'TreyResearch'
     )

$Group = 'Administrators'

# Please be warned. The syntax of [ADSI] is CASE SENSITIVE!
$target=[ADSI]"WinNT://$ComputerName/$Group,group"
$target.psbase.Invoke("Add",([ADSI]"WinNT://$Domain/$UserName").path)

One of the tasks that I’m often asked to perform as an Active Directory domain administrator is to assign a user the same set of permissions as an existing user. This is something you can do fairly easily in the GUI (Active Directory Users and Computers, dsa.msc) when you’re first creating the user, but which is a pain if the target user already exists. Turns out PowerShell can help with this, of course.

First, you need to get the list of groups that the template or source user ($TemplateUser) is a member of. That’s fairly simple:

$UserGroups =@()
$UserGroups = (Get-ADUser -Identity $TemplateUser -Properties MemberOf).MemberOf

A couple of important points in the above:

• First, you should create the empty array first. That tells PowerShell that you’re going to be creating a list of groups, not a single one. You can often get away without doing this at the command line because of PowerShell’s command line magic, but in a script, you need to be explicit.
• Second, you need to include the MemberOf property in the Get-ADUser query. By default, that isn’t returned and you’ll end up with an empty $UserGroups variable.

So, you’ve got a list of groups. If you’re just doing an “additive” group membership change, all you need to do is add the target user ($TargetUser) to the all the groups. However, if you want to exactly match the group memberships, you need to first remove the target user from any groups s/he is part of before adding groups back. To do that, we need to first find out what groups the target user is currently in with much the same command as above:

$CurrentGroups = @()
$CurrentGroups = (Get-ADUser -Identity $TargetUser -Properties MemberOf).MemberOf

Now, we can remove the user from all current groups with:

foreach ($Group in $CurrentGroups) {
    Remove-ADGroupMember -Identity $Group -Members $TargetUser
}

Notice in the above that -Identity is the identity of the group, not the user. This is because we’re acting on the groups, not acting on the user(s).

Finally, we can now add $TargetUser back in to the groups that $TemplateUser had with:

foreach ($Group in $UserGroups) {
    Add-ADGroupMember -Identity $Group -Members $TargetUser
}

All of this, of course, happens quietly with no confirmation. So, just to verify that everything went as expected, use:

(Get-ADUser -Identity $TargetUser -Properties MemberOf).MemberOf

And you should get back a list of user groups the target user is now a member of.

Note: If you’re including this code in a new user script, you won’t need to remove the user from current groups, merely add them to the same groups as the template user.

Deploying a DHCP Server

Now that you have your forest and domain installed, including DNS, the next step to setting up a lab is the DHCP server.  Start by creating a new VM for the DHCP server, trey-dhcp-03. (For details on how to create a VM with PowerShell, see Building a Lab in Hyper-V Part 2 and Part 3. ) There’s no particular need to make this a GUI installation, so build it as a Server Core installation. We’ll do the configuration all in PowerShell anyway.

Next, Install the DHCP role, add the local groups required, and authorize it in Active Directory. (Do note the slightly different server name when you go to do that, please, and you don’t need or want to promote this server to a domain controller. )

Now, as you’ll remember from earlier posts in this series, I configure all my VMs with known MAC addresses by first defining the range and then requiring a MAC address final pair parameter to New-myVM.ps1. This allows me to now configure a set of reservations for each VM in the lab, simplifying connections and making it a lot easier for me to keep track what is where.

Assuming by now you have installed the DHCP role and authorized it in Active Directory, the next step is to set up your IPv4 and IPv6 ranges. We do that by first adding a scope, then setting exclusion ranges and finally scope options. For IPv4, this is three commands:

Add-DhcpServerv4Scope -Name "Trey-Default" `
                      -ComputerName "trey-dhcp-03" `
                      -Description "Default IPv4 Scope for Lab" `
                      -StartRange "192.168.10.1" `
                      -EndRange   "192.168.10.220" `
                      -SubNetMask "255.255.255.0" `
                      -State Active `
                      -Type DHCP `
                      -PassThru

Add-DhcpServerv4ExclusionRange -ScopeID "192.168.10.0" `
                               -ComputerName "trey-dhcp-03" `
                               -StartRange "192.168.10.1" `
                               -EndRange   "192.168.10.20" `
                               -PassThru

Set-DhcpServerv4OptionValue -ScopeID 192.168.10.0 `
                            -ComputerName "trey-dhcp-03" `
                            -DnsDomain "TreyResearch.net" `
                            -DnsServer "192.168.10.2" `
                            -Router "192.168.10.1" `
                            -PassThru

Now,  the same process for IPv6, though I usually do NOT create IPv6 reservations, but do want to set some default values.

Add-DhcpServerv6Scope -Name "Trey-IPv6-Default" `
                      -ComputerName "trey-dhcp-03" `
                      -Description "Default IPv6 Scope for Lab" `
                      -Prefix 2001:db8:0:10:: `
                      -State Active `
                      -PassThru

Add-DhcpServerv6ExclusionRange –ComputerName trey-dhcp-03 `
                               -Prefix 2001:db8:0:10:: `
                               -StartRange 2001:db8:0:10::1 `
                               -EndRange   2001:db8:0:10::20 `
                               -PassThru

Set-DhcpServerv6OptionValue -Prefix 2001:db8:0:10:: `
                            -ComputerName "trey-dhcp-03" `
                            -DnsServer 2001:db8:0:10::2 `
                            -DomainSearchList "TreyResearch.net" `
                            -PassThru

Now, create a CSV file with Names,MAC addresses(ClientID), and IPv4 Addresses. You can use your favourite plain text editor (mine is gVim), or Excel to create the CSV file. My lab has the following for the 192.168.10.xxx range of IP addresses:

Name,ClientID,IPAddress
trey-edge-01,00-15-5D-32-0A-01,192.168.10.1
trey-dc-02,00-15-5D-32-0A-02,192.168.10.2
trey-dhcp-03,00-15-5D-32-0A-03,192.168.10.3
trey-dc-04,00-15-5D-32-0A-04,192.168.10.4
trey-srv-05,00-15-5D-32-0A-05,192.168.10.5
trey-wds-11,00-15-5D-32-0A-0B,192.168.10.11
Trey-Srv-12,00-15-5D-32-0A-0C,192.168.10.12
Trey-Srv-13,00-15-5D-32-0A-0D,192.168.10.13
Trey-Srv-14,00-15-5D-32-0A-0E,192.168.10.14
Trey-Srv-15,00-15-5D-32-0A-0F,192.168.10.15
Trey-Srv-16,00-15-5D-32-0A-10,192.168.10.16
Trey-client-21,00-15-5D-32-0A-15,192.168.10.21
Trey-client-22,00-15-5D-32-0A-16,192.168.10.22
Trey-client-23,00-15-5D-32-0A-17,192.168.10.23
Trey-client-24,00-15-5D-32-0A-18,192.168.10.24
Trey-client-25,00-15-5D-32-0A-19,192.168.10.25

Save the CSV file as “TreyDHCP.csv”. Now, to create the reservations, first read in the CSV file with:

$TreyDHCP = Import-CSV TreyDHCP.csv

Then, create the IPv4 reservations with a simple ForEach loop:

ForEach ($addr in $TreyDHCP ) {
   $ErrorActionPreference = "Continue"
   Add-DhcpServerv4Reservation -ScopeID   192.168.10.0 `
                               -Name      $addr.Name `
                               -ClientID  $addr.ClientID `
                               -IPAddress $addr.IPAddress `
                               -PassThru
}

If you run multiple NICs on your lab environment, you’ll want to repeat all of the above for the second range of IP addresses.

So, here’s the whole thing in a script that supports running remotely.

<#
.Synopsis
Install and configure DHCP for the TreyResearch.net lab environment
.Description
The New-TreyDHCP script installs and configures the DHCP environment for the TreyResearch.net
lab environment. It assumes a DHCP server "trey-dhcp-03" has already been created, but accepts
a parameter to change the server name. 
The script reads a CSV file with the machine names, MAC addresses (ClientIDs), and IPv4
addresses that the that the network will use and then creates IPv4 DHCP reservations for those
machines.
.Example
New-TreyDHCP.ps1
Reads in a list of DHCP addresses from TreyDHCP.csv and configures trey-dhcp-03 as a DHCP
server with those addresses. 
.Example
New-TreyDHCP.ps1 -ComputerName Trey-core-03 -Path c:\temp\dhcp.csv
Reads in a list of DHCP addresses from c:\temp\dhcp.csv and configures the server
Trey-core-03 as a DHCP server with those address reservations. 
.Parameter ComputerName
The server to install and configure DHCP on. Default value is trey-dhcp-03
.Parameter Path
The path to a CSV file with the machine names, client IDs, and IPv4 addresses to configure
DHCP reservations for. The default value is .\TreyDHCP.csv. 
.Inputs
[string]
[string]
.Notes
    Author: Charlie Russel
 Copyright: 2017 by Charlie Russel
          : Permission to use is granted but attribution is appreciated
   Initial: 25 March, 2014 (cpr)
   ModHist: 14 March, 2017 (cpr) Added ComputerName parameter and man page
          : 
#>
[CmdletBinding()]
Param(
     [Parameter(Mandatory=$False)]
     [alias("server")]
     [string]
     $ComputerName = 'trey-dhcp-03',
     [Parameter(Mandatory=$False)]
     [Alias("filename")]
     [string]
     $Path = '.\TreyDHCP.csv'
     )

if ( (Get-WindowsFeature -Name DHCP -ComputerName $ComputerName) -ne "Installed" ) {
  Install-WindowsFeature -Name DHCP -ComputerName $ComputerName -IncludeManagementTools 
}

if (Test-Path $Path ) { 
   $TreyDHCP = Import-CSV $Path 
} else {
   Throw "This script requires an input CSV file with the DHCP Reservations in it."
}

# Find out if the DHCP Server is already authorized. If it is, 
# we assume all the rest of this is done. 
If ( (Get-DhcpServerInDC).DnsName -match $ComputerName ) {
   $IsAuth = $True 
} else {
   $IsAuth = $False 
   $DnsName = $ComputerName + ".TreyResearch.net"
}

# If the server isn't authorized, then nothing is set yet, so set up 
# our DHCP server. 
if (! $IsAuth) {
   Add-DhcpServerInDC -DnsName $DnsName -PassThru
   # Create local groups for DHCP
   # The WinNT in the following IS CASE SENSITIVE
   $connection = [ADSI]"WinNT://$ComputerName"
   $lGroup = $connection.Create("Group","DHCP Administrators")
   $lGroup.SetInfo()
   $lGroup = $connection.Create("Group","DHCP Users")
   $lGroup.SetInfo()
   Add-DhcpServerv4Scope -Name "Trey-Default" `
                         -Description "Default IPv4 Scope for TreyResearch Lab" `
                         -StartRange "192.168.10.1" `
                         -EndRange   "192.168.10.220" `
                         -SubNetMask "255.255.255.0" `
                         -State Active `
                         -Type DHCP `
                         -ComputerName $ComputerName `
                         -PassThru
   Add-DhcpServerv4ExclusionRange -ScopeID "192.168.10.0" `
                                  -StartRange "192.168.10.1" `
                                  -EndRange   "192.168.10.20" `
                                  -ComputerName $ComputerName `
                                  -PassThru
   Set-DhcpServerv4OptionValue -ScopeID 192.168.10.0 `
                               -DnsDomain "TreyResearch.net" `
                               -DnsServer "192.168.10.2" `
                               -Router "192.168.10.1" `
                               -ComputerName $ComputerName `
                               -PassThru
   Add-DhcpServerv6Scope -Name "Trey-IPv6-Default" `
                         -Description "Default IPv6 Scope for TreyResearch Lab" `
                         -Prefix 2001:db8:0:10:: `
                         -State Active `
                         -ComputerName $ComputerName `
                         -PassThru
   Add-DhcpServerv6ExclusionRange -Prefix 2001:db8:0:10:: `
                                  -StartRange 2001:db8:0:10::1 `
                                  -EndRange   2001:db8:0:10::20 `
                                  -ComputerName $ComputerName `
                                  -PassThru
   Set-DhcpServerv6OptionValue -Prefix 2001:db8:0:10:: `
                               -DnsServer 2001:db8:0:10::2 `
                               -DomainSearchList "TreyResearch.net" `
                               -ComputerName $ComputerName `
                               -PassThru
}


ForEach ($addr in $TreyDHCP ) {
   $ErrorActionPreference = "Continue"
   Add-DhcpServerv4Reservation -ScopeID 192.168.10.0 `
                               -Name $addr.Name `
                               -ClientID $addr.ClientID `
                               -IPAddress $addr.IPAddress `
                               -ComputerName $ComputerName `
                               -PassThru
}

I hope you find this script useful, and I’d love to hear comments, suggestions for improvements, or bug reports as appropriate. As always, if you use this script as the basis for your own work, please respect my copyright and provide appropriate attribution.

This came up at work the other day. Another admin had attempted to rename an AD User account and it had only partially gotten renamed — the SAM Account, Name and Display name were all correct, but the old user name was still showing up in a couple of places, including the login screen. The user was not happy, so I was asked to fix it, and provide a script that would handle it correctly. I poked around a bit and found the issue – even if you set all of the obvious properties correctly (and the other admin had missed UPN), it still won’t show correctly on that logon screen — you need to actually rename the AD object itself. So, after I fixed the problem user’s account, I wrote up a script to solve the problem for the next time. I chose to use a CSV file as the input, but you could easily re-work this to work off either a CSV file or a set of command-line parameters. But honestly, I don’t ever want to have to enter that many command-line parameters for a simple script. Especially if I have more than one to change.

The script uses Get-ADUser with the old name, then pipes it to Set-ADUser, and finally pipes it to Rename-ADObject to finish the process.  I even gave it basic help. :)

<#
.Synopsis
Renames the Active Directory users
.Description
Rename-myADUser reads a CSV file to identify an array of users. The users are then 
renamed to the new name in Active Directory.
.Example
Rename-myADUser
Renames the AD Accounts of the users in the default "ADUsers.csv" source file
.Example
Rename-myADUser -Path "C:\temp\ChangedUsers.txt"
Renames the AD accounts of the users listed in the file C:\temp\ChangedUsers.txt"
.Parameter Path
The path to the input CSV file of format:
OldSam,NewName,GivenName,Surname,DisplayName,SAMAccountName,UserPrincipalName,EmailAddress

The default value is ".\ADUsers.csv".  
.Inputs
[string]
.Notes
    Author: Charlie Russel
 Copyright: 2017 by Charlie Russel
          : Permission to use is granted but attribution is appreciated
   Initial: 03/09/2017 (cpr)
   ModHist: 
          :
#>
[CmdletBinding()]
Param(
     [Parameter(Mandatory=$False,Position=0)]
     [string]
     $Path = ".\ADUsers.csv" 
     )

$ADUsers = @()
If (Test-Path $Path ) {
   $ADUsers = Import-CSV $Path
} else { 
   Throw  "This script requires a CSV file with user names and properties."
}
$PDC = (Get-ADDomain).PDCEmulator
Write-Verbose "The PDC Emulator has been identified as $PDC"
Write-Verbose " "

ForEach ($User in $ADUsers ) {
   Write-Verbose "Modifying $user.OldSam to $user.NewName" 
   Sleep 3
   Get-ADUser -Identity $User.OldSam -Properties * | `
   Set-ADUser -Server $PDC `
              -DisplayName $user.DisplayName `
              -EmailAddress $User.EmailAddress `
              -SamAccountName $User.SamAccountName `
              -GivenName $User.GivenName `
              -Surname $User.Surname `
              -UserPrincipalName $user.UserPrincipalName `
              -PassThru | `
   Rename-ADObject -NewName $user.NewName -Server $PDC -PassThru
}

Creating a new forest

In the previous sections of this series, I’ve covered how to build VMs using PowerShell, but labs aren’t much good if they don’t actually have any structure. So, let’s create a new forest and domain to manage our labs. I’m going to assume for this post that you’ve gotten started already and created a new Windows Server 2012R2 or Windows Server 2016 virtual machine. For this, it can be a graphical install or a Server Core installation and either Server Standard or Datacenter. Since we’re going to be using only PowerShell to create the forest, there’s no need for a GUI.

The things we’ll need to have identified before we start are:

• Server IP address
• Server name
• DNS namespace for the root domain of the forest
• Domain name for the root domain of the forest
• DNS Server type (AD-integrated or standalone)

Set Server IP Address

We need set our server to a fixed IP address. While not absolutely required, I think it’s a really bad idea to not do this. And, since our lab doesn’t yet have DHCP in it, you need to anyway. (We’ll add a DHCP server in the next installment. )

To configure the network adapter for a static IP address, I need to know either the interface alias (name) or the interface index. To get those, use Get-NetAdapter from a PowerShell window. (Note: if you’re doing this on a new Windows Server Core installation, you can open a PowerShell window with Start PowerShell.exe at the command prompt. To start a PowerShell window automatically for this user, at logon, see my May post. )

Get-NetAdapter | Format-Table -AutoSize Name,Status,IFIndex,MacAddress

Name       Status ifIndex MacAddress
----       ------ ------- ----------
Ethernet 2 Up           3 00-15-5D-32-0A-02
Ethernet   Up           5 00-15-5D-32-CE-02

Which tells us that the DC has two network adapters, and the one that is on the Local-10 switch (from New-myVM.ps1) is at an ifIndex of 3, while the one on the “199 Network” switch has an ifIndex of 5. Now, we’ll set the static IP addresses for these two adapters. First, the NIC on Local-10:

# Set IPv4
$NIC2 = Get-NetAdapter -ifIndex 3
$NIC2 | Set-NetIPInterface -DHCP Disabled
$NIC2 | New-NetIPAddress -AddressFamily  IPv4 `
                         -IPAddress      192.168.10.2 `
                         -PrefixLength   24 `
                         -Type Unicast `
                         -DefaultGateway 192.168.10.1
# Set IPv6
$NIC2 | New-NetIPAddress -AddressFamily  IPv6 `
                         -IPAddress      2001:db8:0:10::2 `
                         -PrefixLength   64 `
                         -Type Unicast `
                         -DefaultGateway 2001:db8:0:10::1

# Set DNS Server Addresses to self
Set-DnsClientServerAddress -InterfaceIndex  $NIC2.ifIndex `
                           -ServerAddresses 192.168.10.2,2001:db8:0:10::2

#Now, for the 199 Network, which I use for internal communications between lab hosts, I want to set a pure IPv4 address with no IPv6, so instead of setting an IPv6 address for the NIC, I’ll disable it with Disable-NetAdapterBinding.

$NIC = Get-NetAdapter -ifIndex 5

# Disable IPv6
Disable-NetAdapterBinding -Name $NIC.Name -ComponentID ms_tcpip6

# Set IPv4 to 192.168.199.2
$NIC | Set-NetIPInterface -Dhcp Disabled
$NIC | New-NetIPAddress -AddressFamily IPv4 `
                        -IPAddress     192.168.199.2 `
                        -PrefixLength  24 `
                        -Type Unicast
# Set DNS to self
Set-DnsClientServerAddress -InterfaceIndex  $NIC.ifIndex `
                           -ServerAddresses 192.168.199.2

(Note: Set-NetAdapterBinding is not available on Windows 7/Server 2008 R2)

Set Server Name

Next, let’s set the name of the server to match our naming conventions for this lab. We do this now, knowing it will force a reboot before we go any further.

Rename-Computer -NewName trey-dc-02 -Restart -Force

This will give the computer a new name and restart it.

Create Forest and Install AD-integrated DNS

Now that we have static IP addresses for our network adapters, and we’ve set the name of the server, we can go ahead and create our AD forest. First, we install Active Directory and update the PowerShell Help files with:

Install-WindowsFeature -Name AD-Domain-Services -IncludeManagementTools
Update-Help -SourcePath \\labhost\PSHelp

This installs the ActiveDirectory and ADDSDeployment modules that we’ll need to create the forest. Now, we promote the server to be the first domain controller in the new forest. Before we do the actual install, we test to make sure we don’t have any issues with Test-ADDSForestInstallation:

Test-ADDSForestInstallation `
         -DomainName 'TreyResearch.net' `
         -DomainNetBiosName 'TREYRESEARCH' `
         -DomainMode 6 `
         -ForestMode 6 `
         -NoDnsOnNetwork `
         -SafeModeAdministratorPassword (ConvertTo-SecureString `
                                                  -String 'P@ssw0rd' `
                                                  -AsPlainText `
                                                  -Force) `
         -NoRebootOnCompletion

Even though this is a brand new forest in an isolated lab setting, it’s still a good practice to test before you actually deploy. And it doesn’t cost all that much time or annoyance. I’ve included the SafeModeAdministratorPassword parameter to avoid the prompts for it. This is a lab, not real life. :) Also note that we’re setting the forest and domain modes to Server2012R2. If you need earlier versions of domain controllers in your lab, you can set the mode accordingly.

The results of the test are as expected:

WARNING: Windows Server 2016 domain controllers have a default for the security setting named "Allow cryptography
algorithms compatible with Windows NT 4.0" that prevents weaker cryptography algorithms when establishing security
channel sessions.

For more information about this setting, see Knowledge Base article 942564
(http://go.microsoft.com/fwlink/?LinkId=104751).

WARNING: A delegation for this DNS server cannot be created because the authoritative parent zone cannot be found or it
 does not run Windows DNS server. If you are integrating with an existing DNS infrastructure, you should manually
create a delegation to this DNS server in the parent zone to ensure reliable name resolution from outside the domain
"TreyResearch.net". Otherwise, no action is required.


Message                          Context                                  RebootRequired  Status
-------                          -------                                  --------------  ------
Operation completed successfully Test.VerifyDcPromoCore.DCPromo.General.3          False Success

With that confirmation, we can go ahead and finish creating the forest and configuring DNS with the command:

Install-ADDSForest `
    -DomainName 'TreyResearch.net' `
    -DomainNetBiosName 'TREYRESEARCH' `
    -DomainMode 6 `
    -ForestMode 6 `
    -NoDnsOnNetwork `
    -SkipPreChecks `
    -SafeModeAdministratorPassword (ConvertTo-SecureString `
                                                  -String 'P@ssw0rd' `
                                                  -AsPlainText `
                                                  -Force) `
    -Force

You’ll notice that the options here match our test pass, except I chose to bypass a second test. If you want to keep your SafeMode Administrator password private you can eliminate that parameter and you’ll be prompted at the command line. When this finishes and the server has rebooted, you can log in with the TREYRESEARCH\Administrator account and the local Administrator password you had before you promoted the VM to be a domain controller.  This may or may not be the same as the SafeModeAdministratorPassword you set during the installation.

As I mentioned last time, I’m setting up a new domain controller and DHCP server for my internal domain on Windows Server 2016 Core, and I’m exclusively using PowerShell to do it. For both the DHCP Server and AD DS roles, we need to configure a fixed IP address on the server, so let’s do that first. From my Deploying and Managing Active Directory with Windows PowerShell book from Microsoft Press, here’s my little very quick and dirty script to set a fixed IP address:

# Quick and dirty IP address setter

[CmdletBinding()]
Param ([Parameter(Mandatory=$True)][string]$IP4,
       [Parameter(Mandatory=$True)][string]$IP6 
      )
$Network = "192.168.10."
$Network6 = "2001:db8:0:10::"
$IPv4 = $Network + "$IP4"
$IPv6 = $Network6 + "$IP6"
$Gateway4 = $Network + "1"
$Gateway6 = $Network6 + "1"

Write-Verbose "$network,$network6,$IP4,$IP6,$IPv4,$IPv6,$gateway4, $gateway6"

$Nic = Get-NetAdapter -name Ethernet
$Nic | Set-NetIPInterface -DHCP Disabled
$Nic | New-NetIPAddress -AddressFamily IPv4 `
                        -IPAddress $IPv4 `
                        -PrefixLength 24 `
                        -type Unicast `
                        -DefaultGateway $Gateway4
Set-DnsClientServerAddress -InterfaceAlias $Nic.Name `
                           -ServerAddresses 192.168.10.2,2001:db8:0:10::2
$Nic |  New-NetIPAddress -AddressFamily IPv6 `
                         -IPAddress $IPv6 `
                         -PrefixLength 64 `
                         -type Unicast `
                          -DefaultGateway $Gateway6

ipconfig /all

I warned you it was a quick and dirty script. But let’s quickly look at what it does. First, we get the network adapter into a variable, $Nic. Then we turn off DHCP with Set-NetIPInterface, and configure the IPv4 and IPv6 addresses with New-NetIPAddress. Finally, we use Set-DnsClientServerAddress to configure the DNS Servers for this server.

Next, let’s join the server to the TreyResearch.net domain with another little script. OK, I admit, you could do this all as a simple one-liner, but I do it so often that I scripted it.

<#
.Synopsis
Joins a computer to the domain
.Description
Joins a new computer to the domain. If the computer hasn't been renamed yet, 
it renames it as well.
.Parameter NewName
The new name of the computer
.Parameter Domain
The domain to join the computer to. Default value is TreyResearch.net
.Example
Join-myDomain -NewName trey-wds-11
.Example
Join-myDomain dc-contoso-04 -Domain Contoso.com
.Notes
     Name: Join-myDomain
   Author: Charlie Russel
Copyright: 2017 by Charlie Russel
         : Permission to use is granted but attribution is appreciated
  ModHist:  9 Apr, 2014 -- Initial
         : 25 Feb, 2015 -- Updated to allow name already matches
         :
#>
[CmdletBinding()]
Param ( [Parameter(Mandatory=$true,Position=0)]
        [String]$NewName,
        [Parameter(Mandatory=$false,Position=1)]
        [String]$Domain = "TreyResearch.net"
       )

$myCred = Get-Credential -UserName "$Domain\Charlie" `
                         -Message "Enter the Domain password for Charlie."

if ($ENV:COMPUTERNAME -ne $NewName ) {
   Add-Computer -DomainName $Domain -Credential $myCred -NewName $NewName -restart
} else {
   Add-Computer -DomainName $Domain -Credential $myCred -Restart
}

After the server restarts, log in with your domain credentials, not as “Administrator”.  The account you logon with should be at least Domain Admin or equivalent, since you’re going to be adding DHCP to the server and promoting it to be a domain controller.

To add the necessary roles to the server, use:

Install-WindowsFeature -Name DHCP,AD-Domain-Services `
                       -IncludeAllSubFeature `
                       -IncludeManagementTools

Next, download updated Get-Help files with Update-Help. Once you’ve got those, go ahead and restart the server, and when it comes back up, we’ll do the base configuration for DHCP to enable it in the domain, and create the necessary accounts. Creating scopes, etc., is the topic of another day. Probably as part of my Lab series.

First, enable the DHCP server in AD (this assumes the $NewName from earlier was ‘trey-core-03’. )

Add-DhcpServerInDC -DnsName 'trey-core-03' -PassThru

And, finally, create the necessary local groups:

# Create local groups for DHCP
# The WinNT in the following IS CASE SENSITIVE
$connection = [ADSI]"WinNT://trey-core-03"
$lGroup = $connection.Create("Group","DHCP Administrators")
$lGroup.SetInfo()
$lGroup = $connection.Create("Group","DHCP Users")
$lGroup.SetInfo()

This uses ADSI to create a local group, since there’s no good way built into base PowerShell to do it except through ADSI.

Finally, we’ll use my Promote-myDC.ps1 script to promote the server to domain controller. Again, I could easily do this by hand, but I’m building and rebuilding labs often enough that I scripted it. I’m lazy! Do it once, use the PowerShell interactive command line. Do it twice? Write a script!

<#
.Synopsis
Tests a candidate domain controller, and then promotes it to DC.
.Description
Promote-myDC first tests if a domain controller can be successfully promoted,
and, if the user confirms that the test was successful, completes the
promotion and restarts the new domain controller.
.Example
Promote-myDC -Domain TreyResearch.net

Tests if the local server can be promoted to domain controller for the
domain TreyResearch.net. The user is prompted after the test completes
and must press the Y key to continue the promotion.
.Parameter Domain
The domain to which the server will be promoted to domain controller.
.Inputs
[string]
.Notes
    Author: Charlie Russel
 Copyright: 2017 by Charlie Russel
          : Permission to use is granted but attribution is appreciated
   Initial: 05/14/2016 (cpr)
   ModHist: 02/14/2017 (cpr) Default the domain name for standard lab builds
          :
#>
[CmdletBinding()]
Param(
     [Parameter(Mandatory=$False,Position=0)]
     [string]$Domain = 'TreyResearch.net'
     )

Write-Verbose "Testing if ADDSDeployment module is available"
If ( (Get-WindowsFeature -Name AD-Domain-Services).InstallState -ne "Installed" ) {
   Write-Verbose "Installing the ActiveDirectory Windows Feature, since you seem to have forgotten that."
   Install-WindowsFeature -Name AD-Domain-Services -IncludeManagementTools
   Write-Host ""
}

If ( (Get-WindowsFeature -Name AD-Domain-Services).InstallState -ne "Installed" ) {
   throw "Failed to install the ActiveDirectory Windows Feature."
}

Write-Verbose "Testing if server $env:computername can be promoted to DC in the $Domain domain"
Write-Host ""
Test-ADDSDomainControllerInstallation `
         -NoGlobalCatalog:$false `
         -CreateDnsDelegation:$false `
         -CriticalReplicationOnly:$false `
         -DatabasePath "C:\Windows\NTDS" `
         -DomainName $Domain `
         -LogPath "C:\Windows\NTDS" `
         -NoRebootOnCompletion:$false `
         -SiteName "Default-First-Site-Name" `
         -SysvolPath "C:\Windows\SYSVOL" `
         -InstallDns:$true `
         -Force
Write-Host ""
Write-Host ""
Write-Host ""

Write-Host -NoNewLine "If the above looks correct, press Y to continue...  "
$Key = [console]::ReadKey($true)
$sKey = $key.key

Write-Verbose "The $sKey key was pressed."
Write-Host ""
Write-Host ""
If ( $sKey -eq "Y" ) {
   Write-Host "The $sKey key was pressed, so proceeding with promotion of $env:computername to domain controller."
   Write-Host ""
   sleep 5
   Install-ADDSDomainController `
              -SkipPreChecks `
              -NoGlobalCatalog:$false `
              -CreateDnsDelegation:$false `
              -CriticalReplicationOnly:$false `
              -DatabasePath "C:\Windows\NTDS" `
              -DomainName $Domain `
              -InstallDns:$true `
              -LogPath "C:\Windows\NTDS" `
              -NoRebootOnCompletion:$false `
              -SiteName "Default-First-Site-Name" `
              -SysvolPath "C:\Windows\SYSVOL" `
              -Force:$true
} else {
   Write-Host "The $sKey key was pressed, exiting to allow you to fix the problem."
   Write-Host ""
   Write-Host ""
}

This uses a little trick I haven’t talked about before –

$Key = [console]::ReadKey($true)
$sKey = $key.key

This reads in a single keystroke and gets the value of the key. Because of the way this works, “Y” and “y” are equivalent. Useful to give yourself a last chance out if something doesn’t look right, though obviously you’ll want to remove those bits if you’re creating a script that needs to run without interactive input.

In Part 1 of this series, I showed you how to identify users whose password was about to expire. Then in Part 2 of the series, I took that list of users and sent email to them using gmail-hosted company email. This third part of the series pulls all that together into a single script, complete with comment-based help. As always, this and all my scripts are copyrighted, but you’re welcome to use them as the basis for your own scripts. However, I do appreciate attribution. Thanks, and enjoy.

<#
.Synopsis
Sends a "Password Expiring" warning email through TreyResearch's gmail. 
.Description
Send-TreyPasswordExpiryNotice first creates a list of accounts whose password will expire in the 
near future (default is 1 week). It then emails the users to warn them that their password will expire soon. 

This initial version runs interactively only. 
.Example
Send-TreyPasswordExpiryNotice
Sends a warning notice to all TreyResearch users whose password will expire in the next 7 days or less.
.Example
Send-TreyPasswordExpiryNotice -Logging
Sends a warning notice to all TreyResearch users whose password will expire in the next 7 days or less, and 
creates a log file that is echoed to the console at the end. 
.Example
Send-TreyPasswordExpiryNotice -DaysWarning 14
Sends a warning notice to all TreyResearch users whose password will expire in the next 14 days or less.
.Example
Send-TreyPasswordExpiryNotice -DaysWarning 5 -Logging -Testing -Verbose
Does NOT send a warning notice to TreyResearch users, but rather processes the first user and sends a notice
to the admin user(s) and writes to the log file. The -Verbose switch will make it additionally chatty.
.Parameter DaysWarning
The number of days advanced warning to give users whose passwords are close to expiration. 
The default is 7 days or less. 
.Parameter Logging
Switch to enable logging. Logs are written to C:\Temp\emaillogs.csv. When this switch is true, 
Send-TreyPasswordExpiryNotice outputs a table with a list of accounts due to expire as well as 
writing to a log file. 
.Parameter Testing
Switch to enable testing. When enabled, email is sent to a list of Admin users and only a single account is processed. 
.Inputs
[int]
[switch]
[Switch]
.Notes
    Author: Charlie Russel
  ThanksTo: Robert Pearman (WSSMB MVP),Jeffrey Hicks (PS MVP)
 Copyright: 2016 by Charlie Russel
          : Permission to use is granted but attribution is appreciated
   Initial: 06 Sept, 2016 (cpr)
          : 09 Dec,  2016 (cpr) -(Ver 1.5) -- Reworked: Only process users who need reminding. Formatting changes
#>
[CmdletBinding()]
Param(
     [Parameter(Mandatory=$False,Position=0)]
     [int]
     $DaysWarning = 7, 
     [parameter(Mandatory=$false)]
     [Switch]
     $Logging,
     [parameter(Mandatory=$false)]
     [switch]
     $Testing
     )


#Set parameters for gmail.
$smtpServer  ="smtp.gmail.com"
$SMTPPort    = 587
$from        = "IT Notification <it-notification@TreyResearch.net>"
$AdminUser1  = "Charlie.Russel@TreyResearch.net"
$AdminUser2  = "admin.user2@TreyResearch.net"
$AdminUser3  = "admin.user3@TreyResearch.net"
$externalUser= "external.account@example.com"

# Cast this to a list of strings to allow for multiple test recipients
[string[]]$testRecipient = $AdminUser1,$AdminUser2,$AdminUser3

<#
 This uses a stored password sitting on a local hard drive. This is a reasonably
 secure way to work with passwords in a file, and is ONLY accessible by the user that created 
 it. Create the password with: 
   
   PSH> Read-Host -AsSecureString | ConvertFrom-SecureString | Out-File $home\Documents\TreyPW.txt

 See blog post at: http://blogs.msmvps.com/russel/2016/10/04/powershell-get-credential-from-a-file for
 full details. 

 Alternately, simply prompt for the credentials here with Get-Credential.

#>

$TreyUsr = "charlie.russel@TreyResearch.net"
$TreyPW = Get-Content $Home\Documents\TreyPW.txt | ConvertTo-SecureString
$Cred = New-Object System.Management.Automation.PSCredential -ArgumentList $TreyUsr, $TreyPW

 
# Check Logging Settings 
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" 
} 

# System Settings 
$textEncoding = [System.Text.Encoding]::UTF8 
$date = Get-Date -format "MM/dd/yyyy"

# Explicitly import the Active Directory module, but get rid of the noise if it's already loaded. 
Import-Module ActiveDirectory 4>$NULL


# Use the following to query the domain for who the PDC Emulator role holder is. 
$TreyDC = (Get-ADDomain -Identity "TreyResearch.net" -Credential $Cred).PDCEmulator

# Send a cc: to myself or a list of users
$AdminUser = "charlie.russel@TreyResearch.net"
$cclist = @($AdminUser)

# Do calculations outside the ForEach loop whenever possible
$maxPasswordAge = (Get-ADDefaultDomainPasswordPolicy -Server $TreyDC -Credential $Cred).MaxPasswordAge
$today = (get-date) 

# Notice this doesn't get Expired or NeverExpires users. Don't want to send them emails.  
$TreyUsers = Get-ADUser -filter * `
                    -properties Name,PasswordNeverExpires,PasswordExpired,PasswordLastSet,EmailAddress `
                    -Server $TreyDC `
                    -Credential $Cred `
         | where { $_.Enabled -eq $True `
             -AND  $_.PasswordNeverExpires -eq $False `
             -AND  $_.passwordexpired -eq $False `
             -AND  $_.EMailAddress `
             -AND  (($today - $_.PasswordLastSet).Days -ge ($MaxPasswordAge.Days - $DaysWarning))
         }
<# Get notification credentials. Prompt with Get-Credential if not using stored creds. 
$gCred = Get-Credential -UserName "it-notification@TreyResearch.net" `
                        -Message  "Enter Password for IT-Notification account"
#>
$gUsr = "it-notification@TreyResearch.net"
$gPW = Get-Content "$Home\Documents\itnotificationsPW.txt" | ConvertTo-SecureString
$gCred = New-Object System.Management.Automation.PSCredential -ArgumentList $gUsr, $gPW

# Now, we start to do the work. 
foreach ($user in $TreyUsers) { 
    Write-Verbose "Processing user $user"
    $Name = $user.Name 
    $Email = $user.emailaddress 
    $SAM = $user.SAMAccountName
    $sent = " " 
    $passwordSetDate = $user.PasswordLastSet 
    Write-Verbose "$SAM last set their password on $PasswordSetDate"

    $expiresOn = $passwordSetDate + $maxPasswordAge 
    $DaysLeft = (New-TimeSpan -Start $today -End $Expireson).Days 
 
    if (($DaysLeft) -gt "1") { 
        $MessageDays = "in " + "$DaysLeft" + " days." 
    } else { 
        $MessageDays = "today!" 
    } 
 
    # Email Subject Set Here 
    $subject="Your password will expire $messageDays" 
    Write-Verbose "$Name`'s password will expire $messageDays"
   
    # Email Body Set Here, Note You can use HTML, including Images. 
    # This uses PowerShell's here-string. 
$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 your 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>
"@

    # If Testing Is Enabled - Email Administrator 
    if ($testing) { 
        $email = $testRecipient 
        $Subject = "PasswordExpiration Test Message"
        $cclist = $AdminUser2,$externalUser
    } 

   # Send Email Message 
    Write-Verbose "$SAM's password is due to expire in $DaysLeft which is less than the "
    Write-Verbose "DaysWarning Parameter setting of $DaysWarning days."

    # I've left this as a straight output to the host. If you want it quieter, make it a Write-Verbose
    "Sending Email Message to $email using $gUsr account"
    Send-Mailmessage -smtpServer $smtpServer `
                     -from $from `
                     -to $email `
                     -cc $cclist `
                     -subject $subject `
                     -body $body `
                     -bodyasHTML `
                     -priority High `
                     -Encoding $textEncoding `
                     -UseSSL `
                     -port $SMTPPort `
                     -Credential $gCred 
    $sent = "Yes"  # Used for logging
    if ($Logging) {
        Add-Content $logfile "$date,$Name,$email,$DaysLeft,$expiresOn,$Sent"  
    }
   if ($Testing) {
       "Sleeping 5, then breaking so we only process a single record"
       Sleep 5
       Break
    }
} 

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:"}
}

ETA: Minor bug fix (-Identity instead of -Identify. Sheesh!)

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.