Send-PasswordExpiryNotice.ps1

<#PSScriptInfo
.VERSION 1.0.0
.GUID 812bf0c4-3984-51c5-8807-a22c657a0dac
.AUTHOR Torsten Weise
.COMPANYNAME powerscripting.de
.COPYRIGHT (c) 2026 Torsten Weise. MIT-Lizenz.
.TAGS Powerscripting German ActiveDirectory AD Windows Fileserver PSEdition_Desktop PSEdition_Core
.LICENSEURI https://powerscripting.de/skripte/files/LICENSE.txt
.PROJECTURI https://powerscripting.de/skripte/send-passwordexpirynotice.html
.ICONURI https://powerscripting.de/assets/icon-192.png
.EXTERNALMODULEDEPENDENCIES ActiveDirectory
.REQUIREDSCRIPTS
.EXTERNALSCRIPTDEPENDENCIES
.RELEASENOTES
Erste Veröffentlichung in der PowerShell Gallery.
.PRIVATEDATA
#>


<#
.SYNOPSIS
    Erinnert AD-Benutzer per Mail daran, dass ihr Kennwort bald abläuft, standardmäßig 30 und 7 Tage vorher.
 
.DESCRIPTION
    Liest alle aktiven Benutzer mit Mailadresse, deren Kennwort abläuft, und berechnet das genaue Ablaufdatum.
    Dafür nutzt das Skript das Attribut msDS-UserPasswordExpiryTimeComputed, das auch abweichende
    Kennwortrichtlinien (Fine-Grained Password Policies) berücksichtigt.
 
    Liegt der Ablauf genau so viele Tage in der Zukunft wie in -DaysBefore angegeben, bekommt der Benutzer eine
    Mail mit Datum und einer kurzen Anleitung zum Ändern. Am Ende geht auf Wunsch eine Übersicht an die IT.
 
    Das Skript ist für den täglichen Lauf als geplante Aufgabe gedacht. Mit -TestRecipient gehen alle Mails
    an eine einzige Adresse, mit -WhatIf wird gar nichts verschickt.
 
.PARAMETER SearchBase
    Optional. Distinguished Name der OU, in der gesucht wird. Ohne Angabe: die ganze Domäne.
 
.PARAMETER DaysBefore
    Tage vor dem Ablauf, an denen erinnert wird. Standard: 30 und 7.
 
.PARAMETER SmtpServer
    Mailserver für den Versand.
 
.PARAMETER From
    Absender der Erinnerungen, zum Beispiel it-service@contoso.com.
 
.PARAMETER Port
    SMTP-Port. Standard: 25.
 
.PARAMETER UseSsl
    Verbindung zum Mailserver per TLS aufbauen.
 
.PARAMETER Credential
    Optional. Anmeldedaten für den Mailserver.
 
.PARAMETER ReportTo
    Optional. Empfänger einer Übersicht aller verschickten Erinnerungen.
 
.PARAMETER TestRecipient
    Optional. Schickt alle Erinnerungen an diese Adresse statt an die Benutzer. Zum Testen der Texte.
 
.PARAMETER LogPath
    Pfad der Protokolldatei. Standard: Send-PasswordExpiryNotice.log im aktuellen Ordner.
 
.EXAMPLE
    .\Send-PasswordExpiryNotice.ps1 -SmtpServer mail.contoso.local -From it-service@contoso.com -WhatIf
 
    Zeigt an, wer heute eine Erinnerung bekäme, ohne etwas zu verschicken.
 
.EXAMPLE
    .\Send-PasswordExpiryNotice.ps1 -SmtpServer mail.contoso.local -From it-service@contoso.com -TestRecipient admin@contoso.com
 
    Schickt alle heutigen Erinnerungen zur Kontrolle an die eigene Adresse.
 
.EXAMPLE
    .\Send-PasswordExpiryNotice.ps1 -SearchBase "OU=Benutzer,DC=contoso,DC=local" -DaysBefore 14, 3, 1 `
        -SmtpServer mail.contoso.local -From it-service@contoso.com -ReportTo it@contoso.com
 
    Erinnert 14, 3 und 1 Tag vorher und schickt der IT eine Übersicht.
 
.NOTES
    Autor: Torsten Weise, powerscripting.de
    Als geplante Aufgabe täglich einmal ausführen, zum Beispiel morgens um 7 Uhr, mit einem Dienstkonto,
    das Benutzer lesen und über den Mailserver senden darf.
    Send-MailMessage gilt als veraltet, funktioniert mit internen Mailservern aber weiterhin.
#>

[CmdletBinding(SupportsShouldProcess)]
param(
    [string] $SearchBase,
    [ValidateRange(1, 365)] [int[]] $DaysBefore = @(30, 7),
    [Parameter(Mandatory)] [string] $SmtpServer,
    [Parameter(Mandatory)] [string] $From,
    [int] $Port = 25,
    [switch] $UseSsl,
    [pscredential] $Credential,
    [string[]] $ReportTo,
    [string] $TestRecipient,
    [string] $LogPath = (Join-Path (Get-Location).Path 'Send-PasswordExpiryNotice.log')
)

Import-Module ActiveDirectory -ErrorAction Stop

$today = (Get-Date).Date
$mail  = @{ SmtpServer = $SmtpServer; From = $From; Port = $Port; Encoding = [System.Text.Encoding]::UTF8; BodyAsHtml = $true }
if ($UseSsl)     { $mail.UseSsl = $true }
if ($Credential) { $mail.Credential = $Credential }

function Write-NoticeLog([string] $Message) {
    $line = '{0:yyyy-MM-dd HH:mm:ss} {1}' -f (Get-Date), $Message
    Write-Verbose $line
    if (-not $WhatIfPreference) { Add-Content -Path $LogPath -Value $line -Encoding UTF8 }
}

function Get-NoticeBody($User, [datetime] $Expires, [int] $Days) {
    $dayText = if ($Days -eq 1) { 'morgen' } else { "in $Days Tagen" }
    @"
<div style="font-family:Segoe UI,Arial,sans-serif;font-size:14px;line-height:1.5;color:#222">
<p>Hallo $([System.Net.WebUtility]::HtmlEncode($User.GivenName)),</p>
<p>dein Kennwort für das Benutzerkonto <b>$($User.SamAccountName)</b> läuft <b>$dayText</b> ab,
am <b>$($Expires.ToString('dddd, dd.MM.yyyy', [Globalization.CultureInfo]'de-DE'))</b> um $($Expires.ToString('HH:mm')) Uhr.</p>
<p><b>So änderst du es am Windows-PC:</b></p>
<ol>
<li>Strg + Alt + Entf drücken.</li>
<li>„Kennwort ändern“ wählen.</li>
<li>Altes Kennwort einmal und das neue Kennwort zweimal eingeben.</li>
</ol>
<p>Bist du nicht im Firmennetz, verbinde dich vorher per VPN. Denk danach daran, das neue Kennwort auch auf dem Smartphone
und in anderen Programmen einzutragen, die sich mit deinem Konto anmelden.</p>
<p>Fragen? Antworte einfach auf diese Mail.</p>
<p style="color:#666;font-size:12px">Diese Nachricht wurde automatisch erstellt.</p>
</div>
"@

}

$filter = { Enabled -eq $true -and PasswordNeverExpires -eq $false -and mail -like '*' }
$params = @{ Filter = $filter; Properties = 'mail', 'GivenName', 'msDS-UserPasswordExpiryTimeComputed', 'pwdLastSet' }
if ($SearchBase) { $params.SearchBase = $SearchBase }

$sent = [System.Collections.Generic.List[object]]::new()

foreach ($user in Get-ADUser @params) {
    $raw = $user.'msDS-UserPasswordExpiryTimeComputed'
    # 0 = "muss bei nächster Anmeldung ändern", Int64.MaxValue = läuft nie ab
    if (-not $raw -or $raw -eq 0 -or $raw -ge [long]::MaxValue -or $user.pwdLastSet -eq 0) { continue }

    $expires = [datetime]::FromFileTime($raw)
    $days    = ($expires.Date - $today).Days
    if ($DaysBefore -notcontains $days) { continue }

    $to      = if ($TestRecipient) { $TestRecipient } else { $user.mail }
    $subject = if ($days -eq 1) { 'Dein Kennwort läuft morgen ab' } else { "Dein Kennwort läuft in $days Tagen ab" }

    if ($PSCmdlet.ShouldProcess("$($user.SamAccountName) <$to>", "Erinnerung senden ($days Tage)")) {
        try {
            Send-MailMessage @mail -To $to -Subject $subject -Body (Get-NoticeBody $user $expires $days) -ErrorAction Stop
            Write-NoticeLog "OK $($user.SamAccountName) $to läuft ab $($expires.ToString('dd.MM.yyyy')) ($days Tage)"
            $status = 'gesendet'
        }
        catch {
            Write-NoticeLog "FEHLER $($user.SamAccountName) $to $($_.Exception.Message)"
            Write-Warning "Versand an $to fehlgeschlagen: $($_.Exception.Message)"
            $status = 'Fehler'
        }
    }
    else { $status = 'Testlauf' }

    $sent.Add([pscustomobject]@{
        Benutzer = $user.SamAccountName
        Name     = $user.Name
        Mail     = $user.mail
        Ablauf   = $expires.ToString('dd.MM.yyyy HH:mm')
        Tage     = $days
        Status   = $status
    })
}

if ($sent.Count -eq 0) {
    Write-Host 'Heute ist keine Erinnerung fällig.' -ForegroundColor Green
    return
}

$sent | Sort-Object Tage, Benutzer | Format-Table -AutoSize

if ($ReportTo -and -not $WhatIfPreference) {
    $title = 'Kennwort-Erinnerungen vom {0:dd.MM.yyyy}' -f $today
    $html  = $sent | Sort-Object Tage, Benutzer | ConvertTo-Html -Title $title -PreContent "<h2>$title</h2>" | Out-String
    Send-MailMessage @mail -To $ReportTo -Subject $title -Body $html
}