Updating the User Principal Name When Restoring a Deleted User Account is Only Possible with PowerShell
In the past, I’ve covered the topic of rewriting user principal names and email addresses following the decision by a tenant to use a new domain. This could be because of a corporate rebranding or part of a tenant split or merge. The actions necessary to update user principal names and email addresses for all accounts can be executed in a one-off operation at a suitable time, such as over the weekend. If all goes well, everyone comes in after the weekend and uses their newly assigned user principal names and email addresses.
But what happens if the need arises to restore some soft-deleted user accounts and make sure that the newly restored accounts comply with the new tenant naming standard? Or avoid the problem where the user principal name originally assigned to a deleted user account has been reassigned to another account. These scenarios are slightly tricker than normal restores. Let’s explain why.
Methods to Restore a Deleted User Account
Deleted directory objects remain in the Entra ID deleted items cache for thirty days following their deletion. During this time, the objects are soft-deleted and recoverable. After the deleted item retention period for an object expires, Entra ID removes the object permanently (a hard delete) and it becomes irrecoverable. During the retention period, an administrator can purge the soft-deleted account object by running the Remove-MgDirectoryDeletedItem cmdlet.
A soft-deleted object can be recovered at any time during its deleted retention period. Recovery means that the object becomes usable again. In the case of a recovered user account, the account also regains its membership of groups and any administrative roles it held prior to deletion. Restoring a user account preserves other information too, such as the identifier for the account. This is critical for actions such as reconnecting OneDrive for Business.
Two ways exist to restore a user account with a new user principal name.
The first method is to restore the account as usual and then run the Update-MgUser cmdlet to update the user principal name. Running the Update-MgUser cmdlet to change the user principal name is what happens if you perform the update in an admin center.
$User = Get-MgUser -UserId 'Marc.Vigneau@office365itpros.onmicrosoft.com' Update-MgUser -UserId $User.Id -UserPrincipalName 'Marc.Vigneau@office365itpros.com'
Alternatively, you can restore the account and update its user principal name at the same time. This action is not supported by the Microsoft 365 admin center or Entra admin center, but the action is supported by the Restore deleted items Graph API and can be done with PowerShell by running the Restore-MgBetaDirectoryDeletedItem cmdlet from the Microsoft Graph PowerShell SDK.
No matter how you decide to restore a deleted user account, it’s wise to check the object properties in the Entra admin center (Figure 1) afterward to make sure that everything appears OK. It’s also wise to reset the account password and check multifactor authentication methods and assigned licenses before making sure that the user can sign in and work with Microsoft 365. Remember that it can take a little while before the Teams AadSync process adds restored users to team rosters.
Restoring a Deleted User Account with a New UPN
Let’s have a look at some example code that restores a deleted user account and assigns a new user principal name.
Connect-MgGraph -Scopes User.DeleteRestore.All
$DeletedUserUPN = "Marc.Vigneau@office365itpros.com"
$SearchString = $DeletedUserUPN.split('@')[0].Replace("."," ")
$NewUserPrincipalName = $DeletedUserUPN.split('@')[0] + "@office365exchangebook.com"
$NewUPNDetails = @{}
$NewUPNDetails.Add("newUserPrincipalName",$NewUserPrincipalName)
$NewUPNDetails.Add("autoReconcileProxyConflict",$true)
$DeletedObject = Get-MgDirectoryDeletedItemAsUser -Filter "displayName eq '$SearchString'"
If ($DeletedObject) {
Write-Host “Restoring Object with new User principal Name”
$Status = Restore-MgBetaDirectoryDeletedItem -DirectoryObjectId $DeletedObject.Id -BodyParameter $NewUPNDetails
If ($Status) {
Write-Host ("Account restored for {0} with UPN of {1}" -f $SearchString, $NewUserPrincipalName)
}
}
First, the code connects an interactive Graph SDK session by running Connect-MgGraph. The User.DeleteRestore.All permission is enough to restore a deleted account using delegated permissions, if the account that’s signed into the session holds at least the User administrator role. See the notes on the API documentation for details.
For the purpose of this demonstration, the user principal name of the account to restore is hardcoded. The code computes the new user principal name and builds a hash table holding the parameters for the command Entra ID will process. The parameters instruct Entra ID to assign the new user principal name and check for any conflict that the assignment of the new user principal name might cause with proxy addresses assigned to other objects within the tenant.
Next, the code attempts to find the deleted account to restore by searching the set of deleted user account objects based on the display name extracted from the original user principal name. This is a very simple search and will only work if the account’s display name is contained in the old user principal name.
A more complex search uses the old user principal name to search for a deleted object. This is an Entra ID advanced query because the query uses the endsWith operator to check the user principal name. Advanced queries run against a separate data store, so the request headers passed to the Get-MgDirectoryDeletedItemAsUser cmdlet contain the command to set the consistency level to eventual. In other words, execute the query against the data store that contains consistent Entra ID data rather than whatever copy of the distributed Entra ID store you’re connected to, which might include some inconsistent data due to synchronization glitches or lags. We therefore end up with:
$Headers = @{}
$Headers.Add("consistencylevel","eventual")
$DeletedObject = Get-MgDirectoryDeletedItemAsUser -Filter "endsWith(UserPrincipalName,'$DeletedUserUPN')" -Headers $Headers -CountVariable OutCount
Entra ID supports searching with the startsWith operator too, but it’s not included in the operators that can filter against the user principal name.
No matter what search is used, it will either find or fail to find a matching deleted user account object. If a match is found, the Restore-MgBetaDirectoryDeletedItem cmdlet runs to restore the account, and because the parameters used with the cmdlet say that the user principal name for the restored object should have a different value, that’s what it gets.
Updating Email Addresses
When you restore an account and change its user principal name and the account is mailbox-enabled, Entra ID also updates the primary SMTP address for the mailbox. This is in line with the guidance to have the same values in the user principal name and primary SMTP address. To ensure that email continues to be delivered for messages addressed to the previous SMTP address, Exchange Online retains that address.
For instance, after running the code shown above to restore the Marc Vigneau account while changing its user principal name, the Get-Mailbox or Get-ExoMailbox reveals the set of email addresses assigned to the account. The primary SMTP address is the one prefixed with SMTP:, the other addresses have an smtp: prefix.
Get-Mailbox -Identity marc.vigneau@office365exchangebook.com | Select-Object -ExpandProperty emailaddresses smtp:Marc.Vigneau@office365itpros.com SMTP:Marc.Vigneau@office365exchangebook.com SIP:marc.vigneau@office365itpros.com smtp:Marc.A.Vigneau@office365itpros.com SPO:SPO_c22434e1-9567-4b9c-979e-ac5cd5ffae30@SPO_b662313f-14fc-43a2-9a7a-d2e27f4f3478 smtp:Marc.Vigneau@office365itpros.onmicrosoft.com
Changing User Principal Names When Restoring Accounts is Unusual
There’s a good reason why Microsoft doesn’t include the facility to change the user principal name when restoring a deleted user account in the admin centers: this is not something that needs to be done very often. But strange things happen during corporate restructuring projects and it’s possible that you might run into a situation where this action is necessary. Now you know what to do, so you can be a hero! But before becoming too confident, take some time to review a more developed version of the script that you can download from GitHub.
