Using Set-mgUserLicense in Powershell

Using Set-mgUserLicense in Powershell

For administrators handling Microsoft 365, managing user licenses accurately is essential. The Set-MgUserLicense cmdlet in the Microsoft Graph PowerShell SDK helps simplify this task by providing detailed control over user licenses through direct interaction with the Microsoft Graph API.

Let's learn how to effectively use Set-MgUserLicense, specifically how to add and remove licenses and service plans for users in three easy steps.

What is the Set-MgUserLicense Cmdlet in PowerShell?

Set-MgUserLicense is a PowerShell cmdlet provided by the Microsoft Graph PowerShell SDK, which allows administrators to manage user licenses directly through the Microsoft Graph API.

This cmdlet enables adding or removing licenses and service plans for a specific user in Microsoft Azure Active Directory. With Set-MgUserLicense, administrators can modify the licenses assigned to a user by specifying the user's identifier and providing details about the licenses and service plans to add or remove.

The syntax of Set-MgUserLicense is the following:


-UserId <String>

[-ResponseHeadersVariable <String>]

[-AddLicenses <IMicrosoftGraphAssignedLicense[]>]

[-AdditionalProperties <Hashtable>]

[-RemoveLicenses <String[]>]

[-Headers <IDictionary>]

[-ProgressAction <ActionPreference>]




Here’s a list with the meanings of these different parameters:

  • -UserId <String>: Mandatory identifier for the user whose licenses are to be managed.
  • -ResponseHeadersVariable <String>: Optional; stores API response headers in a specified variable.
  • -AddLicenses <IMicrosoftGraphAssignedLicense>: Specifies licenses to add to the user, including any service plans.
  • -AdditionalProperties <Hashtable>: Optional; allows adding extra properties to the request.
  • -RemoveLicenses <String>: Specifies licenses to remove from the user.
  • -Headers <IDictionary>: Optional; allows adding custom HTTP headers to the API request.
  • -ProgressAction <ActionPreference>: Controls the display of progress updates during cmdlet execution.
  • -WhatIf: Shows what would happen if the cmdlet executes, without making changes.
  • -Confirm: Prompts for confirmation before executing the cmdlet.

What Can You Use the "Set-MgUserLicense" Command For?

The Set-MgUserLicense cmdlet is versatile in managing Microsoft 365 licenses within an organization. Here are three practical use cases:

  • Provisioning New Employees: When new employees join an organization, they often require access to various Microsoft services like Office 365, Dynamics, or specific features within these applications. This includes adding specific service plans that are essential for their roles and ensuring they have immediate access to the tools needed for their job functions.
  • License Optimization and Cost Savings: Organizations frequently review their license utilization to optimize costs. Set-MgUserLicense can be used to remove licenses or specific service plans that are no longer needed by certain users.
  • Streamlining Departing Employee Processes: When employees leave a company, it's crucial to promptly remove their access to company resources to maintain security and compliance. Set-MgUserLicense can be used to remove all assigned Microsoft 365 licenses from departing users.

Prerequisites to Run the Set-MgUserLicense Cmdlet

To effectively utilize the Set-MgUserLicense cmdlet in PowerShell, there are three key prerequisites:

  1. Permissions: For work or school accounts using delegated access, the necessary minimum permission is User.ReadWrite.All, allowing read and write access to user profiles. For broader administrative operations that involve managing other elements of the directory, Directory.ReadWrite.All is required. When using the cmdlet under application access, similar permissions are required, ensuring the application can perform needed user and directory modifications.
  2. Installation of the Microsoft Graph PowerShell SDK: This SDK is crucial as it provides the necessary commands and access to Microsoft Graph API, which Set-MgUserLicense uses to manage user licenses. The SDK must be properly installed and configured in your PowerShell environment to enable these functionalities.
  3. Authentication and Authorization Setup: Depending on the access type, the correct authentication method needs to be established. For delegated access, the individual running the cmdlet needs to authenticate using their user account credentials that have the required permissions. For application access, the application itself should be registered in Azure AD.

How to Use Set-MgUserLicense in PowerShell

Now that we know what this cmdlet is for, let's learn how to assign or remove licenses to users in three quick steps.

Step 1: Connect to Microsoft Graph

Before executing any cmdlet that interacts with Microsoft Graph, you need to establish a connection using the Connect-MgGraph cmdlet.

You'll need to choose the appropriate permissions scope depending on your needs; for license management, scopes like User.ReadWrite.All or Directory.ReadWrite.All may be required, so the prompt should look like this:

Connect-MgGraph -Scopes "User.Read.All", "Group.ReadWrite.All"

Step 2: Execute Set-MgUserLicense

After successfully connecting to Microsoft Graph, you are ready to modify user licenses. Depending on the task, this could involve adding new licenses, removing existing ones, or modifying service plans within a license. Take a look at the following example:

Connect-Graph -Scopes User.ReadWrite.All, Organization.Read.All

$EmsSku = Get-MgSubscribedSku -All | Where SkuPartNumber -eq 'MEETINGROOM'

Set-MgUserLicense -UserId '73189456-c279-4b82-9643-2196430bc78' -AddLicenses @{SkuId = $EmsSku.SkuId} -RemoveLicenses @()

Id          DisplayName     Mail           UserPrincipalName                                         UserType
--           -----------                 ----                                                  -----------------                          --------
38955658-c844-4f59-9430-6519430ac89b James Member

This example assigns a license from the MEETINGROOM licensing plan to the unlicensed user 73189456-c279-4b82-9643-2196430bc78 (

Step 3: Verify and Log the Changes

After executing the modification command, it’s important to verify that the changes have been applied correctly. Use Get-MgUserLicenseDetail or check the user’s license status through the Microsoft 365 admin center.

Why is Set-MgUser Not Working?

If you encounter issues while using the Set-MgUserLicense cmdlet and it's not working as expected, here are three troubleshooting steps you can take:

  • Check Permissions: Ensure that you have the necessary administrative permissions to modify user licenses in Microsoft 365. You might need specific admin roles assigned to your account, such as Global Administrator or User Management Administrator.
  • Update PowerShell and SDKs: Verify that you are using the latest version of PowerShell and that the Microsoft Graph PowerShell SDK is up to date.
  • Review Error Messages: Carefully examine any error messages returned by the cmdlet. These messages can provide clues about what is going wrong. Check for syntax errors, incorrect user IDs, or issues with the license information you are trying to assign or remove.

Mastering Set-MgUserLicense in PowerShell

The Set-MgUserLicense cmdlet is a powerful way to manage Microsoft 365 licenses, making it easier to adjust user permissions with precise commands. By learning this tool, administrators can customize licenses to meet changing organizational needs, ensure compliance, and manage resources effectively.

Using Microsoft Graph with PowerShell improves operational efficiency and gives detailed control over user accounts and services in real time.