Assign Microsoft 365 licences without needless manual work

In the admin center you see recognisable product names. In scripts you come across technical codes. They belong to the same licences.

What the admin center calls "Microsoft 365 E3" is a SKU in PowerShell and Graph: a product with a technical name (SkuPartNumber) and a GUID (SkuId). Each SKU consists of service plans: Exchange Online, SharePoint, Teams, Sway, Viva Engage and so on. You always assign a SKU, and per assignment you can turn off individual service plans with disabledPlans. The SKU stays the same and still counts as one licence.

Note that the technical name does not always resemble the product name: Microsoft 365 F3 is called SPE_F1. Microsoft publishes the full list, with every service plan, as a CSV on the page "Product names and service plan identifiers for licensing". What your own tenant has, and how much of it is in use, you retrieve with Get-MgSubscribedSku.

Connect-MgGraph -Scopes "Organization.Read.All"

Get-MgSubscribedSku -All |
  Select-Object SkuPartNumber, SkuId, ConsumedUnits,
    @{ n = "Gekocht"; e = { $_.PrepaidUnits.Enabled } }

A missing country code looks like a detail, but it can block a licence assignment.

Assigning a licence to a user without a usage location fails. Microsoft wants to know in which country someone uses the services, because not every service is available in every country. The value is a two-letter country code under ISO 3166-1 alpha-2: NL, BE, DE.

If you create a user in the Microsoft 365 admin center, the form asks for the location. Accounts synchronised from on-premises Active Directory have no location by default. In a hybrid environment this is therefore the first place to look when a licence does not arrive. With group-based licensing it is less noticeable: there a user without a location gets the tenant's country. For an employee in Germany in a Dutch tenant, that is wrong. How usage location relates to the other fields on the user object is covered in Entra ID user attributes.

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

Get-MgUser -All -Property Id, DisplayName, UserPrincipalName, UsageLocation, UserType |
  Where-Object { -not $_.UsageLocation -and $_.UserType -eq "Member" } |
  Select-Object DisplayName, UserPrincipalName

Update-MgUser -UserId "jan.jansen@bedrijf.nl" -UsageLocation "NL"

You need at least the License Administrator or User Administrator role. There are two ways in, and which one you choose depends on whether you work from the person or from the product.

1. 1From the user: go to Users > Active users, choose the user and open Licenses and apps. Tick the licence and expand the apps per licence to turn off service plans. Choose Save changes. For several people at once, select them in the list and choose Manage product licenses.
2. 2From the product: go to Billing > Licenses, choose the product and then Assign licenses. You add up to 20 users or groups at a time. Under Turn apps and services on or off you turn off service plans.
3. 3If something goes wrong, you see it on the product's Errors & issues tab: no licences left, conflicting service plans or an invalid usage location. Fix the cause, choose the user and then Reprocess.

Some services, such as Sway, are assigned by Microsoft automatically; you do not have to turn them on separately. If you do not want them, turn off the service plan.

For more than a handful of people, or as part of an onboarding script, you use Microsoft Graph PowerShell. Microsoft now only describes licence management in its documentation with this module. Convert scripts that still use Set-MsolUserLicense or Set-AzureADUserLicense to Set-MgUserLicense.

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

$sku = Get-MgSubscribedSku -All | Where-Object SkuPartNumber -eq "SPE_E3"
$uit = $sku.ServicePlans |
  Where-Object ServicePlanName -in "SWAY","YAMMER_ENTERPRISE" |
  Select-Object -ExpandProperty ServicePlanId

Set-MgUserLicense -UserId "jan.jansen@bedrijf.nl" -AddLicenses @(@{ SkuId = $sku.SkuId; DisabledPlans = $uit }) -RemoveLicenses @()

-RemoveLicenses is required, even if you are not removing anything; in that case pass an empty list. The same request in Microsoft Graph, for an integration or a Logic App, looks like this. The app needs at least the LicenseAssignment.ReadWrite.All permission.

POST https://graph.microsoft.com/v1.0/users/jan.jansen@bedrijf.nl/assignLicense
Content-Type: application/json

{
  "addLicenses": [
    {
      "skuId": "05e9a617-0261-4cee-bb44-138d3ef5d965",
      "disabledPlans": []
    }
  ],
  "removeLicenses": []
}

Moving from E3 to E5 is a RemoveLicenses of one SKU and an AddLicenses of the other. Afterwards, check with Get-MgUserLicenseDetail what the user really has.

If you want to clean up or automate, you first need to know where a licence comes from.

Before you remove a licence, you want to know where it comes from. If you remove a direct assignment while the same licence also arrives through a group, nothing changes. A licence that arrives through a group only disappears when the user leaves that group or the licence is removed from the group. In the admin center, under Billing > Licenses, a group assignment shows the group name instead of the individual users. Per user it is in licenseAssignmentStates: if assignedByGroup is empty, the licence was assigned directly; otherwise it holds the ID of the group.

$u = Get-MgUser -UserId "jan.jansen@bedrijf.nl" -Property LicenseAssignmentStates
$skus = Get-MgSubscribedSku -All

$u.LicenseAssignmentStates | ForEach-Object {
  $id = $_.SkuId
  [pscustomobject]@{
    Licentie = ($skus | Where-Object SkuId -eq $id).SkuPartNumber
    Bron     = if ($_.AssignedByGroup) { (Get-MgGroup -GroupId $_.AssignedByGroup).DisplayName } else { "Direct" }
    Status   = $_.State
  }
}

All three methods answer the question of how a licence reaches someone. None of the three answers the question of who should have it. With direct assignment that lives in the administrator's head or in an onboarding form, with a group in the membership and with auto-claim with the user themselves. If someone moves from the office to the shop floor, someone has to remember to replace E3 with F3. If they leave, someone has to release the licence, preferably in the right order: see licences when employees leave.

If you manage this for several customers as an MSP, the same applies per tenant. That is covered in Microsoft 365 licences for MSPs.