MSEndpointMgr

Remove Synchronized Users in a Microsoft Intune tenant with PowerShell

Occasionally I stumble upon environments where the customer have been piloting Intune or Office 365 and signed up for a tenant. In most cases, the customers signed up for a tenant and want to re-use that tenant when going into production. In my experience, the tenant might have a bunch of synchronized test (or actual production) users accounts from the on-prem Active Directory. For various reasons, perhaps the user accounts where not synced correctly with a sync anchor best suited for the deployment scenario, which leaves you to just begin all over again and synchronize everything correctly.
In this case, it would be a good idea to scrap everything that’s already synchronized to get a clean synchronization experience, and decrease the fact of running into any obvious synchronization issues. If you’ve ever attempted to remove a synchronized user account in your Microsoft Intune tenant (e.g. through the legacy Azure Portal browsing your Directory), you’ve experienced that there’s no easy way of completing that task.
To accomplish this, we can turn to PowerShell (as always).

Requirements

First you’ll need to install the Online Services Sign-In Assistant, and then install the Azure Active Directory module for PowerShell. Since the 32-bit version of the module has been deprecated, I suggest that you install the 64-bit version to stay up to date. You’ll find the downloads required below:
Microsoft Online Services Sign-In Assistant for IT Professionals RTW
Azure Active Directory Module for Windows PowerShell (64-bit version)
For those of you that want to use the latest version of the Azure Active Directory Module for PowerShell (currently in Preview as of writing), that leverages Active Directory Authentication Library (ADAL), you can download that from Microsoft Connect here:
https://connect.microsoft.com/site1164/Downloads/DownloadDetails.aspx?DownloadID=59185

NOTE! The Preview version does not require the Online Services Sign-In Assistance since it’s using ADAL for authentication.

Download the script

You’ll find the script on TechNet Gallery.

Script documentation

This script was created to remove all or individual synchronized user accounts in an Azure Active Directory tenant. If any licenses have been attached for any of the user accounts that will be removed, these licenses will be available again after the user account has been removed. When a synchronized user account is removed in the tenant, it’s automatically put in a Recycle Bin for 30 days (default value). This script supports to delete removed user accounts from the Azure Active Directory Recycle Bin by specifying the Purge switch. If you’re going to synchronize the same user identity again, it’s recommended that you purge all the synchronized user accounts when running this script.
If you’d want to get a list of all the synchronized user accounts that eligible for removal by executing this script, use the List switch. When running this script, you’ll be prompted to specify your tenant admin credentials.
Below is a table of the available parameters and switches for this script:

ParameterParameterSetNameRequiredTypeDescription
UserPrincipalNameRemoveUserTrueString ArrayUser account(s) to be removed. Supports a string array of UserPrincipalNames.
AllAllUsersTrueSwitchAll synchronized user accounts will be removed.
ListListUsersTrueSwitchList user accounts eligible for removal. No user account will be removed.
PurgeRemoveUser
AllUsers
False
False
SwitchRemoved user accounts will be deleted from the Recycle Bin.
ShowProgressRemoveUser
AllUsers
False
False
SwitchShow a progressbar displaying the current operation.

Using the script

Download the script and make sure that you’ve both the Online Services Sign-In Assistance and Azure Active Directory Module for PowerShell installed on the system where you’re about to execute the script. In the example below, I’ll attempt to remove two of my synchronized user accounts. I’ve added the common parameter WhatIf as you can see in the screenshot, just because I don’t want to actually remove any user accounts in my tenant. But in your case, simply just run the command provided below.
1. Open an elevated PowerShell console and browse to where you’ve downloaded the script, e.g. C:\Scripts.
2. Run the following command (replace the UserPrincipalName values accordingly):

.\Remove-AADSynchronizedUser.ps1 -UserPrincipalName "[email protected]","[email protected]" -Purge

3. You’ll first be prompted to enter valid credentials:
174_1
4. When you’ve entered valid credentials, the script will execute:
174_2
If you’d want to remove all synchronized user accounts and delete them from the Recycle Bin, simply run the following command:

.\Remove-AADSynchronizedUser.ps1 -All -Purge -ShowProgress

And for listing the synchronized user accounts eligible for removal, run the following command:

.\Remove-AADSynchronizedUser.ps1 -List

I hope this helps, let me know if you have any questions.

(1319)

Nickolaj Andersen

Chief Technical Architect and Enterprise Mobility MVP since 2016. Nickolaj has been in the IT industry for the past 10 years specializing in Enterprise Mobility and Security, Windows devices and deployments including automation. Awarded as PowerShell Hero in 2015 by the community for his script and tools contributions. Creator of ConfigMgr Prerequisites Tool, ConfigMgr OSD FrontEnd, ConfigMgr WebService to name a few. Frequent speaker at conferences such as Microsoft Ignite, NIC Conference and IT/Dev Connections including nordic user groups.

1 comment

Sponsors