Josimar Hedler
Índice
Introdução
Administrar identidade pelo portal do Microsoft Entra funciona bem para atividades pontuais: criar um usuário, revisar um grupo, verificar uma aplicação específica, mas assim que o objetivo muda automação de rotinas, inventário completo do tenant, análise em escala ou correlação de informações entre diferentes áreas de identidade, o portal deixa de ser suficiente. Nesse ponto, é necessário uma camada programática que permita consultar, cruzar e automatizar dados de identidade de forma consistente.
É exatamente esse o papel do Microsoft Graph: uma API unificada que expõe praticamente todos os recursos do Microsoft Entra ID e do Microsoft 365 através de um único modelo de dados e de um conjunto coerente de endpoints REST.
De forma conceitual, o caminho entre o administrador e os dados de identidade pode ser representado assim:
Administrador / Automação
│
▼
Microsoft Graph PowerShell SDK
│
▼
Microsoft Graph API
│
▼
Microsoft Entra ID
│
▼
Usuários, Grupos, Aplicações, Service Principals,
Directory Roles, PIM, Conditional Access, Riscos, Logs
O Microsoft Graph PowerShell SDK é a camada que traduz essa API em cmdlets do PowerShell, permitindo que profissionais de identidade automatizem tarefas sem precisar lidar diretamente com chamadas REST, tokens e payloads JSON a cada consulta.
Atenção: As implementações apresentadas em nossos artigos foram desenvolvidas com base em documentações oficiais e nas boas práticas recomendadas pela Microsoft. Entretanto, enfatizamos que qualquer implementação deve ser previamente testada em ambientes de homologação ou testes para garantir a segurança e a estabilidade do ambiente de produção
Microsoft Graph PowerShell SDK
Instalando e atualizando os módulos do Microsoft Graph
É comum confundir o Microsoft Graph API com o Microsoft Graph PowerShell SDK, mas são duas coisas diferentes:
- O Microsoft Graph API é a interface REST em si endpoints HTTP que retornam e recebem JSON.
- O Microsoft Graph PowerShell SDK é um conjunto de módulos PowerShell que encapsula essas chamadas REST em cmdlets nativos, como
Get-MgUserouGet-MgGroup.
Um ponto importante: o SDK não é um módulo único, ele é dividido em dezenas de submódulos, cada um focado em uma área específica do Graph (usuários, grupos, mensagens, arquivos, dispositivos, etc.). Isso significa que não é necessário nem recomendável instalar o SDK inteiro quando o objetivo é trabalhar apenas com identidade.
Para os cenários deste artigo, vamos instalar os módulos:
Install-Module Microsoft.Graph.Authentication -Scope CurrentUser
Install-Module Microsoft.Graph.Users -Scope CurrentUser
Install-Module Microsoft.Graph.Groups -Scope CurrentUser
Install-Module Microsoft.Graph.Applications -Scope CurrentUser
Install-Module Microsoft.Graph.Identity.DirectoryManagement -Scope CurrentUser
Install-Module Microsoft.Graph.Identity.Governance -Scope CurrentUser
Install-Module Microsoft.Graph.Identity.SignIns -Scope CurrentUser
Install-Module Microsoft.Graph.Reports -Scope CurrentUserInstalar apenas os módulos necessários reduz a superfície local, agiliza o carregamento do PowerShell e evita conflitos de versão em ambientes com múltiplos scripts.
Como o Microsoft Graph PowerShell SDK é dividido em vários submódulos, é importante manter as versões atualizadas para evitar incompatibilidades durante o carregamento, principalmente porque submódulos diferentes, em versões diferentes, podem gerar conflitos silenciosos entre si.
Para verificar quais versões estão instaladas:
Get-Module -ListAvailable Microsoft.Graph* |
Select-Object Name, Version, Path |
Sort-Object Name, VersionSe houver módulos desatualizados, utilize Update-Module para atualizá-los. Exemplo, considerando os módulos usados neste artigo:
Update-Module Microsoft.Graph.Authentication
Update-Module Microsoft.Graph.Users
Update-Module Microsoft.Graph.Groups
Update-Module Microsoft.Graph.Applications
Update-Module Microsoft.Graph.Identity.DirectoryManagement
Update-Module Microsoft.Graph.Identity.Governance
Update-Module Microsoft.Graph.Identity.SignIns
Update-Module Microsoft.Graph.ReportsAtenção: Se algum módulo estiver em uso na sessão atual, feche o PowerShell e abra uma nova janela antes de executar a atualização o Windows PowerShell não permite substituir arquivos de um módulo carregado.
Como o Microsoft Graph PowerShell SDK é dividido em vários submódulos, é importante manter os módulos utilizados em versões compatíveis, quando Microsoft.Graph.Authentication, Microsoft.Graph.Users, Microsoft.Graph.Groups e outros módulos estão em versões diferentes, podem ocorrer erros de carregamento de assemblies.
Autenticação
Toda interação com o Microsoft Graph começa com Connect-MgGraph. O cmdlet estabelece a sessão autenticada que será usada pelos demais comandos do SDK.
Connect-MgGraph -Scopes "User.Read.All", "Group.Read.All"Repare que a autenticação aqui já nasce vinculada a scopes (permissões delegadas). Isso não é um detalhe burocrático, é o ponto em que o conceito de Least Privilege entra em jogo pela primeira vez, cada scope solicitado define exatamente o que a sessão pode fazer nada além disso.
Após conectar, é possível verificar o contexto atual da sessão:
Get-MgContext
Observação: neste ambiente, a sessão utilizada já possui outros scopes delegados concedidos anteriormente para diferentes cenários de teste e administração. Por esse motivo, o Get-MgContext apresenta permissões adicionais além de User.Read.All e Group.Read.All. Em um ambiente novo, a recomendação continua sendo solicitar apenas os scopes necessários para cada operação, seguindo o princípio de Least Privilege.
O retorno mostra a conta autenticada, o tenant, os scopes concedidos e o ambiente (Global, etc.), o que é útil tanto para depuração quanto para auditoria de scripts.
Vale diferenciar brevemente os dois modelos de autenticação suportados:
- Delegated (delegada): a sessão atua em nome de um usuário autenticado interativamente, as permissões efetivas são a interseção entre os scopes concedidos ao app e os direitos do usuário logado.
- App-only: a automação atua como uma identidade de aplicação (Service Principal), normalmente usando certificado, sem um usuário interativo por trás, usada em pipelines, runbooks e automações não assistidas.
Em ambos os modelos, o princípio é o mesmo: autenticação prova quem está fazendo a chamada; autorização expressa pelos scopes ou pelas permissões de aplicação define o que essa identidade pode fazer no Graph, solicitar sempre o menor conjunto de permissões necessário para a tarefa é a aplicação prática de Least Privilege nesse contexto.
Principais módulos do Microsoft Graph relacionados a identidade
| Módulo | Área | Objetos/recursos | Exemplos de utilização |
|---|---|---|---|
| Microsoft.Graph.Authentication | Autenticação e descoberta | Sessão, contexto, comandos, permissões | Connect-MgGraph, Get-MgContext, Find-MgGraphCommand |
| Microsoft.Graph.Users | Identidades de usuário | Usuários, atributos, guests | Get-MgUser, inventário de contas |
| Microsoft.Graph.Groups | Autorização e agrupamento | Grupos, membros, proprietários | Get-MgGroup, análise de pertencimento |
| Microsoft.Graph.Applications | Identidades de aplicação | App Registrations, Service Principals | Get-MgApplication, Get-MgServicePrincipal |
| Microsoft.Graph.Identity.DirectoryManagement | Estrutura do diretório | Directory Roles, domínios, organização | Get-MgDirectoryRole |
| Microsoft.Graph.Identity.Governance | Governança de privilégios | PIM, elegibilidade, ativações | Get-MgRoleManagementDirectoryRoleEligibilityScheduleInstance |
| Microsoft.Graph.Identity.SignIns | Acesso condicional e proteção de identidade | Conditional Access, Risky Users | Get-MgIdentityConditionalAccessPolicy, Get-MgRiskyUser |
| Microsoft.Graph.Reports | Auditoria e telemetria | Sign-in logs, audit logs | Get-MgAuditLogSignIn |
Essa tabela, é a imagem abaixo funciona como um mapa mental: cada módulo representa uma “lente” diferente sobre a mesma identidade.
Usuários
O ponto de partida mais natural é o objeto usuário, o cmdlet Get-MgUser (módulo Microsoft.Graph.Users) permite consultar contas do tenant.
# Exemplo simples: listar usuários
Get-MgUser -Top 10Também é possível selecionar apenas as propriedades relevantes, o que reduz o payload da resposta e torna a saída mais legível:
Get-MgUser -Top 10 -Property Id, DisplayName, UserPrincipalName, AccountEnabled |
Select-Object Id, DisplayName, UserPrincipalName, AccountEnabledA partir desse único cmdlet já é possível construir cenários relevantes de identidade:
- Inventário: quantas contas existem, quais estão habilitadas ou desabilitadas.
- Identificação de guests: usuários externos convidados no tenant (propriedade
UserType). - Análise de atributos: departamento, cargo, localização, licenciamento.
- Detecção de contas órfãs: contas antigas sem atividade recente (quando combinadas com sign-in logs).
Grupos
O módulo Microsoft.Graph.Groups expõe o cmdlet Get-MgGroup para consultar grupos do Entra ID.
Get-MgGroup -Top 10 -Property Id, DisplayName, GroupTypes, SecurityEnabled |
Select-Object Id, DisplayName, GroupTypes, SecurityEnabledGrupos raramente são interessantes isoladamente o que importa é quem está dentro deles e quem os administra. Os relacionamentos de members e owners são centrais para dois motivos:
- Autorização: muitas aplicações, roles e políticas de Conditional Access usam grupos como unidade de atribuição, em vez de usuários individuais.
- Governança: um grupo com proprietários mal definidos, ou com membros que não deveriam estar ali, é uma das formas mais comuns de desvio silencioso de acesso em um tenant.
Applications e Service Principals
Esta é uma das áreas em que a confusão conceitual é mais frequente, no modelo do Microsoft Entra ID existem dois objetos distintos, embora relacionados:
- Application Registration / Application Object: representa a definição da aplicação é o “projeto” ou “manifesto” da app, único por tenant onde foi registrada.
- Service Principal: é a instância local dessa aplicação em um tenant o objeto que efetivamente recebe permissões, é referenciado em atribuições de acesso e é usado em tempo de execução. Uma mesma Application pode ter Service Principals em múltiplos tenants (cenário multi-tenant).
Em termos simples: a Application é o “modelo”; o Service Principal é a “identidade em uso”.
# Application (definição/registro)
Get-MgApplication -Top 10 -Property Id, AppId, DisplayName |
Select-Object Id, AppId, DisplayName
# Service Principal (identidade em tempo de execução)
Get-MgServicePrincipal -Top 10 -Property Id, AppId, DisplayName |
Select-Object Id, AppId, DisplayNameA partir desses dois objetos, abrem-se diversos cenários de segurança que merecem atenção contínua, sem que seja necessário, neste momento construir scripts complexos:
- Owners: quem pode administrar a aplicação; ausência de owners dificulta a rastreabilidade.
- Client Secrets e certificados: credenciais usadas para autenticação app-only, com datas de expiração que precisam ser monitoradas.
- Expiração de credenciais: segredos e certificados vencidos ou próximos do vencimento são uma causa comum de interrupções e também um vetor de risco se ficarem esquecidos.
- API permissions: quais permissões a aplicação solicita, e se são delegadas ou de aplicação.
- Admin Consent: se as permissões concedidas passaram por consentimento administrativo, e quem concedeu.
- Atividade do Service Principal: com que frequência a aplicação é realmente utilizada, o que ajuda a identificar apps obsoletas ainda com acesso ativo.
Cada um desses pontos é, isoladamente, suficiente para um artigo próprio, aqui o objetivo é apenas mostrar que o Graph disponibiliza esses dados de forma consultável.
Directory Roles
O módulo Microsoft.Graph.Identity.DirectoryManagement permite consultar as Microsoft Entra Directory Roles as funções administrativas nativas do diretório, como:
- Global Administrator
- Privileged Role Administrator
- Application Administrator
- Cloud Application Administrator
Get-MgDirectoryRole | Select-Object Id, DisplayName, RoleTemplateIdMicrosoft Entra Directory Roles não são Azure RBAC.
Atenção: Essa distinção é fundamental e frequentemente confundida, Directory Roles concedem privilégios sobre o diretório (Microsoft Entra ID) e sobre serviços do Microsoft 365 coisas como gerenciar usuários, aplicações ou políticas de segurança. Azure RBAC, por outro lado, pertence à camada do Azure Resource Manager e controla acesso a recursos de infraestrutura na nuvem Azure máquinas virtuais, contas de armazenamento, grupos de recursos, são dois sistemas de autorização independentes, com modelos de atribuição, escopos e APIs diferentes. Um usuário pode ser Global Administrator no Entra ID e não ter absolutamente nenhum acesso a uma assinatura Azure e vice-versa.
PIM (Privileged Identity Management)
O módulo Microsoft.Graph.Identity.Governance expõe a camada de governança de privilégios, incluindo o Privileged Identity Management (PIM).
Para consultar atribuições elegíveis (roles que um usuário pode ativar, mas que não estão ativas o tempo todo):
Get-MgRoleManagementDirectoryRoleEligibilityScheduleInstance |
Select-Object PrincipalId, RoleDefinitionId, DirectoryScopeIdPara consultar atribuições ativas no momento:
Get-MgRoleManagementDirectoryRoleAssignmentScheduleInstance |
Select-Object PrincipalId, RoleDefinitionId, DirectoryScopeId, StartDateTime, EndDateTimeO fluxo conceitual do PIM pode ser representado assim:
Directory Role
│
▼
PIM
│
▼
Eligible ──► Activation ──► Active ──► ExpirationOu seja: um principal pode estar elegível para uma role sem estar usando-a; ao ativar, a atribuição se torna ativa por tempo determinado; ao final desse período, ela expira e volta ao estado elegível. O Microsoft Graph permite consultar essa camada inteira de forma programática, o que é essencial para auditorias de acesso privilegiado por exemplo, identificar quantas contas têm elegibilidade para Global Administrator, mesmo que não estejam ativas neste instante.
Conditional Access e Identity Protection
O módulo Microsoft.Graph.Identity.SignIns concentra as áreas relacionadas a controle de acesso condicional e proteção de identidade:
- Conditional Access: políticas que condicionam o acesso a sinais como localização, dispositivo, risco e aplicação.
- Authentication Strength: definição de quais métodos de autenticação satisfazem determinada política.
- Identity Protection: detecção de risco em usuários e sign-ins.
- Risky Users: contas sinalizadas com atividade suspeita.
Para consultar políticas de Conditional Access:
Get-MgIdentityConditionalAccessPolicy |
Select-Object Id, DisplayName, StatePara consultar usuários sinalizados como arriscados pelo Identity Protection:
Get-MgRiskyUser -Filter "riskLevel eq 'high'" |
Select-Object UserDisplayName, RiskLevel, RiskState, RiskLastUpdatedDateTimeVale observar que o recurso de Risky Users requer licenciamento Microsoft Entra ID P2, algo a considerar antes de planejar automações nessa área.
Auditoria e Sign-in Logs
O módulo Microsoft.Graph.Reports fecha o ciclo, permitindo consultar os registros de entrada no tenant.
# Exemplo simples
Get-MgAuditLogSignIn -Top 10
# Exemplo com filtro: sign-ins de uma aplicação específica
Get-MgAuditLogSignIn -Filter "startsWith(appDisplayName,'Graph')" -Top 10 |
Select-Object UserPrincipalName, AppDisplayName, CreatedDateTime, StatusÉ neste ponto que a proposta de valor do Graph fica mais evidente: cada sign-in registrado permite correlacionar:
Usuário → Login → Aplicação → Origem → Dispositivo → Políticas → ResultadoAlém dos sign-in logs, o Microsoft Graph também expõe Audit Logs (mudanças administrativas realizadas no diretório, como criação de usuários ou alteração de roles) e Provisioning Logs (eventos de provisionamento automatizado de identidades, comuns em integrações com aplicações SaaS). Juntos, esses três tipos de registro formam a base de qualquer investigação ou auditoria de identidade no Microsoft Entra ID.
Uma identidade vista por diferentes partes do Microsoft Graph
Para consolidar tudo o que foi apresentado, vale um exercício conceitual com um usuário fictício, [email protected].
Microsoft.Graph.Users
→ Quem é o usuário? (atributos, status, tipo de conta)
Microsoft.Graph.Groups
→ De quais grupos participa? (autorização, pertencimento)
Microsoft.Graph.Identity.Governance
→ Possui funções elegíveis ou ativas? (PIM)
Microsoft.Graph.Reports
→ Quando e onde realizou login? (sign-in logs)
Microsoft.Graph.Identity.SignIns
→ Existe risco associado? (Identity Protection)Isoladamente, Get-MgUser -UserId [email protected] responde a uma pergunta muito limitada, quem é esse usuário no cadastro, mas quando o mesmo identificador é cruzado através de múltiplos módulos, a pergunta muda de natureza deixa de ser “quem é” e passa a ser “qual é a exposição real dessa identidade no tenant”. É exatamente essa correlação, e não a execução isolada de um único cmdlet, que representa o verdadeiro valor do Microsoft Graph para profissionais de identidade e segurança.
Descoberta de comandos
Com oito módulos, dezenas de cmdlets por módulo e múltiplas versões de API, uma pergunta se torna recorrente: qual cmdlet corresponde a qual endpoint, e quais permissões ele exige?
O próprio SDK oferece ferramentas para responder isso, ambas no módulo Microsoft.Graph.Authentication:
# Descobrir cmdlets relacionados a um endpoint ou padrão
Find-MgGraphCommand -Command "*RiskyUser*"
# Descobrir qual cmdlet corresponde a uma URI do Graph
Find-MgGraphCommand -Uri "/users/{id}"
# Descobrir quais permissões existem para um domínio específico
Find-MgGraphPermission -SearchString "User" -PermissionType DelegatedA saída de Find-MgGraphCommand inclui o cmdlet, o módulo, o método HTTP, a URI equivalente e as permissões associadas informação valiosa tanto para quem está escrevendo um script quanto para quem está revisando um já existente, verificando se ele realmente usa a permissão mínima necessária.
Microsoft Graph v1.0 versus Beta
O Microsoft Graph é versionado em dois planos principais:
Microsoft.Graph→ cmdlets alinhados à API v1.0, estável e com suporte para produção.Microsoft.Graph.Beta→ cmdlets alinhados à API beta, usada para recursos em prévia ou ainda em evolução.
Atenção: Para automações e scripts de produção, a recomendação é sempre priorizar v1.0 sempre que o recurso necessário já estiver disponível nessa versão. A API beta pode muda em nome de propriedade, em comportamento ou até ser descontinuada sem os mesmos compromissos de estabilidade da v1.0. Isso não significa evitar o beta por completo, apenas que seu uso deve ser deliberado, geralmente restrito a testes, provas de conceito ou recursos que simplesmente ainda não existem na v1.0.
Conclusão
Ao longo deste artigo, percorremos uma fração representativa da superfície de identidade disponível no Microsoft Graph: usuários, grupos, aplicações, Service Principals, Directory Roles, PIM, Conditional Access, Identity Protection, audit logs e sign-in logs. Cada uma dessas áreas é acessível de forma consistente através do Microsoft Graph PowerShell SDK, com autenticação unificada e um modelo de permissões granular que favorece o Least Privilege.
Mas essa mesma amplitude carrega um problema prático, quanto maior a superfície do Microsoft Graph, mais difícil pode ficar encontrar rapidamente qual módulo, qual cmdlet, qual endpoint e qual permissão utilizar para uma tarefa específica especialmente em tenants onde múltiplas pessoas escrevem scripts de forma independente, sem um padrão comum de descoberta.
Referências oficiais Microsoft Learn:
- Microsoft Graph PowerShell overview
- Connect-MgGraph
- Get-MgUser
- Get-MgGroup
- Get-MgApplication
- Get-MgServicePrincipal
- Get-MgDirectoryRole
- Get-MgRoleManagementDirectoryRoleEligibilityScheduleInstance
- Get-MgRoleManagementDirectoryRoleAssignmentScheduleInstance
- Get-MgIdentityConditionalAccessPolicy
- Get-MgRiskyUser
- Get-MgAuditLogSignIn
- Find-MgGraphCommand
- Find-MgGraphPermission
- Azure AD roles vs Azure roles
- RiskyUser resource type
Chegamos ao final deste artigo!
Ao longo deste conteúdo, vimos como o Microsoft Graph PowerShell pode ser utilizado para explorar diferentes áreas de identidade no Microsoft Entra ID, passando por usuários, grupos, aplicações, Service Principals, Directory Roles, PIM, Conditional Access, Identity Protection e logs.
Mais do que executar cmdlets isolados, o verdadeiro valor do Microsoft Graph está na possibilidade de correlacionar informações de identidade, acesso e segurança em uma única camada programática.
Como sua organização utiliza o Microsoft Graph hoje? Já existe algum processo de automação, inventário ou auditoria de identidades utilizando PowerShell?
E quando você precisa encontrar rapidamente qual módulo, cmdlet, endpoint ou permissão utilizar para determinado cenário, como faz essa descoberta?
Compartilhe sua experiência nos comentários e conte como o Microsoft Graph faz parte da sua rotina de identidade e segurança.