How to Use Remove-MgDirectoryRoleMemberByRef to Remove Members From Directory Roles?

Managing directory roles effectively is critical to maintaining security and governance in Microsoft 365 and Azure Active Directory. Whether you're removing users, groups, or applications from privileged roles, the Remove-MgDirectoryRoleMemberByRef cmdlet offers a secure and automated way to do it.

In this blog, we’ll explore what this cmdlet does, why it’s essential, and walk through practical examples to help you remove role assignments with confidence.

What is Remove-MgDirectoryRoleMemberByRef?

Remove-MgDirectoryRoleMemberByRef is a Microsoft Graph PowerShell cmdlet used to remove a member (user, group, or service principal) from an activated directory role in Azure Active Directory.

This cmdlet doesn’t delete users or roles—it simply removes the relationship between the directory role and the assigned member. Think of it as revoking access to the permissions tied to that role.

Why Use Remove-MgDirectoryRoleMemberByRef?

Here’s why this cmdlet is a must-have in any admin’s toolbox:

• Enforce Least Privilege: Remove users from high-privilege roles like Global Administrator once their tasks are complete.
• Automate Role Cleanup: Schedule regular audits and use scripts to remove inactive accounts from roles.
• Avoid Manual Errors: Programmatic role revocation is safer and less error-prone than manual removal via the portal.
• Support Role-Based Access Control (RBAC): Keeps your access model clean and compliant.

Cmdlet Syntax

Remove-MgDirectoryRoleMemberByRef -DirectoryRoleId <String> -DirectoryObjectId <String>

Parameters:

• -DirectoryRoleId: The unique ID of the activated directory role.
• -DirectoryObjectId: The object ID of the member (user, group, or service principal) you want to remove from the role.

Usage Examples

Let’s look at three real-world examples where you might use this cmdlet.

Example 1: Remove a User from the Global Administrator Role

$roleId = (Get-MgDirectoryRole -Filter "displayName eq 'Company Administrator'").Id
$userId = (Get-MgUser -UserId "alex.williams@contoso.com").Id
Remove-MgDirectoryRoleMemberByRef -DirectoryRoleId $roleId -DirectoryObjectId $userId
                                        

This removes the user alex.williams@contoso.com from the Global Administrator role.

Example 2: Remove a Service Principal from a Custom Role

$customRole = Get-MgDirectoryRole -Filter "displayName eq 'App Manager'"
$sp = Get-MgServicePrincipal -Filter "displayName eq 'CustomApp1'"
Remove-MgDirectoryRoleMemberByRef -DirectoryRoleId $customRole.Id -DirectoryObjectId $sp.Id
                                        

Use this when revoking application-level permissions assigned via a custom directory role.

Example 3: Remove a Group from the User Administrator Role

$roleId = (Get-MgDirectoryRole -Filter "displayName eq 'User Administrator'").Id
$groupId = (Get-MgGroup -Filter "displayName eq 'HR Admins'").Id
Remove-MgDirectoryRoleMemberByRef -DirectoryRoleId $roleId -DirectoryObjectId $groupId
                                        

Perfect for managing group-based access control, especially in enterprise environments.

Frequently Asked Questions

• Can this cmdlet delete users or roles?

No. It only removes the link between a directory role and its member. No data or identities are deleted.

• How can I find which members are assigned to a directory role?

Get-MgDirectoryRoleMember -DirectoryRoleId

• Can this be used to remove guest users?

Yes, as long as the guest user is a member of the role and you have their object ID.

Use Cases

Here are some practical scenarios where this cmdlet shines:

• Revoke Temporary Admin Access: After resolving an issue, revoke elevated privileges from helpdesk staff or contractors.
• Role Reassignments: When team responsibilities change, reassign roles by removing old members and adding new ones.
• Security Audit Compliance: Regularly clean up unused role memberships to stay compliant with internal and external security policies.
• Automated Offboarding: Integrate with your HR system to auto-remove employees from all roles upon departure.

Conclusion

The Remove-MgDirectoryRoleMemberByRef cmdlet offers a simple, scriptable, and secure way to revoke directory role access in Microsoft 365 and Azure AD. Whether you're managing users, apps, or groups, it's an essential tool in your admin toolkit.

Want to streamline your role assignment and revocation processes? Stay tuned for our upcoming scripts and automation playbooks tailored for IT admins!