Como registrar um App no Entra ID para acessar o Microsoft Graph via PowerShell

Neste post, vamos abordar as etapas para registrar um App no Entra ID, visando estabelecer uma autenticação segura para extrair informações do Microsoft Graph usando PowerShell.
Como exemplo prático, ao final, iremos utilizar um script para listar e exportar (em CSV) os dispositivos registrados no Intune.

Criar e Configurar App

Registrar App

• Acesse https://portal.azure.com e, em seguida, pesquise por “App Registration“.

• Adicione o nome do App e, em seguida, clique em Register

Configurar Client Secret

1. No menu lateral esquedo, clique em Certificates & secrets.
2. Clique em New client secret.
3. Adicione uma descrição para secret.
4. Escolha o tempo de expiração.
5. Clique em Add.

API Permissions

Nesta etapa, adicionaremos as permissões de API ao aplicativo. No exemplo prático, faremos uma consulta dos dispositivos registrados no Intune. Nesse contexto, selecione as permissões listadas abaixo.

• DeviceManagementManagedDevices.Read.All
• DeviceManagementManagedDevices.ReadWrite.All

Para obter informações adicionais sobre as permissões, consulte a documentação disponível aqui.

Siga as etapas a seguir para concluir a adição das permissões.

1. No menu, vá até API Permissions.
2. Clique em Add a permission.
3. Selecione Microsoft Graph.
4. Clique em Application permission.
   Saiba a mais sobre os dois tipos de cenarios de acesso aqui.
5. Adicione as permissões necessárias.
6. Clique em Add permissions.

Por fim, clique em Grant admin consent.

Demonstração

Como mencionado previamente, faremos uso do App Registrations criado para consultar, por meio do PowerShell, informações sobre os dispositivos registrados no Intune.

Script Powershell

<#
    .DESCRIPTION
        Listar equipamentos registrados no Intune

    .NOTES
        Criado por: Thiago Rufino
        thiagorufino.com

        Data: 20/10/2023
        Version: 1.0
#>

# Define as informações de autenticação do aplicativo no Azure AD
$clientId = "Adicione o valor do Application (client) ID"
$clientSecret = "Adicione o valor do client secret"
$tenantId = "Adicione o valor do Directory (tenant) ID"

$authUrl = "https://login.microsoftonline.com/$tenantId/oauth2/token"

$body = @{
    grant_type    = "client_credentials"
    client_id     = $clientId
    client_secret = $clientSecret
    resource      = "https://graph.microsoft.com"
}

$tokenResponse = Invoke-RestMethod -Method Post -Uri $authUrl -Body $body
$accessToken = $tokenResponse.access_token

$apiUrl = "https://graph.microsoft.com/v1.0/deviceManagement/managedDevices"

$headers = @{
    "Authorization" = "Bearer $accessToken"
    "Content-Type"  = "application/json"
}

# Obtém informações do dispositivos
$Devices = Invoke-RestMethod -Method Get -Uri $apiUrl -Headers $headers

# Gera o nome do arquivo CSV com base na data e hora atual
$dateTime = Get-Date -Format "dd-MM-yyyy-HH-mm-ss"
$csvFileName = "intune-devices-$dateTime.csv"

# Caminho do arquivo CSV de destino
$csvFilePath = "C:\Temp\$csvFileName"

# Função para converter bytes para gigabytes
function Convert-ToGB {
    param (
        [long]$Bytes
    )
    return "$([math]::Round($Bytes / 1GB, 2)) GB"
}

# Cor do Cabeçalho (Windows Powershell 7.2+)
$psstyle.Formatting.TableHeader = "`e[36;1m"
$psstyle.Formatting.FormatAccent = "`e[36;1m"


# Cria um array para armazenar os objetos
$csvData = @()

# Retorna as informações dos dispositivos e adiciona ao array
$devices.value | ForEach-Object {
    $deviceInfo = [PSCustomObject]@{
        DeviceName           = $_.deviceName
        ComplianceState      = $_.complianceState
        UserDisplayName      = $_.userDisplayName
        UserPrincipalName    = $_.userPrincipalName
        Manufacturer         = $_.manufacturer
        Model                = $_.model
        SerialNumber         = $_.serialNumber
        EnrolledDateTime     = (Get-Date $_.enrolledDateTime).ToString("dd/MM/yyyy hh:mm:ss")
        LastSyncDateTime     = (Get-Date $_.lastSyncDateTime).ToString("dd/MM/yyyy hh:mm:ss")
        OperatingSystem      = $_.operatingSystem
        OSVersion            = $_.osVersion
        DeviceEnrollmentType = $_.deviceEnrollmentType
        IsEncrypted          = $_.isEncrypted
        DiskSpaceTotal       = Convert-ToGB -Bytes $_.totalStorageSpaceInBytes
        DiskSpaceFree        = Convert-ToGB -Bytes $_.freeStorageSpaceInBytes
        Id                   = $_.id
        AzureADDeviceId      = $_.azureADDeviceId
    }

    $csvData += $deviceInfo
}

# Exporta o array para um arquivo CSV
$csvData | Export-Csv -Path $csvFilePath -NoTypeInformation

# Mostra as informações dos dispositivos
$csvData

Informações de Autenticação

Inclua as informações coletadas durante o processo de criação do App Registrations nas linhas 14, 15 e 16 do script.

Resultado

O script será responsável por listar diversas informações dos dispositivos. Você pode personalizá-lo incluindo outros campos suportados. Um exemplo desses campos está disponível no link a seguir: List managedDevices – Microsoft Graph v1.0 | Microsoft Learn

Também será gerado um arquivo CSV no diretório C:\Temp com essas informações. Você pode personalizar o diretório na linha 45.

Referência

Para obter informações detalhadas sobre o Microsoft Graph e explorar outros recursos, confira os links abaixo:

Microsoft Graph overview – Microsoft Graph | Microsoft Learn
Microsoft Graph REST API v1.0 endpoint reference – Microsoft Graph v1.0 | Microsoft Learn
Microsoft Graph REST API beta endpoint reference – Microsoft Graph beta | Microsoft Learn