Restore-MgDirectoryDeletedItem — Recover Soft-Deleted Azure AD Objects

The Restore-MgDirectoryDeletedItem cmdlet lets you recover deleted Azure AD (Entra ID) objects such as users and Microsoft 365 groups. When an object is deleted, it’s retained in a soft-deleted state for a limited period, allowing easy restoration before permanent removal. This cmdlet provides a safe and direct way to undo accidental deletions from your tenant.

i) Cmdlet Syntax

Restore-MgDirectoryDeletedItem -DirectoryObjectId <directory-object-id>

Required scope (recommended):

Connect-MgGraph -Scopes "Directory.ReadWrite.All"

ii) Usage Examples

Restoring Single Deleted Microsoft 365 Directory Object

Step 1: Get the Directory Object ID to be recovered

Use the correct helper depending on what you’re restoring.

• If restoring a user

# List deleted users and pick one

Get-MgDirectoryDeletedItemAsUser | Select-Object Id, DisplayName, UserPrincipalName, DeletedDateTime | Sort-Object DeletedDateTime -Descending

• If restoring a group

# List deleted groups and pick one

Get-MgDirectoryDeletedItemAsGroup | Select-Object Id, DisplayName, Mail, GroupTypes, DeletedDateTime | Sort-Object DeletedDateTime -Descending

Note down the Id of the object you want to restore.

Step 2: Pass the fetched Directory Object ID to Restore-MgDirectoryDeletedItem

Restore-MgDirectoryDeletedItem -DirectoryObjectId ae22d08d-1ef5-4ac0-b36b-376864f6b63a

Step 3: Verify the restore completed

# For a user (look for it in active users now)

Get-MgUser -Filter "userPrincipalName eq 'amanda@contoso.com'" -All

# For a group (look for it in active groups)

Get-MgGroup -Filter "displayName eq 'Finance - AP'" -All

Restoring All Deleted Microsoft 365 Directory Objects

You can restore all soft deleted Microsoft 365 Directory Objects by piping the results from Get-MgDirectoryDeletedItemAsUser or Get-MgDirectoryDeletedItemAsGroup to Restore-MgDirectoryDeletedItem cmdlet and looping through each item in the list using a ForEach-Object cmdlet.

Get-MgDirectoryDeletedItemAsUser -All | ForEach-Object { Restore-MgDirectoryDeletedItem -DirectoryObjectId $_.Id -Confirm:$false }

Note: You can also confirm the deletion by running Get-MgDirectoryDeletedItemAsUser or Get-MgDirectoryDeletedItemAsGroup, depending on your requirements.

iii) Cmdlet Tips

• Know the window: Users and groups are only soft-deleted for a limited period (commonly up to 30 days for users and M365 groups). After that, they’re permanently deleted and cannot be restored.
• Use the right “AsX” getter:
• Users → Get-MgDirectoryDeletedItemAsUser
• Groups → Get-MgDirectoryDeletedItemAsGroup
• Minimal info you need: The Id (GUID) from the deleted item. Pass it to -DirectoryObjectId.
• Permissions matter: Directory.ReadWrite.All is the safest single scope for restore. Ensure your account has sufficient admin rights.
• Naming conflicts: If the original UPN, mail nickname, or proxyAddresses are now taken by a new object, the restore may fail or the object may be restored with adjusted identifiers.
• After restore checks: Reconfirm licenses, group memberships, and app assignments—some downstream systems may need a sync cycle.

iv) Use Cases

• Accidental deletion recovery of a user or Microsoft 365 group.
• Rapid rollback during clean-up projects when an object was removed too aggressively.
• Disaster recovery drills to validate soft-delete/restore workflows.
• Compliance: restore a group that was housing critical SharePoint/Teams resources linked to a Microsoft 365 group.

v) Possible Errors & Solutions

Error	Cause	How to Fix
Authorization_RequestDenied or Insufficient privileges to complete the operation.	Missing scopes or insufficient admin role.	Reconnect with Connect-MgGraph -Scopes "Directory.ReadWrite.All" and ensure your role (e.g., User/Group/Directory admin) is adequate.
ResourceNotFound / Request_ResourceNotFound	The ID doesn’t exist in the deleted container (typo, already restored, or permanently deleted).	Re-list deleted items with Get-MgDirectoryDeletedItemAsUser or ...AsGroup and pick a current Id.
Request_BadRequest with message about property/identifier conflict	The original UPN/MailNickname/ProxyAddress is in use by another object created after deletion.	Rename or release the conflicting identifier on the current object, then retry the restore.
Restore succeeds but user can’t sign in	Password/Conditional Access/licensing not set as before; sync lag for hybrid tenants.	Re-assign license(s), verify sign-in status and Conditional Access, and allow directory sync (if hybrid).
Group restored but not visible immediately in clients	Service caches and replication delays.	Wait a few minutes, then refresh clients/portal; verify via Get-MgGroup first.
Forbidden	You’re connected with delegated permissions from an account without rights, or using application identity without required app role.	Use a privileged admin account or an app registration granted Directory.ReadWrite.All (application) consent by an admin.

vi) Conclusion

Restore-MgDirectoryDeletedItem provides a reliable way to recover users or groups deleted by mistake in Azure AD. By first identifying the deleted object with Get-MgDirectoryDeletedItemAsUser or ...AsGroup, and then restoring it with a single command, administrators can quickly reverse accidental deletions. Ensure proper permissions, resolve naming conflicts, and verify post-restore configurations for a smooth recovery process.