Remove Synchronized Users in a Microsoft Intune tenant with PowerShell

174_1

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:

http://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:

Parameter ParameterSetName Required Type Description
UserPrincipalName RemoveUser True String Array User account(s) to be removed. Supports a string array of UserPrincipalNames.
All AllUsers True Switch All synchronized user accounts will be removed.
List ListUsers True Switch List user accounts eligible for removal. No user account will be removed.
Purge RemoveUser
AllUsers
False
False
Switch Removed user accounts will be deleted from the Recycle Bin.
ShowProgress RemoveUser
AllUsers
False
False
Switch Show 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 "nickolaj@scconfigmgr.com","jamesa@scconfigmgr.com" -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.

1 Comment

  1. Pingback: Friday Five: Windows and Enterprise Mobility #13 - Windows, Enterprise Mobility, Productivity and IoT

Leave a Comment

Your email address will not be published. Required fields are marked *