Como usar a Microsoft Graph API para extrair relatórios de conformidade de vários tenants

As ferramentas de segurança e conformidade da Microsoft Graph API são essenciais em qualquer ambiente corporativo. Elas oferecem um endpoint unificado para acessar todos os logs de auditoria, relatórios de DLP, incidentes de alerta e políticas de retenção das contas Microsoft 365 da organização.

Usar essa ferramenta traz vários benefícios: mantém a visibilidade de conformidade entre tenants, automatiza relatórios sem depender de acesso ao portal, oferece um método seguro de autenticação baseada em aplicativo e facilita integrações com SIEM e painéis personalizados.

Como acessar relatórios de conformidade com o Microsoft Graph

Antes de começar, configure o aplicativo no portal do Azure AD e garanta que ele tenha as permissões necessárias. Depois, conecte a conta ao Microsoft Graph pelo Windows PowerShell e gere os relatórios automaticamente. Também dá para automatizar o processo com um arquivo .JSON.

Os GPOs ajudam a reforçar os procedimentos de segurança. Use o Registro do Windows para garantir que todas as políticas sejam aplicadas de forma consistente nos dispositivos gerenciados. E, se algum erro aparecer, recorra ao CMD para diagnosticar.

Pré-requisitos:

• Registro de aplicativo no Azure AD para cada tenant (ou uso do Microsoft Lighthouse, necessário para acesso delegado)
• Consentimento do administrador concedido para os escopos de API exigidos.
• O complemento Microsoft 365 E5 Compliance é necessário para relatórios avançados.
• É preciso ter o Windows PowerShell com o SDK do Microsoft Graph instalado.
• Opcional/recomendado: acesso ao Intune, ao GPO e ao Registro do Windows para validar políticas de endpoint

O vídeo mostra na tela Como usar a Microsoft Graph API para extrair relatórios de conformidade de vários tenants — uma referência útil antes de navegar pelas opções e configurá-las.

Passo 1: registre um aplicativo no Azure para acesso ao Graph

1. Abra o portal do Azure AD no navegador.
2. Vá até App Registrations > New Registration.
3. Dê um nome ao aplicativo que vai registrar.
4. Defina o tipo de conta com acesso como Accounts in this organizational directory only (Contoso only – Single tenant).
5. Em seguida, altere as permissões do aplicativo clicando em Add a permission. Isso leva você ao Microsoft Graph.
6. Conceda as seguintes permissões:
   • Reports.Read.All
   • AuditLog.Read.All
   • SecurityEvents.Read.All
   • Directory.Read.All
7. Clique em Add Permissions.
8. Clique no botão Grant admin consent. Depois disso, o aplicativo já consegue ler todos os perfis de usuário aos quais recebeu acesso.
9. Vá até Certificates & secrets.
10. Selecione Client Secrets > New Client secret.
11. Preencha as informações e siga as instruções. Esse segredo funciona como a senha do aplicativo.
12. Anote o ID do aplicativo (cliente), o ID do diretório (tenant) e o valor do segredo. Com eles, você acessa o aplicativo novamente no futuro.

Repita ou automatize esse processo em cada tenant que precisar dele.

Passo 2: conecte-se ao Microsoft Graph no PowerShell

1. Abra o Menu Iniciar e procure por Windows PowerShell.
2. Clique com o botão direito em Windows PowerShell > Executar como administrador.
3. Para instalar o Microsoft Graph, digite o comando a seguir e pressione Enter:

Install-Module Microsoft.Graph -Scope CurrentUser

Import-Module Microsoft.Graph

4. Para conectar com as credenciais do aplicativo, digite o comando a seguir e pressione Enter:

Connect-MgGraph -ClientId "APP_ID" -TenantId "TENANT_ID" -ClientSecret (ConvertTo-SecureString "SECRET" -AsPlainText -Force)

Troque “APP_ID” pelo ID do cliente, “TENANT_ID” pelo ID do tenant e “SECRET” pelo valor do segredo que você gerou.

5. Para selecionar o escopo, digite Select-MgProfile -Name "beta" e pressione Enter.

Pronto: você está conectado ao Microsoft Graph.

Passo 3: extraia relatórios de conformidade com a Microsoft Graph API

Depois de entrar no Microsoft Graph pelo Windows PowerShell, siga estes passos:

1. Para obter os logs de auditoria, digite este comando e pressione Enter:

$logs = Invoke-MgGraphRequest -Method GET -Uri "https://graph.microsoft.com/beta/auditLogs/signIns"

2. Para listar os alertas de DLP, digite este comando e pressione Enter:

$alerts = Invoke-MgGraphRequest -Method GET -Uri "https://graph.microsoft.com/beta/security/alerts"

3. Para listar as políticas de retenção, digite este comando e pressione Enter:

$policies = Invoke-MgGraphRequest -Method GET -Uri "https://graph.microsoft.com/beta/security/retentionLabels"

4. Para exportar os dados em um arquivo .CSV, digite este comando e pressione Enter:

$logs.value | Export-Csv -Path ".\Tenant_AuditLogs.csv" -NoTypeInformation

Repita o processo em cada tenant, entrando com as credenciais específicas de cada um.

Opcional: automatize os relatórios entre tenants

Os administradores de TI podem guardar todas as credenciais dos tenants em um arquivo JSON. Basta executar esse arquivo para percorrer cada tenant sempre que precisarem conectar-se a eles e consolidar os dados. Também é possível executá-lo automaticamente em uma programação regular com o Agendador de Tarefas, pela ferramenta de gerenciamento de endpoints.

Veja um exemplo de estrutura de laço entre tenants:

foreach ($tenant in $tenantList) {
Connect-MgGraph -ClientId $tenant.ClientId -TenantId $tenant.TenantId -ClientSecret $tenant.Secret
$auditData = Invoke-MgGraphRequest -Uri "https://graph.microsoft.com/beta/auditLogs/signIns"
$auditData.value | Export-Csv -Path ".\$($tenant.Name)_Audit.csv" -Append
}

Opcional: use o Registro para dar contexto aos relatórios nos endpoints

Caso de uso: as chaves de registro ajudam a garantir que as marcações de dispositivo e os rótulos de relatório sejam aplicados de forma consistente em todos os dispositivos. Para isso, siga estes passos:

1. Abra o Menu Iniciar e procure por Editor do Registro para abrir o programa.
2. Localize a chave de registro correspondente ao aplicativo que quer verificar. Como referência, veja um exemplo de caminho de registro e os valores relevantes dentro dele:

HKEY_LOCAL_MACHINE\SOFTWARE\Contoso\Compliance

• • TenantTag (String) – o valor deve ser “ClientA”.
  • LastAuditSync (String) – o valor deve ser “[Data da última sincronização de auditoria]”.

Observação: dá para usar scripts que leiam essas marcações e incluam metadados dos endpoints nos relatórios gerados pelo Graph.

Opcional: use a Política de Grupo para o status de conformidade dos endpoints

Caso de uso: as políticas de grupo ajudam a reforçar a aplicação de regras e a garantir a conformidade dos endpoints, principalmente na pontuação de conformidade e nos relatórios de sensibilidade de dados.

1. Abra o Menu Iniciar e procure por Editar Política de Grupo para abrir o programa.
2. Vá até este local: Configuração do Computador > Modelos Administrativos > Componentes do Windows > Coleta de Dados.
3. Ative as seguintes políticas:
   • Permitir Telemetria – defina também como Avançado ou Completo.
   • Configurar ID comercial para agrupamento de dispositivos

Opcional: use o CMD para validar permissões e conectividade

Caso de uso: útil em ambientes locais ou híbridos, nos quais os endpoints precisam estar alinhados à conformidade.

1. Abra o Menu Iniciar e procure por Prompt de Comando.
2. Clique com o botão direito em Prompt de Comando > Executar como administrador.
3. Para verificar o acesso à Internet e ao endpoint do Graph, digite este comando e pressione Enter:

nslookup graph.microsoft.com

ping graph.microsoft.com

Para validar o status de sincronização do agente local, digite este comando e pressione Enter:

dsregcmd /status

Para confirmar que as políticas de GPO foram aplicadas, digite isto e pressione Enter:

gpresult /h gpo.html

Pontos de atenção

Problema/Risco	Possíveis consequências	Correção/Reversão
Aparece um erro de “Access Denied”.	Não é possível acessar os dados procurados.	Confirme se o consentimento do administrador e os escopos de API exigidos foram atribuídos corretamente.
A resposta vem vazia.	Você não recebe os dados procurados.	Verifique se o tenant tem o licenciamento adequado e o registro de logs ativado.
O segredo do cliente expirou.	Você não conseguirá acessar os dados no Microsoft Graph.	Configure um alerta na ferramenta de gerenciamento de endpoints para avisar quando os segredos estiverem perto de expirar e evitar esse problema.
Há um erro no script.	Você não conseguirá extrair os relatórios.	Use blocos Try/Catch e logs detalhados para rastrear os erros.

Outros pontos a considerar ao usar o Microsoft Graph para extrair relatórios de conformidade

• Atenção aos limites de taxa e à limitação de requisições do Microsoft Graph. Em alguns casos, será preciso repetir ações, principalmente ao extrair grandes volumes de dados.
• Dá para reduzir a complexidade com o Azure Lighthouse ou com modelos de acesso entre tenants.
• Use o Azure Key Vault ou uma solução de armazenamento criptografado para guardar os segredos de cliente.
• Garanta que apenas pessoas autorizadas tenham acesso a relatórios com dados específicos de usuários.

Serviços NinjaOne

NinjaOne aprimora a automação de conformidade baseada no Graph com:

• Execução entre tenants: agende e implante scripts PowerShell de relatórios em todos os tenants gerenciados com a ferramenta de PowerShell remoto do NinjaOne.
• Gerenciamento centralizado de credenciais: armazene as credenciais da Graph API com segurança e use-as por tenant em uma solução de armazenamento segura e criptografada.
• Alertas e painéis de conformidade: integre os resultados dos relatórios a painéis personalizados e receba notificações ao atingir limites de risco.
• Contexto no nível do endpoint: extraia dados de registro e de GPO de cada dispositivo para enriquecer os relatórios de conformidade com a ferramenta de gerenciamento de endpoints do NinjaOne.
• Sistema de tickets automatizado: configure alertas para quando condições de conformidade forem detectadas (por exemplo, inatividade de auditoria ou ausência de política de retenção).

Aproveite o Microsoft Graph nos seus relatórios de conformidade

O Microsoft Graph é uma ferramenta poderosa para automatizar relatórios de conformidade em ambientes corporativos. Ele dá aos administradores de TI visibilidade escalável sobre a atividade dos tenants, a proteção de dados e a postura de governança.

Temas relacionados:

• O que é uma auditoria de conformidade? Definição e importância
• O que é gerenciamento de conformidade? Definição e importância
• O que é gerenciamento de segredos? Boas práticas de segurança de TI
• O que é gerenciamento de APIs? Visão geral e boas práticas
• Como agendar verificações via Graph API para licenças expiradas e usuários inativos
• [Video Guide] Como agendar verificações via Graph API para licenças expiradas e usuários inativos