Microsoft Entra ID - Atualizando usuários em lote

Ola pessoALL,
Esses dias recebi um pedido de ajuda que parecia simples, mas acabou se mostrando um pouquinho chato de fazer e vou documentar aqui caso alguém necessite no futuro.

Um dos nossos clientes estava com uma demanda de atualizar uma série de usuários no AD do Azure (agora chamado de Entra ID, que por sinal é um nome bem ruim... auauhauahauh) via CSV.

Bom, achei que era uma tarefa simples, iria escrever um script com powershell, importar o CSV e atualizar os registros utilizando o CMDLET no powershell.
Até aqui tudo tranquilo e funcionou na primeira tentativa, mas os problemas começaram de fato quando precisávamos lidar com campos sem informações, o CMDLET não se comporta bem ao enviar uma string vazia como parâmetro.

Após algumas pesquisas e bastante tentativas e erros acabei optando por usar um caminho diferente que compartilho aqui com vocês, passamos a usar o Microsoft Graph para gerenciar os usuários e manipular o arquivo via json.

Arquivo json

O arquivo é bem simples e lista as propriedades que desejamos atualizar, cada usuário vai ser serializado e enviado em uma requisição http.

[
    {
        "userPrincipalName": "email@dominio.com",
        "companyName": "AzureBrasil.cloud",
        "department": "IT",
        "jobTitle": "CEO",
        "businessPhones": [],
        "mobilePhone": null,
        "city": "Serra",
        "state": "ES",
        "country": "BR",
        "preferredLanguage": "pt-BR"
    }
]

A lista de todas as propriedades que podem ser atualizadas pode ser obtida no link a seguir:

Update user - Microsoft Graph v1.0

Update the properties of a user object.

Microsoft Learnyyuank

Script

O script é bem simples, o "truque" é utilizar o método Invoke-GraphRequest ao invés do Update-MgUser para ter um melhor controle sobre a serialização das propriedades.

# if not already, install msgraph powershell module
# https://learn.microsoft.com/en-us/powershell/microsoftgraph/installation?view=graph-powershell-1.0

# Authenticate with an Admin account for the required permissions
Connect-MgGraph -Scopes "User.ReadWrite.All", "Group.ReadWrite.All"

# Get JSON content
$jsonUsers = Get-Content -Raw -Path .\users.json  | ConvertFrom-Json

# Loop trough JSON records
foreach ($record in $jsonUsers) {
   # Gets an user by email
   $userMail = $record.UserPrincipalName
   $user = Get-MgUser -Filter "mail eq '$userMail'"
   
   if ($user) {
      try {
         # Update-MgUser has an issue handling null and empty values so we need to use Invoke-GraphRequest
         # For a list of all possible properties https://learn.microsoft.com/en-us/graph/api/user-update?view=graph-rest-1.0&tabs=http

         $bodyContent = $record | ConvertTo-Json
         Invoke-GraphRequest -Method PATCH `
            -Uri "https://graph.microsoft.com/v1.0/Users/$($user.UserPrincipalName)" `
            -Body $bodyContent
      }
      catch {
         Write-Warning "$userMail user found, but FAILED to update."
         Write-Debug $record
         Write-Error $_
      }
   }
   else {
      Write-Warning "$userMail not found, skipped"
   }
}

Com isso podemos facilitar tarefas de gerenciamento de usuários no dia a dia utilizando o powershell.

Espero que tenham gostado!
[]s