Microsoft 365 / Microsoft Graph PowerShell: exportar usuários para CSV e gerenciar licenças

O Microsoft Graph PowerShell permite que você consulte usuários do Microsoft 365 e automatize a administração de contas e licenças. Comece instalando os módulos necessários → conectando-se com permissões de leitura → confirmando a organização alvo → exportando usuários para um arquivo CSV (valores separados por vírgula). O exercício somente leitura e os exemplos de alteração de conta ou licença abaixo exigem permissões diferentes e têm efeitos diferentes, portanto, execute-os separadamente.

O que é o Microsoft Graph PowerShell?

Microsoft Graph é uma API (Interface de Programação de Aplicações, uma interface para comunicação entre programas) que gerencia dados do Microsoft Entra ID, Teams, SharePoint e mais. O Graph PowerShell SDK (Kit de Desenvolvimento de Software) permite que você use essa API através de comandos do PowerShell. O nome atual do serviço de diretório, anteriormente referido como Azure Active Directory ou Azure AD em documentos mais antigos, é Microsoft Entra ID.

Instalar o Graph não significa que você pode usar todos os comandos de gerenciamento do Microsoft 365. Algumas tarefas, como os comandos de gerenciamento específicos do Exchange Online, exigem módulos e conexões separados. Este artigo aborda Autenticação Delegada Interativa usando o módulo Microsoft Graph v1.0. A autenticação apenas de aplicativo para tarefas agendadas sem supervisão requer considerações de design separadas, como permissões de aplicativo e certificados, e é diferente de executar tarefas agendadas usando os mesmos exemplos de login de usuário.

Requisitos e Instalação do Módulo

A Microsoft recomenda PowerShell 7 ou posterior. Execute os seguintes exercícios em um ambiente PowerShell 7 compatível. O Windows PowerShell 5.1 requer .NET Framework, PowerShellGet e outros pré-requisitos separados, e os módulos instalados em uma versão não são automaticamente instalados em outra versão. Primeiro, verifique os requisitos de instalação do SDK.

  1. Abra o PowerShell em um PC de administração aprovado pela organização. Verifique sua versão com $PSVersionTable.PSVersion.
  2. No centro de administração do Microsoft Entra, verifique o ID de locatário de destino em Entra ID → Overview. Isso é especialmente importante se sua conta tiver acesso a várias organizações.
  3. Confirme o consentimento do administrador para permissões do Graph e seu próprio papel administrativo. Use a conta corporativa ou escolar da sua organização em vez de uma conta pessoal comum da Microsoft.
  4. Crie uma pasta restrita para armazenar os arquivos de resultado. Como a lista de usuários contém nomes e endereços de conta, não use armazenamento público ou pastas web públicas.

Para instalar apenas os módulos necessários para o escopo de usuário atual, execute da seguinte forma. Se aparecer uma mensagem de confirmação de instalação, verifique o repositório e os pacotes. Também é possível instalar o módulo completo Microsoft.Graph, mas para este exercício, os submódulos abaixo são suficientes.

Install-Module -Name Microsoft.Graph.Authentication,Microsoft.Graph.Users,Microsoft.Graph.Identity.DirectoryManagement,Microsoft.Graph.Users.Actions -Scope CurrentUser -Repository PSGallery

Após a instalação, verifique as versões e nomes de comando disponíveis usando o seguinte comando. Nesta etapa, não há conexão com dados organizacionais.

Get-Module -ListAvailable Microsoft.Graph.Authentication,Microsoft.Graph.Users,Microsoft.Graph.Identity.DirectoryManagement,Microsoft.Graph.Users.Actions | Select-Object Name,Version
Get-Command Connect-MgGraph,Get-MgUser,Get-MgSubscribedSku,Set-MgUserLicense

Se módulos ou scripts estiverem bloqueados devido à política de execução, primeiro verifique a seção de política de execução. Não trate um erro de política como um problema, como um erro de permissão 403.

Distinguindo permissões de conexão e funções de administrador

Autenticação delegada é um método que funciona em nome do usuário logado. -Scopes é o escopo de permissão do Graph solicitado pelo aplicativo, e também deve atender ao escopo de função/objetivo do administrador logado e ao consentimento do administrador. Apenas escrever um nome em -Scopes não aprova automaticamente essa permissão nem cria uma função de administrador.

Tarefas Permissões do Graph solicitadas no exemplo Verificações adicionais
Visualizar lista de usuários e atributos especificados User.Read.All Consentimento do administrador e limitação de atributos a serem consultados
Consultar SKUs de assinatura e licenças de usuários LicenseAssignment.Read.All Funções suportadas pela API, como Leitores de Diretório
Criar usuários na nuvem User.Create Consentimento de administrador e permissões e alvos de gerenciamento de usuários
Atribuir e revogar licenças LicenseAssignment.ReadWrite.All Funções suportadas, como Administrador de Licenças

Para prática de leitura, não é necessário solicitar permissões de modificação de grupo ou permissões completas de escrita no diretório. Permissões delegadas versus permissões de aplicativo e requisitos de consentimento do administrador podem ser verificados em Referência de permissões do Microsoft Graph.

Para testar comandos de consulta individuais, conecte-se conforme mostrado abaixo. O ID do locatário que você inserir deve ser o valor real confirmado em sua organização e, após o login, verifique Account·TenantId·Scopes. O método de login pode usar um navegador ou janela de autenticação do Windows, dependendo da versão instalada e do ambiente.

$tenantId = Read-Host 'ID do locatário de destino'
Connect-MgGraph -TenantId $tenantId -Scopes 'User.Read.All' -ContextScope Process
Get-MgContext | Select-Object Account,TenantId,AuthType,Scopes

-ContextScope Process limita o contexto de autenticação ao processo atual do PowerShell. Quando Connect-MgGraph for chamado sem escopos explícitos, inspecione o contexto real ao invés de presumir que sua permissão é sempre User.Read. Para alterar contas ou escopos, execute Disconnect-MgGraph e reconecte-se com os escopos necessários. Veja o Guia de autenticação do Graph PowerShell.

Exemplo completo de pesquisa de usuário e salvamento em CSV

Get-MgUser -All recupera continuamente listas de usuários retornadas em páginas. No entanto, isso não significa que ele receba automaticamente todas as propriedades. Select-Object * apenas expande as propriedades de objetos já recebidos, e valores não incluídos no retorno padrão devem ser solicitados ao servidor com -Property. Essa diferença é explicada em Descrição do Get-MgUser.

Salve o seguinte código completo como UTF-8 com m365-users-report.ps1. O script lê informações de usuários, cria um CSV com timestamps na mesma pasta e desconecta a sessão. Ele não altera contas ou licenças. Se você já fez prática de conexão anterior, primeiro termine-a com Disconnect-MgGraph e então execute este script.

param(
    [Parameter(Mandatory)]
    [Guid]$TenantId
)

$ErrorActionPreference = 'Stop'
$connected = $false
$file = Join-Path $PSScriptRoot ("m365-users-{0}.csv" -f (Get-Date -Format 'yyyyMMdd-HHmmss'))

try {
    Connect-MgGraph -TenantId $TenantId.ToString() -Scopes 'User.Read.All' -ContextScope Process -NoWelcome
    $connected = $true
    $context = Get-MgContext
    if ($context.TenantId -ne $TenantId.ToString()) {
        throw 'O locatário conectado não corresponde ao solicitado.'
    }

    $properties = 'Id','DisplayName','UserPrincipalName','Mail','AccountEnabled','UsageLocation','AssignedLicenses'
    $users = @(Get-MgUser -All -Property $properties)
    if ($users.Count -eq 0) {
        throw 'Nenhum usuário retornado. Verifique a conexão e as permissões.'
    }
    $report = @($users | Select-Object Id,DisplayName,UserPrincipalName,Mail,AccountEnabled,UsageLocation,
        @{Name='AssignedSkuCount';Expression={ @($_.AssignedLicenses | Where-Object { $null -ne $_ }).Count }})

    $report | Export-Csv -Path $file -NoTypeInformation -Encoding utf8BOM -NoClobber
    Write-Host ("Salvo: {0} / Número de usuários: {1}" -f $file, $report.Count)
    $report | Select-Object -First 5 | Format-Table DisplayName,UserPrincipalName,AssignedSkuCount -AutoSize
}
finally {
    if ($connected) {
        Disconnect-MgGraph -ErrorAction SilentlyContinue | Out-Null
    }
}

Após mover-se para a pasta onde o arquivo está localizado no PowerShell, execute da seguinte forma. Ajuste o caminho do arquivo para o local onde ele está realmente salvo e cole o ID do locatário da sua organização no campo de entrada.

$targetTenant = Read-Host 'ID do locatário de destino'
.\m365-users-report.ps1 -TenantId $targetTenant

Se for bem-sucedido, o caminho do CSV e o número de usuários serão exibidos, e os cinco primeiros usuários serão mostrados na tela. Compare o número de linhas no arquivo com o número de usuários na tela e verifique o nome de exibição, endereço de login, local de uso e licença de uma conta de teste conhecida no centro de administração. AssignedSkuCount representa o número de SKUs de produto atribuídos, não o número de serviços individuais ou licenças adquiridas.

Mesmo que existam usuários com um Mail vazio, não assuma imediatamente falha na consulta. O nome de login, UserPrincipalName, e o endereço de e-mail são atributos diferentes. Mesmo que AccountEnabled seja verdadeiro, o login ou uso real do serviço pode estar restrito devido a licenças, políticas ou avaliações de risco. Não conclua apenas com base neste relatório que um usuário tenha feito login recentemente ou esteja realizando trabalho normalmente.

Se nenhum resultado for retornado ou a geração do CSV falhar, não marque como concluído. Verifique permissões para o caminho de saída, arquivos com o mesmo nome, bloqueios de arquivo e mensagens de erro. Como o relatório reflete os resultados da consulta no momento da execução, se contas tiverem sido alteradas, execute-o novamente para comparação e gerencie os arquivos anteriores de acordo com a política de retenção da sua organização.

Consultando produtos licenciados e atribuições de usuários

SKU (Stock Keeping Unit, identificador de produto) é a unidade usada aqui para diferenciar produtos licenciados. SkuPartNumber é a string de identificação do produto, e SkuId é o identificador global exclusivo do produto (GUID) usado nos comandos do Graph. Ao alterar a atribuição de um usuário, diferencie para que você não insira o ID do objeto de assinatura ou ID do plano de serviço em vez do ID do SKU.

O script CSV completo se desconecta no final, então ao executar os comandos individuais abaixo, reconecte a cada vez. Além de permissões de leitura, a função suportada por essa operação é necessária para consultar SKUs de assinatura. Verifique Funções e Permissões para Consulta de SKU de Assinatura.

$tenantId = Read-Host 'ID do locatário de destino'
Connect-MgGraph -TenantId $tenantId -Scopes 'User.Read.All','LicenseAssignment.Read.All' -ContextScope Process
Get-MgContext | Select-Object Account,TenantId,Scopes
Get-MgSubscribedSku -All | Select-Object SkuPartNumber,SkuId,CapabilityStatus,ConsumedUnits,@{Name='EnabledUnits';Expression={$_.PrepaidUnits.Enabled}}

$userId = Read-Host 'Nome principal de usuário (UPN) ou ID de objeto a consultar'
Get-MgUserLicenseDetail -UserId $userId -All | Select-Object SkuPartNumber,SkuId,ServicePlans

ConsumedUnits é o número de licenças consumidas, e PrepaidUnits.Enabled são as unidades disponibilizadas. Como pode haver estados suspensos, de aviso e condições do produto, não interprete imediatamente a diferença simples como a quantidade faturada ou os licenças disponíveis para todos os produtos. Detalhes reais de compra e faturamento devem ser confirmados separadamente através do Procedimento de Reconciliação de Assinatura, Faturamento e Quantidade de Licença.

Get-MgUserLicenseDetail inclui licenças atribuídas diretamente e herdadas de grupos. Você não pode distinguir a causa da atribuição apenas a partir deste resultado. Para atribuições baseadas em grupo, verifique adicionalmente o centro de administração ou informações de status de atribuição. No API de Detalhes de Licença de Usuário, você também pode verificar permissões delegadas e funções suportadas.

Execute operações de alteração de usuário e licença separadamente.

O exemplo a seguir mostra uma operação que modifica dados organizacionais. Não a execute em lote imediatamente após o relatório de leitura; reconecte-se com as permissões necessárias após preparar um usuário de teste aprovado e registros antes das alterações. A opção -WhatIf abaixo permite que você visualize a operação que deseja executar e não é um teste simulado que verifica todas as validações do servidor, permissões e condições de licença.

Crie um usuário de teste na nuvem.

Use este método apenas para usuários gerenciados na nuvem. Em uma organização sincronizada, verifique primeiro se as contas devem ser criadas no diretório de origem. Escolha um nome principal de usuário (UPN, o nome de entrada) exclusivo em um domínio verificado no locatário e uma senha temporária que atenda à política. Criar um membro é diferente de convidar um colaborador externo. Consulte os requisitos e permissões da API de criação de usuários, incluindo a permissão mínima User.Create, e confirme a função administrativa e seu escopo.

Disconnect-MgGraph
$tenantId = Read-Host 'ID do locatário de destino'
Connect-MgGraph -TenantId $tenantId -Scopes 'User.Create','User.Read.All' -ContextScope Process
Get-MgContext | Select-Object Account,TenantId,Scopes

$upn = Read-Host 'UPN do usuário de teste a criar (domínio verificado)'
$nickname = Read-Host 'Alias de email (por exemplo, graph-test01)'
$securePassword = Read-Host 'Senha temporária que atenda à política' -AsSecureString
$params = @{
    AccountEnabled = $true
    DisplayName = 'Usuário de teste do Graph'
    UserPrincipalName = $upn
    MailNickname = $nickname
    PasswordProfile = @{
        Password = [System.Net.NetworkCredential]::new('', $securePassword).Password
        ForceChangePasswordNextSignIn = $true
    }
}
try {
    New-MgUser -BodyParameter $params -WhatIf
}
finally {
    $params.PasswordProfile.Password = $null
    Remove-Variable securePassword
}

Após verificar entradas e alvos, para realmente criar o usuário, remova -WhatIf do código e execute-o novamente. Não codifique senhas diretamente em strings de linha de comando ou arquivos de script. Como as solicitações do SDK exigem valores de senha em texto simples, não use a saída de depuração ou o registro do corpo da solicitação para esta tarefa, e entregue senhas temporárias através dos canais aprovados da organização.

Após a criação, verifique a conta novamente usando Get-MgUser -UserId $upn -Property Id,DisplayName,UserPrincipalName,AccountEnabled. Simplesmente criar um usuário não completa automaticamente licenças de aplicativos, caixas de correio ou associações a grupos. Excluir uma conta de teste também requer revisão de dados similar à exclusão de uma conta empresarial. Verifique procedimentos de desligamento e transferência de dados, depois revise e organize o escopo alvo e recuperável no centro de administração.

Remover licenças atribuídas diretamente

Antes de remover uma licença, verifique o usuário, o produto, se foi atribuído diretamente ou por grupo e os requisitos de retenção de dados. Neste exemplo, -RemoveLicenses passa um array de strings de ID de SKU, mas não inclui uma tabela hash no formato @{SkuId=...}. Use -AddLicenses @() junto quando não houver produtos adicionais a adicionar. Verifique a sintaxe Set-MgUserLicense.

Disconnect-MgGraph
$tenantId = Read-Host 'ID do locatário de destino'
Connect-MgGraph -TenantId $tenantId -Scopes 'LicenseAssignment.ReadWrite.All' -ContextScope Process
Get-MgContext | Select-Object Account,TenantId,Scopes

$userId = Read-Host 'UPN ou ID de objeto do usuário para remoção da licença'
$skuId = [Guid](Read-Host 'SkuId verificado da licença a remover')
Set-MgUserLicense -UserId $userId -AddLicenses @() -RemoveLicenses @($skuId.ToString()) -WhatIf

Faça a alteração após aprovação e verificação do usuário de destino, removendo -WhatIf. São necessários tanto o consentimento para LicenseAssignment.ReadWrite.All quanto uma função compatível, como Administrador de licenças. Para licenças herdadas de um grupo, revise a atribuição do grupo; a remoção direta do usuário não substitui esse gerenciamento. Consulte as permissões, funções e formato da solicitação da API de atribuição de licenças.

Após a alteração, reconecte-se com as permissões de leitura necessárias e compare os detalhes da licença com o centro de gerenciamento. Durante a reversão, você precisa verificar os licenças disponíveis, locais de uso e planos de serviço previamente desabilitados para reatribuir à configuração original. Não presuma que reatribuir a licença desfará todas as exclusões de dados executadas anteriormente. É importante concluir a retenção e a transferência dos dados antes de remover a licença.

Verifique a política de execução do Windows e realize a reversão

Políticas de execução são condições para a execução de scripts e módulos. Se ocorrer um erro de bloqueio no Windows, verifique a política efetiva e os valores por escopo.

Get-ExecutionPolicy
Get-ExecutionPolicy -List

Somente se a política organizacional permitir e o escopo do usuário atual precisar de alterações, registre os valores anteriores e revise RemoteSigned. Se as configurações já forem permitidas, não as altere apenas para coincidir com o formato. Se MachinePolicy e UserPolicy da política de grupo organizacional tiverem precedência, consulte a pessoa responsável e não contorne.

$previousUserPolicy = Get-ExecutionPolicy -Scope CurrentUser
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
Get-ExecutionPolicy -List

Para restaurar o valor original ao terminar, execute o comando abaixo na mesma sessão. Se usar uma nova janela, informe o valor real registrado anteriormente. RemoteSigned não torna confiável todo código recebido da internet. Consulte os escopos e a prioridade das políticas de execução.

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy $previousUserPolicy

Erros comuns e encerramento de tarefas

Sintomas Sequência de Verificação
Comando Não Reconhecido Verifique a versão em execução do PowerShell e a localização da instalação do módulo. Get-MgUser está em Microsoft.Graph.Users. Use Get-Command para localizar o comando e diferenciar erros de instalação e de importação.
403 ou Privilégios Insuficientes Verifique a conta conectada, o tenant, os escopos, o consentimento do administrador e as funções suportadas para a API. Não adicione permissões de escrita completas por padrão.
Não é Possível Encontrar Usuário ou Objeto Verifique a organização e o UPN/ID do objeto, bem como o status de exclusão/sincronização. Certifique-se de que o nome da conta não seja de outro tenant.
A Propriedade Está Vazia Diferencie se a propriedade foi solicitada com -Property, se a conta realmente possui um valor e se a propriedade requer permissões separadas.
Login Bloqueado Registre códigos de erro e carimbos de data/hora, e verifique acesso condicional, autenticação multifator (MFA), métodos de autenticação permitidos e registros de login. Não desative políticas de segurança para login bem-sucedido.

Registrar a versão da instalação, erros detalhados de comando, ID de solicitação e horário de ocorrência juntos pode ajudar na reprodução e em solicitações de suporte. Mesmo ao usar o método em diagnóstico de erros do Graph PowerShell, não compartilhe logs contendo tokens, senhas ou informações pessoais tal como estão.

Após concluir os exercícios de comando individuais, desconecte-se e verifique o local de armazenamento dos arquivos de resultado. Fazer logout é diferente de desfazer alterações de conta ou licença que já foram realizadas.

Disconnect-MgGraph