PSADDS

0.0.1

Public/User/Set-ADUserCommonName.ps1

<#
    .SYNOPSIS
    Set the common name (CN) of an Active Directory user to a consistent "GivenName Surname" format (or reversed).
 
    .DESCRIPTION
    Renames the AD user object so its CN (the relative distinguished name) matches the user's GivenName and
    Surname, in the chosen order. Useful to homogenize the CN across a directory where objects were created
    with inconsistent naming conventions.
 
    Only the CN (object name) is changed. The sAMAccountName, userPrincipalName, DisplayName and other
    attributes are left untouched. Supports -WhatIf and -Confirm.
 
    Requires the ActiveDirectory module (RSAT) and rights to rename the target objects.
 
    .PARAMETER Identity
    One or more AD users (sAMAccountName, distinguishedName, GUID or SID). Accepts pipeline input,
    including objects piped from Get-ADUser.
 
    .PARAMETER NameOrder
    Order used to build the CN:
    - 'GivenNameSurname' (default) -> "John Doe"
    - 'SurnameGivenName' -> "Doe John"
 
    .PARAMETER Separator
    String placed between the given name and the surname. Default is a single space.
 
    .PARAMETER Server
    Optional domain controller to target.
 
    .EXAMPLE
    Set-ADUserCommonName -Identity jdoe
 
    Renames the CN of jdoe to "GivenName Surname".
 
    .EXAMPLE
    Get-ADUser -Filter * -SearchBase 'OU=Users,DC=contoso,DC=com' | Set-ADUserCommonName -NameOrder SurnameGivenName -WhatIf
 
    Previews renaming every user in the OU so the CN becomes "Surname GivenName".
 
    .LINK
    https://github.com/bastienperez/PSADDS
#>
function Set-ADUserCommonName {
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
    param (
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
        [Alias('SamAccountName', 'DistinguishedName', 'ObjectGUID')]
        [String[]]$Identity,

        [Parameter(Mandatory = $false)]
        [ValidateSet('GivenNameSurname', 'SurnameGivenName')]
        [String]$NameOrder = 'GivenNameSurname',

        [Parameter(Mandatory = $false)]
        [String]$Separator = ' ',

        [Parameter(Mandatory = $false)]
        [String]$Server
    )

    begin {
        if (-not (Get-Command Get-ADUser -ErrorAction SilentlyContinue)) {
            throw 'The ActiveDirectory module is required (RSAT). Import it and try again.'
        }

        # Forward an optional -Server to every AD call via splatting.
        $adParams = @{}
        if (-not [string]::IsNullOrWhiteSpace($Server)) {
            $adParams['Server'] = $Server
        }
    }

    process {
        foreach ($id in $Identity) {
            try {
                $user = Get-ADUser -Identity $id -Properties GivenName, Surname @adParams -ErrorAction Stop
            }
            catch {
                Write-Warning "[!] Cannot find AD user '$id'. $($_.Exception.Message)"
                continue
            }

            $givenName = $user.GivenName
            $surname = $user.Surname

            if (([string]::IsNullOrWhiteSpace($givenName)) -or ([string]::IsNullOrWhiteSpace($surname))) {
                Write-Warning "[*] '$($user.SamAccountName)' is missing GivenName or Surname, skipping."
                continue
            }

            if ($NameOrder -eq 'SurnameGivenName') {
                $newCN = "$surname$Separator$givenName"
            }
            else {
                $newCN = "$givenName$Separator$surname"
            }

            # $user.Name is the RDN (the CN value for a user object).
            if ($user.Name -eq $newCN) {
                Write-Verbose "[i] '$($user.SamAccountName)' CN is already '$newCN', skipping."
                continue
            }

            if ($PSCmdlet.ShouldProcess($user.DistinguishedName, "Rename CN to '$newCN'")) {
                try {
                    Rename-ADObject -Identity $user.DistinguishedName -NewName $newCN @adParams -ErrorAction Stop
                    Write-Host -ForegroundColor Green "[OK] '$($user.SamAccountName)' CN set to '$newCN'"
                }
                catch {
                    Write-Warning "[!] Failed to rename '$($user.SamAccountName)' to '$newCN'. $($_.Exception.Message)"
                }
            }
        }
    }
}