How to Use the Set-MgUserLicense Cmdlet to Assign Licenses in Microsoft 365

Managing Microsoft 365 licenses efficiently is crucial for IT administrators. The Set-MgUserLicense cmdlet from the Microsoft Graph PowerShell module allows you to assign or remove licenses from users in a streamlined manner. This article walks you through the cmdlet's syntax, practical examples, pro tips, use cases, common errors, and their solutions.

Cmdlet Syntax

Set-MgUserLicense -UserId  [-AddLicenses <IMicrosoftGraphAssignedLicense>] [-RemoveLicenses <IMicrosoftGraphGuidCollection>] 

Parameters:

• -UserId: The UPN (e.g., user@domain.com) or the GUID of the user.
• -AddLicenses: A hashtable containing the SkuId of the license to assign.
• -RemoveLicenses: A list of SkuIds to remove (use @() if none to remove).

Usage Examples

Assign License Using UPN

Set-MgUserLicense -UserId jackie@7xh7fj.onmicrosoft.com ` -AddLicenses @{SkuId = "c42b9cae-ea4f-4ab7-9717-81576235ccac"} `-RemoveLicenses @()

Assign License Using User Id

Set-MgUserLicense -UserId cd6cd291-41ba-4b3d-ba70-5f5f07292843 ` -AddLicenses @{SkuId = "c42b9cae-ea4f-4ab7-9717-81576235ccac"} `-RemoveLicenses @()

Bulk Assign User License from CSV

CSV Format (Users.csv):

UserPrincipalName,SkuId

alice@domain.com,c42b9cae-ea4f-4ab7-9717-81576235ccac

bob@domain.com,c42b9cae-ea4f-4ab7-9717-81576235ccac

PowerShell Script:

Import-Csv "Users.csv" | ForEach-Object {
Set-MgUserLicense -UserId $_.UserPrincipalName `-AddLicenses @{SkuId = $_.SkuId} `-RemoveLicenses @()}

Cmdlet Tips

• Always include -RemoveLicenses @() even if you're not removing any licenses. If omitted, the command might silently fail or throw an error.
• Use Get-MgSubscribedSku to fetch valid license SkuIds before assigning licenses. Run:

Get-MgSubscribedSku | Select SkuPartNumber, SkuId

• License assignment might take a few seconds to reflect in the Microsoft 365 admin portal. Be patient when verifying changes.
• Run Get-MgUserLicenseDetail -UserId to check what licenses the user already holds before assigning new ones.
• Use UPN for simplicity during scripting unless you're specifically working with user IDs. Both formats are accepted.

Use Cases

• Onboarding Automation: Automate the license assignment process as part of user provisioning. When a new employee joins, licenses can be assigned instantly through scripted workflows.
• Bulk Licensing: Assign licenses to hundreds or thousands of users using a CSV file—perfect during mergers, migrations, or company-wide license rollouts.
• Role-Based License Management: Assign different license SKUs based on the user's department or job role. For example, give Microsoft 365 E5 to IT staff and Business Basic to interns.
• License Reallocation: Easily remove old licenses and assign new ones when a user moves to a different team or is promoted.
• License Optimization: Remove unused licenses from inactive or disabled accounts, helping your organization save on unnecessary costs.

Frequently Asked Questions

• Can I assign multiple licenses to a user using Set-MgUserLicense?

Yes, you can pass multiple SkuId values in the AddLicenses array within the -BodyParameter hashtable. This allows bulk license assignment in one call.

• How do I find the correct SkuId to use with Set-MgUserLicense?

You can retrieve available SkuId values using the Get-MgSubscribedSku cmdlet. The SkuId is a GUID associated with each licensed product.

• Can I assign licenses to guest users?

While technically possible, most Microsoft 365 licenses are intended for member users. Assigning licenses to guests may result in compliance or billing issues and is generally not recommended.

Possible Errors & Solutions

Error	Cause	Solution
Cannot convert the literal 'System.Collections.Hashtable' to the expected type 'Edm.Guid'.	Incorrect use of -AddLicenses format.	Use the correct hashtable syntax: -AddLicenses @{SkuId = ""}
The property 'RemoveLicenses' must be specified for this request.	Missing -RemoveLicenses parameter.	Always include -RemoveLicenses @() even if you're not removing any licenses.
License assignment failed. License limit exceeded, or the user is already licensed.	The license quota has been exceeded or the user already has the license.	Check the user’s current licenses using Get-MgUserLicenseDetail and validate availability.
Access Denied or Insufficient privileges to complete the operation.	Lack of required permissions.	Ensure the account has User.ReadWrite.All and Directory.ReadWrite.All delegated/app consent.

Notes

• Where to get the SkuId for assigning licenses?

Use the following command:

Get-MgSubscribedSku | Select SkuPartNumber, SkuId

This returns a list of all license types (like ENTERPRISEPACK, BUSINESS_PREMIUM) and their unique identifiers.


• Why is -RemoveLicenses @() required even when you’re not removing anything?

The Microsoft Graph API expects both AddLicenses and RemoveLicenses to be explicitly defined in the request. Omitting one can lead to failure or unexpected behavior. Always include both for a successful operation.

Conclusion

The Set-MgUserLicense cmdlet is a powerful and reliable way to assign or remove Microsoft 365 licenses from users. Whether you're managing a single user or deploying licenses in bulk, this cmdlet simplifies the task with consistency and automation support. Just ensure:

• The SkuId is valid,
• You include -RemoveLicenses @(), and
• Your account has the right permissions.

With proper usage, you can automate onboarding, streamline license distribution, and maintain better control over your Microsoft 365 environment.