Exemplos de licenciamento baseado em grupo do Microsoft Graph PowerShell
O licenciamento baseado em grupo no Microsoft Entra ID, parte do Microsoft Entra, está disponível através do portal do Azure. Há tarefas úteis que podem ser executadas usando cmdlets do Microsoft Graph PowerShell.
Neste artigo, abordaremos alguns exemplos usando o Microsoft Graph PowerShell.
Nota
Os módulos Azure AD e MSOnline PowerShell foram preteridos a partir de 30 de março de 2024. Para saber mais, leia a atualização de descontinuação. Após essa data, o suporte para esses módulos é limitado à assistência de migração para o SDK do Microsoft Graph PowerShell e correções de segurança. Os módulos preteridos continuarão a funcionar até 30 de março de 2025.
Recomendamos migrar para o Microsoft Graph PowerShell para interagir com o Microsoft Entra ID (anteriormente Azure AD). Para perguntas comuns sobre migração, consulte as Perguntas frequentes sobre migração. Nota: As versões 1.0.x do MSOnline podem sofrer interrupções após 30 de junho de 2024.
Nota
À medida que as APIs do Azure AD Graph estão sendo desativadas, também estamos desativando a operação de atribuição de licença nos módulos MSOnline e Azure AD PowerShell. Recomendamos que você atualize os aplicativos existentes para acessar as APIs de atribuição de licença do ponto de extremidade do Microsoft Graph e atualize seus scripts para usar o módulo PowerShell do Microsoft Graph para reduzir o impacto nas operações. Outras operações nos módulos MSOnline e Azure AD PowerShell não serão afetadas.
Aviso
Estas amostras são fornecidas apenas para fins de demonstração. Recomendamos testá-los em uma escala menor ou em um ambiente de teste separado antes de confiar neles em seu ambiente de produção. Também pode ser necessário modificar as amostras para atender aos requisitos específicos do seu ambiente.
Antes de começar a executar cmdlets, certifique-se de se conectar à sua organização primeiro, executando o Connect-MgGraph cmdlet-.
Atribuir licenças a um grupo
O licenciamento baseado em grupo fornece uma maneira conveniente de gerenciar a atribuição de licenças. Você pode atribuir uma ou mais licenças de produto a um grupo e essas licenças são atribuídas a todos os membros do grupo.
# Import the Microsoft.Graph.Groups module
Import-Module Microsoft.Graph.Groups
$groupId = "911f05cf-f635-440c-b888-e54c73e0ef1a"
# Create a hashtable to store the parameters for the Set-MgGroupLicense cmdlet
$params = @{
AddLicenses = @(
@{
# Remove the DisabledPlans key as we don't need to disable any service plans
# Specify the SkuId of the license you want to assign
SkuId = "c42b9cae-ea4f-4ab7-9717-81576235ccac"
}
)
# Keep the RemoveLicenses key empty as we don't need to remove any licenses
RemoveLicenses = @(
)
}
# Call the Set-MgGroupLicense cmdlet to update the licenses for the specified group
# Replace $groupId with the actual group ID
Set-MgGroupLicense -GroupId $groupId -BodyParameter $params
Ver licenças de produtos atribuídas a um grupo
Get-MgGroup -GroupId 99c4216a-56de-42c4-a4ac-1111cd8c7c41 -Property "AssignedLicenses" | Select-Object -ExpandProperty AssignedLicenses
Ver todas as licenças de plano de serviço desativadas atribuídas a um grupo
Get-MgGroup -GroupId 1ad75eeb-7e5a-4367-a493-9214d90d54d0 -Property "AssignedLicenses" |
Select-Object -ExpandProperty AssignedLicenses |
ForEach-Object {
$_ | Select-Object SkuId, DisabledPlans
}
Obter todos os grupos com licenças
# Import the Microsoft.Graph.Groups module
Import-Module Microsoft.Graph.Groups
# Get all groups and licenses
$groups = Get-MgGroup -All
$groupsWithLicenses = @()
# Loop through each group and check if it has any licenses assigned
foreach ($group in $groups) {
$licenses = Get-MgGroup -GroupId $group.Id -Property "AssignedLicenses, Id, DisplayName" | Select-Object AssignedLicenses, DisplayName, Id
if ($licenses.AssignedLicenses) {
$groupData = [PSCustomObject]@{
ObjectId = $group.Id
DisplayName = $group.DisplayName
Licenses = $licenses.AssignedLicenses
}
$groupsWithLicenses += $groupData
}
}
Obter estatísticas para grupos com licenças
# Import User Graph Module
Import-Module Microsoft.Graph.Users
# Authenticate to MS Graph
Connect-MgGraph -Scopes "User.Read.All", "Directory.Read.All", "Group.ReadWrite.All"
#get all groups with licenses
$groups = Get-MgGroup -All -Property LicenseProcessingState, DisplayName, Id, AssignedLicenses | Select-Object displayname, Id, LicenseProcessingState, AssignedLicenses | Select-Object DisplayName, Id, AssignedLicenses -ExpandProperty LicenseProcessingState | Select-Object DisplayName, State, Id, AssignedLicenses | Where-Object {$_.State -eq "ProcessingComplete"}
$groupInfoArray = @()
# Filter the groups to only include those that have licenses assigned
$groups = $groups | Where-Object {$_.AssignedLicenses -ne $null}
# For each group, get the group name, license types, total user count, licensed user count, and license error count
foreach ($group in $groups) {
$groupInfo = New-Object PSObject
$groupInfo | Add-Member -MemberType NoteProperty -Name "Group Name" -Value $group.DisplayName
$groupInfo | Add-Member -MemberType NoteProperty -Name "Group ID" -Value $group.Id
$groupInfo | Add-Member -MemberType NoteProperty -Name "License Types" -Value ($group.AssignedLicenses | Select-Object -ExpandProperty SkuId)
$groupInfo | Add-Member -MemberType NoteProperty -Name "Total User Count" -Value (Get-MgGroupMember -GroupId $group.Id -All | Measure-Object).Count
$groupInfo | Add-Member -MemberType NoteProperty -Name "Licensed User Count" -Value (Get-MgGroupMember -GroupId $group.Id -All | Where-Object {$_. LicenseProcessingState -eq "ProcessingComplete"} | Measure-Object).Count
$groupInfo | Add-Member -MemberType NoteProperty -Name "License Error Count" -Value (Get-MgGroupMember -GroupId $group.Id -All | Where-Object {$_.LicenseProcessingState -eq "ProcessingFailed"} | Measure-Object).Count
$groupInfoArray += $groupInfo
}
# Format the output and print it to the console
$groupInfoArray | Format-Table -AutoSize
Obter todos os grupos com erros de licença
# Import User Graph Module
Import-Module Microsoft.Graph.Users
# Authenticate to MS Graph
Connect-MgGraph -Scopes "Group.Read.All"
# Get all groups in the tenant with license assigned and with errors
$groups = Get-MgGroup -All -Property LicenseProcessingState, DisplayName, Id, AssignedLicenses | Select-Object displayname, Id, LicenseProcessingState, AssignedLicenses | Select-Object DisplayName, Id, AssignedLicenses -ExpandProperty LicenseProcessingState | Select-Object DisplayName, State, Id, AssignedLicenses | Where-Object {$_.State -eq "ProcessingFailed" -and $_.AssignedLicenses -ne $null }
# Display the results and format output
$groups | Format-Table -AutoSize
Obter todos os usuários com erros de licença em um grupo
Dado um grupo que contém alguns erros relacionados à licença, agora você pode listar todos os usuários afetados por esses erros. Um usuário também pode ter erros de outros grupos. No entanto, neste exemplo, limitamos os resultados apenas a erros relevantes para o grupo em questão, verificando a propriedade ReferencedObjectId de cada entrada IndirectLicenseError no usuário.
# Import User Graph Module
Import-Module Microsoft.Graph.Users
# Authenticate to MS Graph
Connect-MgGraph -Scopes "Group.Read.All", "User.Read.All"
# Get all groups in the tenant with license assigned
$groups = Get-MgGroup -All -Property LicenseProcessingState, DisplayName, Id, AssignedLicenses | Select-Object displayname, Id, LicenseProcessingState, AssignedLicenses | Select-Object DisplayName, Id, AssignedLicenses | Where-Object {$_.AssignedLicenses -ne $null }
#output array
$groupInfoArray = @()
# Get All Members from the groups and check their license status
foreach($group in $groups) {
$groupMembers = Get-MgGroupMember -GroupId $group.Id -All -Property LicenseProcessingState, DisplayName, Id, AssignedLicenses | Select-Object displayname, Id, LicenseProcessingState, AssignedLicenses | Select-Object DisplayName, Id, AssignedLicenses -ExpandProperty LicenseProcessingState | Select-Object DisplayName, Id, AssignedLicenses | Where-Object {$_.AssignedLicenses -ne $null }
foreach($member in $groupMembers) {
Write-Host "Member $($member.DisplayName)"
if($member.LicenseProcessingState -eq "ProcessingFailed") {
$group | Add-Member -MemberType NoteProperty -Name "License Error" -Value $member.DisplayName
$groupInfoArray += $group
}
}
}
# Format the output and print it to the console
if ($groupInfoArray.Length -gt 0) {
$groupInfoArray | Format-Table -AutoSize
}
else {
Write-Host "No License Errors"
}
Obter todos os usuários com erros de licença em toda a organização
O script a seguir pode ser usado para obter todos os usuários que têm erros de licença de um ou mais grupos. O script imprime uma linha por usuário, por erro de licença, o que permite identificar claramente a origem de cada erro.
# Import User Graph Module
Import-Module Microsoft.Graph.Users
# Authenticate to MS Graph
Connect-MgGraph -Scopes "User.Read.All"
# Get All Users From the Tenant with licenses assigned
$users = Get-MgUser -All -Property AssignedLicenses, LicenseAssignmentStates, DisplayName | Select-Object DisplayName, AssignedLicenses -ExpandProperty LicenseAssignmentStates | Select-Object DisplayName, AssignedByGroup, State, Error, SkuId
#count the number of users found with errors
$count = 0
# Loop through each user and check the Error property for None value
foreach($user in $users) {
if($user.Error -ne "None") {
$count += 1
Write-Host "User $($user.DisplayName) has a license error"
}
}
if ($count -le 0) {
write-host "No user found with license errors"
}
Verificar se a licença de usuário é atribuída diretamente ou herdada de um grupo
# Connect to Microsoft Graph using Connect-MgGraph
Connect-MgGraph -Scopes "User.Read.All"
# Get all users using Get-MgUser with a filter
$users = Get-MgUser -All -Property AssignedLicenses, LicenseAssignmentStates, DisplayName | Select-Object DisplayName, AssignedLicenses -ExpandProperty LicenseAssignmentStates | Select-Object DisplayName, AssignedByGroup, State, Error, SkuId
$output = @()
# Loop through all users and get the AssignedByGroup Details which will list the groupId
foreach ($user in $users) {
# Get the group ID if AssignedByGroup is not empty
if ($user.AssignedByGroup -ne $null)
{
$groupId = $user.AssignedByGroup
$groupName = Get-MgGroup -GroupId $groupId | Select-Object -ExpandProperty DisplayName
Write-Host "$($user.DisplayName) is assigned by group - $($groupName)" -ErrorAction SilentlyContinue -ForegroundColor Yellow
$result = [pscustomobject]@{
User=$user.DisplayName
AssignedByGroup=$true
GroupName=$groupName
GroupId=$groupId
}
$output += $result
}
else {
$result = [pscustomobject]@{
User=$user.DisplayName
AssignedByGroup=$false
GroupName="NA"
GroupId="NA"
}
$output += $result
Write-Host "$($user.DisplayName) is Not assigned by group" -ErrorAction SilentlyContinue -ForegroundColor Cyan
}
}
# Display the result
$output | ft
Remover licenças diretas para usuários com licenças de grupo
O objetivo deste script é remover licenças diretas desnecessárias de usuários que já herdam a mesma licença de um grupo; por exemplo, como parte de uma transição para o licenciamento baseado em grupo.
Nota
Para garantir que os usuários não percam o acesso a serviços e dados, é importante confirmar que as licenças atribuídas diretamente não fornecem mais funcionalidade de serviço do que as licenças herdadas. Atualmente, não é possível usar o PowerShell para determinar quais serviços são habilitados por meio de licenças herdadas versus licenças diretas. Portanto, o script usa um nível mínimo de serviços que são conhecidos por serem herdados de grupos para verificar e garantir que os usuários não tenham perda de serviço inesperada.
# Import the Microsoft.Graph.Users and Microsoft.Graph.Groups modules
Import-Module Microsoft.Graph.Users -Force
Import-Module Microsoft.Graph.Authentication -Force
Import-Module Microsoft.Graph.Users.Actions -Force
Import-Module Microsoft.Graph.Groups -Force
Clear-Host
if ($null -eq (Get-MgContext)) {
Connect-MgGraph -Scopes "Directory.Read.All, User.Read.All, Group.Read.All, Organization.Read.All" -NoWelcome
}
# Get all groups with licenses assigned
$groupsWithLicenses = Get-MgGroup -All -Property AssignedLicenses, DisplayName, Id | Where-Object { $_.assignedlicenses } | Select-Object DisplayName, Id -ExpandProperty AssignedLicenses | Select-Object DisplayName, Id, SkuId
$output = @()
# Check if there is any group that has licenses assigned or not
if ($null -ne $groupsWithLicenses) {
# Loop through each group
foreach ($group in $groupsWithLicenses) {
# Get the group's licenses
$groupLicenses = $group.SkuId
# Get the group's members
$groupMembers = Get-MgGroupMember -GroupId $group.Id -All
# Check if the group member list is empty or not
if ($groupMembers) {
# Loop through each member
foreach ($member in $groupMembers) {
# Check if the member is a user
if ($member.AdditionalProperties.'@odata.type' -eq '#microsoft.graph.user') {
# Get the user's direct licenses
Write-Host "Fetching license details for $($member.AdditionalProperties.displayName)" -ForegroundColor Yellow
# Get User With Directly Assigned Licenses Only
$user = Get-MgUser -UserId $member.Id -Property AssignedLicenses, LicenseAssignmentStates, DisplayName | Select-Object DisplayName, AssignedLicenses -ExpandProperty LicenseAssignmentStates | Select-Object DisplayName, AssignedByGroup, State, Error, SkuId | Where-Object { $_.AssignedByGroup -eq $null }
$licensesToRemove = @()
if($user)
{
if ($user.count -ge 2) {
foreach ($u in $user) {
$userLicenses = $u.SkuId
$licensesToRemove += $userLicenses | Where-Object { $_ -in $groupLicenses }
}
}
else {
$userLicenses = $user.SkuId
$licensesToRemove = $userLicenses | Where-Object { $_ -in $groupLicenses }
}
} else {
Write-Host "No conflicting licenses found for the user $($member.AdditionalProperties.displayName)" -ForegroundColor Green
}
# Remove the licenses from the user
if ($licensesToRemove) {
Write-Host "Removing the license $($licensesToRemove) from user $($member.AdditionalProperties.displayName) as inherited from group $($group.DisplayName)" -ForegroundColor Green
$result = Set-MgUserLicense -UserId $member.Id -AddLicenses @() -RemoveLicenses $licensesToRemove
$obj = [PSCustomObject]@{
User = $result.DisplayName
Id = $result.Id
LicensesRemoved = $licensesToRemove
LicenseInheritedFromGroup = $group.DisplayName
GroupId = $group.Id
}
$output += $obj
}
else {
Write-Host "No action required for $($member.AdditionalProperties.displayName)" -ForegroundColor Green
}
}
}
}
else {
Write-Host "The licensed group $($group.DisplayName) has no members, exiting now!!" -ForegroundColor Yellow
}
}
$output | Format-Table -AutoSize
}
else {
Write-Host "No groups found with licenses assigned." -ForegroundColor Cyan
}
Próximos passos
Para saber mais sobre o conjunto de recursos para gerenciamento de licenças por meio de grupos, consulte os seguintes artigos:
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários