Dominando o fluxo de identidade gerenciada com PowerShell e Microsoft Graph

By Mirko Peters · 2026-08-28

Bem-vindo de volta ao blog do podcast! Se você já sentiu o incômodo de codificar senhas no script, lidar com client secrets trabalhosos ou se preocupar com credenciais vazadas…

Automatically translated with AI from the original post. Read the English original

Bem-vindo de volta ao blog do podcast! Se você já sentiu o incômodo de codificar senhas no script, lidar com client secrets trabalhosos ou se preocupar com credenciais vazando em seus scripts automatizados, você está no lugar certo. A automação na nuvem exige uma mudança de paradigma na forma como pensamos sobre segurança. Já passaram os tempos em que administradores podiam guardar credenciais com tranquilidade em arquivos de configuração em texto simples ou em variáveis de ambiente sem olhar por cima do ombro. Hoje vamos mergulhar fundo no mundo da autenticação nativa da nuvem, vendo especificamente como você pode usar as identidades gerenciadas do Azure dentro dos seus scripts do PowerShell para se autenticar com segurança no Microsoft Graph, sem armazenar credenciais sensíveis.

Automatizar o seu ambiente do Microsoft 365 deixou de ser uma habilidade desejável e passou a ser uma necessidade operacional absoluta. No entanto, combinar o PowerShell com a API do Microsoft Graph pode, às vezes, parecer um labirinto de solicitações de permissão, limites de throttling e fluxos complexos de aquisição de tokens. Ao adotar uma mentalidade voltada para fluxos modernos e centrados na identidade, podemos eliminar totalmente o gerenciamento de credenciais para cargas de trabalho executadas no Azure. Neste post, vamos detalhar os componentes essenciais da autenticação nativa da nuvem, guiando você pelos pré-requisitos, pelos registros de aplicativos no Azure AD, pelos fluxos de aquisição de tokens e pela otimização de scripts. Se você quiser se aprofundar exatamente nesse fluxo de trabalho, não deixe de ouvir o nosso episódio complementar do podcast, Use Managed Identity with PowerShell for Microsoft Graph.

Pré-requisitos para PowerShell + API do Graph

Antes de começar a automatizar tarefas do Microsoft 365 com PowerShell e a API do Graph, você precisa preparar corretamente o seu sistema e o seu ambiente. Essa preparação garante uma execução sem problemas e um acesso seguro aos recursos do Microsoft Graph.

Instalando os módulos do PowerShell

Você precisa instalar os módulos certos do PowerShell para interagir com a API do Microsoft Graph. O SDK do PowerShell do Microsoft Graph fornece todos os cmdlets necessários para essa integração. Para evitar erros, verifique se o seu sistema atende a estes requisitos mínimos:

Você pode atualizar o PowerShellGet executando Install-Module PowerShellGet -Force e definir a política de execução com Set-ExecutionPolicy RemoteSigned. Depois disso, instale o módulo do Microsoft Graph usando:

Install-Module Microsoft.Graph -Scope CurrentUser

Esse comando baixa a versão estável mais recente do módulo, permitindo que você chame os endpoints do Microsoft Graph com facilidade.

Configurando o ambiente do Microsoft 365

Configurar corretamente o seu ambiente do Microsoft 365 é essencial para a automação. Siga estes passos para começar:

1. Confirme que o seu sistema atende aos requisitos: PowerShell 7.2 ou posterior, .NET Framework 4.7.2 ou mais recente e o módulo PowerShellGet mais atual.
2. Instale o módulo do PowerShell do Microsoft Graph conforme mostrado acima.
3. Conecte-se ao seu locatário do Microsoft 365 importando o módulo e autenticando com os escopos necessários. Por exemplo:

Connect-MgGraph -Scopes "User.ReadWrite.All","Directory.ReadWrite.All"

Esse comando solicita que você faça login e concede à sua sessão permissões para ler e gravar dados de usuários e do diretório. Você pode ajustar os escopos de acordo com as necessidades da sua automação.

Entendendo permissões e escopos

Permissões e escopos definem o que os seus scripts podem acessar ou modificar no Microsoft 365. A API do Microsoft Graph usa dois tipos principais de permissão:

• Permissões delegadas: Elas se aplicam quando você executa scripts como um usuário conectado. Elas limitam o acesso aos dados que o usuário possui ou pode acessar.
• Permissões de aplicativo: Elas permitem que seu aplicativo ou script acesse dados em toda a organização sem um usuário conectado, o que é típico de automações em segundo plano e fluxos com identidade gerenciada.

Permissões comuns incluem *.Read.All para acesso somente leitura e *.ReadWrite.All para leitura e gravação completas. Por exemplo, SecurityActions.Read.All permite visualizar ações de segurança, enquanto SecurityActions.ReadWrite.All permite modificá-las.

Permissões de aplicativo exigem consentimento de administrador. Um administrador do locatário precisa aprovar essas permissões para garantir a segurança. Além disso, os usuários precisam das funções adequadas do Microsoft Entra, como Leitor de Segurança, para acessar dados sensíveis. Esse controle de acesso baseado em funções adiciona uma camada extra de segurança.

Ao se conectar usando o Microsoft Graph PowerShell SDK, especifique apenas os escopos de que seu script precisa. Essa prática segue o princípio do privilégio mínimo, reduzindo os riscos de segurança. Lembre-se de que as permissões concedidas ao seu aplicativo se aplicam a todos os usuários desse aplicativo, por isso revise e gerencie-as regularmente.

Identidade de aplicativo no Azure AD

Registrando um novo aplicativo

Para automatizar tarefas do Microsoft 365 com PowerShell e a API do Graph, primeiro você precisa registrar um aplicativo no Azure Active Directory (Azure AD). Esse aplicativo atua como uma identidade que seus scripts usam para acessar o Microsoft Graph com segurança. Siga estes passos para registrar seu aplicativo:

1. Abra o portal do Azure e acesse Azure Active Directory > Registros de aplicativo > Novo registro.
2. Dê ao seu aplicativo um nome significativo, como "My Graph Automation App".
3. Escolha os tipos de conta compatíveis:
   • Locatário único: somente usuários do seu locatário do Azure AD podem entrar.
   • Multilocatário: usuários de qualquer locatário do Azure AD podem entrar.
   • Multilocatário e contas pessoais: inclui usuários do Azure AD e contas pessoais da Microsoft.
4. Defina o URI de redirecionamento de acordo com o tipo do seu aplicativo:
   • Para aplicativos web, use uma URL como https://yourapp.com/auth/callback.
   • Para aplicativos de página única, use https://yourapp.com.
   • Para aplicativos móveis ou de desktop, use https://login.microsoftonline.com/common/oauth2/nativeclient.
5. Clique em Registrar para criar seu aplicativo.

Esse processo cria uma identidade de aplicativo exclusiva no seu locatário. Você usará essa identidade para solicitar tokens e chamar a API do Microsoft Graph.

Configurando permissões de API

Depois de registrar seu aplicativo, você precisa configurar as permissões de API de que ele necessita. Essas permissões controlam o que seu aplicativo pode acessar ou modificar no Microsoft 365. Para definir as permissões:

1. No registro do seu aplicativo, acesse Permissões de API > Adicionar uma permissão > Microsoft Graph.
2. Escolha Permissões de aplicativo se seu script rodar sem interface ou por meio de um contexto de identidade gerenciada, ou Permissões delegadas se ele rodar de forma interativa.
3. Selecione as permissões específicas de que seu aplicativo precisa, como User.Read.All ou Directory.Read.All.
4. Clique em Adicionar permissões para aplicá-las.

⚠️ Sempre aplique o princípio do privilégio mínimo. Atribua apenas as permissões de que seu aplicativo precisa para reduzir os riscos de segurança.

Algumas permissões exigem consentimento de administrador antes que seu aplicativo possa usá-las. Você pode conceder esse consentimento clicando em Conceder consentimento de administrador para [nome do locatário] no portal do Azure. Revise as permissões regularmente para evitar que seu aplicativo tenha privilégios excessivos.

Gerando segredo de cliente ou certificado

Seu aplicativo precisa de credenciais para se autenticar com segurança no Azure AD caso não esteja usando uma identidade gerenciada. Você pode usar um segredo de cliente ou um certificado. Ambos os métodos comprovam a identidade do seu aplicativo ao solicitar tokens.

Para criar um segredo de cliente, acesse Certificados e segredos no registro do seu aplicativo, selecione Novo segredo de cliente, adicione uma descrição e defina um período de expiração. Para certificados, carregue um arquivo de certificado válido na mesma seção.

Obtendo tokens de acesso

Entendendo o OAuth 2.0

O OAuth 2.0 desempenha um papel fundamental na proteção do seu acesso à API do Microsoft Graph ao usar PowerShell + API do Graph. Ele funciona como um guardião confiável que permite que suas aplicações se autentiquem com segurança e obtenham tokens de acesso. Esses tokens funcionam como chaves digitais, concedendo aos seus scripts permissão para chamar os endpoints do Microsoft Graph sem expor suas credenciais diretamente.

Para usar o OAuth 2.0, primeiro você precisa registrar sua aplicação no Azure Active Directory (Azure AD). Esse registro fornece credenciais de cliente, como um ID de aplicativo e um segredo ou certificado. Quando seu script solicita um token de acesso, ele apresenta essas credenciais ao Azure AD. O Azure AD então verifica sua identidade e emite um token de curta duração. Seu script inclui esse token nas requisições à API para comprovar que tem direito de acessar os recursos solicitados.

Esse processo garante acesso seguro e controlado aos dados do Microsoft 365. Ele também oferece suporte a permissões granulares, para que seus scripts recebam apenas o acesso de que precisam. Ao seguir os padrões do OAuth 2.0, você protege seu ambiente contra acessos não autorizados e, ao mesmo tempo, habilita automações poderosas com PowerShell + API do Graph.

Usando o PowerShell para solicitações de token

Você pode obter tokens de acesso usando vários fluxos de autenticação adaptados a diferentes cenários. Cada fluxo equilibra segurança e usabilidade de maneira diferente. A API do Microsoft Graph oferece suporte a estes fluxos comuns:

• Fluxo de código de dispositivo: ideal para dispositivos ou scripts sem navegador ou recursos de entrada. Você se autentica em outro dispositivo, o que torna o processo seguro e fácil de usar.
• Fluxo baseado em certificado: projetado para automação sem interface, este fluxo usa certificados em vez de senhas, aumentando a segurança de scripts não supervisionados.
• Fluxo de identidade gerenciada: ideal para ambientes nativos da nuvem, como Azure Functions ou máquinas virtuais, este fluxo utiliza as identidades gerenciadas do Azure para obter tokens sem armazenar segredos.

Fluxo de código de dispositivo

O fluxo de código de dispositivo funciona bem quando você executa scripts localmente ou em dispositivos sem opções de entrada práticas. Ele permite autenticar interativamente em outro dispositivo, como seu celular ou o navegador do seu PC.

Veja como usar o fluxo de código de dispositivo com o PowerShell:

1. Execute o comando a seguir para iniciar a autenticação por código de dispositivo:

   Connect-MgGraph -Scopes "User.Read.All" -DeviceCode

2. O PowerShell exibe um código e uma URL. Abra a URL no navegador de qualquer dispositivo.
3. Digite o código exibido no PowerShell e entre com sua conta do Microsoft 365.
4. Após a autenticação bem-sucedida, o PowerShell obtém um token de acesso e conecta sua sessão.

💡 O fluxo de código de dispositivo equilibra segurança e usabilidade. Ele evita incorporar credenciais em scripts e funciona bem para tarefas manuais ou semiautomatizadas.

Fluxo baseado em certificado

O fluxo baseado em certificado é indicado para scripts automatizados executados sem interação do usuário. Em vez de um segredo de cliente, você usa um certificado para comprovar a identidade do seu aplicativo. Esse método reduz os riscos relacionados a segredos vazados.

Para usar esse fluxo, siga estas etapas:

1. Registre seu aplicativo no Azure AD e carregue um certificado em Certificados e segredos.
2. Armazene o certificado com segurança na máquina que executa seu script.
3. Use o PowerShell para solicitar um token especificando a impressão digital do certificado, o ID do cliente e o ID do locatário.

Aqui está um exemplo simplificado de como obter um token usando um certificado no PowerShell:

$tenantId = "YOUR_TENANT_ID"
$clientId = "YOUR_CLIENT_ID"
$certThumbprint = "YOUR_CERT_THUMBPRINT"
$cert = Get-Item Cert:\CurrentUser\My\$certThumbprint
$body = @{
    grant_type = "client_credentials"
    client_id = $clientId
    scope = "https://graph.microsoft.com/.default"
    client_assertion_type = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
    client_assertion = New-JwtToken -Certificate $cert -TenantId $tenantId -ClientId $clientId
}
$tokenResponse = Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" -Body $body
$accessToken = $tokenResponse.access_token

⚠️ Gerenciar certificados exige cuidado. Proteja as chaves privadas e renove os certificados regularmente para manter a segurança.

Fluxo de Identidade Gerenciada

O Fluxo de Identidade Gerenciada funciona melhor quando você executa scripts do PowerShell + Graph API dentro de serviços do Azure, como Azure Virtual Machines, Azure Functions ou Azure Automation. O Azure atribui automaticamente uma identidade ao seu recurso, então você não precisa gerenciar credenciais manualmente.

Para obter um token de acesso usando a Identidade Gerenciada, siga estas etapas:

1. Habilite a Identidade Gerenciada (atribuída pelo sistema ou pelo usuário) no seu recurso do Azure.
2. Atribua as permissões necessárias da Microsoft Graph API a essa identidade no Azure AD, usando o Microsoft Graph PowerShell ou o Graph Explorer.
3. Use o PowerShell para solicitar um token do Serviço de Metadados de Instância (IMDS) do Azure local.

Exemplo de trecho de PowerShell para obter um token via Identidade Gerenciada:

$resource = "https://graph.microsoft.com"
$tokenAuthUri = "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=$resource"
$headers = @{ Metadata = "true" }
$response = Invoke-RestMethod -Method Get -Uri $tokenAuthUri -Headers $headers
$accessToken = $response.access_token

🔐 O Fluxo de Identidade Gerenciada elimina a necessidade de armazenar segredos nos seus scripts. Ele oferece autenticação segura e transparente em ambientes do Azure.

Fazendo chamadas de API com PowerShell + Graph API

Fazer chamadas de API com PowerShell + Graph API permite interagir com os serviços do Microsoft 365 de forma eficaz. Entender como construir requisições HTTP é essencial para uma comunicação bem-sucedida com a API.

Construindo requisições HTTP

Ao interagir com a Microsoft Graph API, você precisa construir as requisições HTTP corretamente. Estes são os componentes principais de uma requisição HTTP:

• Obtenção do token de acesso: use o token obtido dentro do cabeçalho.
• Configuração dos cabeçalhos: defina os cabeçalhos necessários, incluindo Content-Type: application/json e Authorization: Bearer $accessToken.
• Requisição GET/POST: faça uma requisição explícita ao endpoint desejado da Microsoft Graph API.

Usando o Invoke-RestMethod

O cmdlet Invoke-RestMethod simplifica a comunicação com a Microsoft Graph API. Ele permite enviar requisições HTTP e receber respostas de forma direta. Aqui está uma visão geral rápida do seu comportamento e de suas limitações:

Endpoints comuns da API

Vários endpoints da Microsoft Graph API são usados com frequência em tarefas de gerenciamento do Microsoft 365. Estes são alguns dos mais comuns:

Gerenciando a saída da API

Entendendo as respostas JSON

Ao interagir com a Microsoft Graph API, ela retorna os dados no formato JSON. JSON (JavaScript Object Notation) é leve e fácil de ler. Entender as respostas JSON é fundamental para manipular dados de forma eficaz. Uma resposta JSON típica se parece com isto:

{
  "id": "1",
  "displayName": "John Doe",
  "mail": "john.doe@example.com"
}

Convertendo JSON em objetos do PowerShell

Para trabalhar com dados JSON no PowerShell, você precisa convertê-los em objetos do PowerShell. Essa conversão permite manipular os dados facilmente. Você pode usar o cmdlet ConvertFrom-Json para isso. Veja como funciona:

$jsonData = '{"id": "1", "displayName": "John Doe", "mail": "john.doe@example.com"}'
$powerShellObject = $jsonData | ConvertFrom-Json

Agora, $powerShellObject contém propriedades que você pode acessar diretamente, como $powerShellObject.displayName.

Filtrando e formatando dados

Quando você tiver seus dados em objetos do PowerShell, poderá filtrá-los e formatá-los conforme suas necessidades. O PowerShell oferece várias técnicas para refinar a saída dos dados. Por exemplo, você pode usar parâmetros de consulta OData nas chamadas à API para filtrar os resultados diretamente pela Microsoft Graph API.

Exportando resultados

Exportar os resultados dos seus scripts do PowerShell é essencial para um gerenciamento de dados eficaz. Você pode salvar a saída em diversos formatos, como CSV, JSON ou XML. Por exemplo, você pode exportar os detalhes dos usuários assim:

$users = Get-MgUser -All
$users | Select-Object DisplayName, Mail | Export-Csv -Path "Users.csv" -NoTypeInformation

Boas práticas e solução de problemas

Tratamento de erros e limites da API

Ao trabalhar com a Microsoft Graph API, os erros costumam surgir de configurações específicas do locatário ou problemas de permissões. Muitos usuários executam scripts baixados da internet sem adaptá-los ao seu ambiente, o que causa falhas. Além disso, a Microsoft Graph aplica limites de taxa para proteger os seus serviços. Se o seu script enviar muitas solicitações em pouco tempo, a API retorna o código de status 429. Você deve respeitar o cabeçalho Retry-After e aguardar o tempo sugerido antes de tentar novamente.

Protegendo credenciais

Proteger suas credenciais é fundamental ao automatizar tarefas no Microsoft 365. Use registros de aplicativo e identidades gerenciadas para criar identidades seguras para os seus aplicativos. Evite armazenar segredos de cliente em texto simples dentro dos seus scripts sempre que possível.

Otimizando scripts

Scripts eficientes economizam tempo e reduzem o consumo de recursos. Use a recuperação seletiva de propriedades aplicando o parâmetro de consulta $select, aproveite os mecanismos de lote e projete seus loops de automação com manipuladores de paginação bem estruturados.

Dominar os fluxos de identidade gerenciada com PowerShell e a Microsoft Graph API transforma fundamentalmente a forma como você aborda a automação na nuvem. Ao eliminar segredos estáticos e adotar identidades nativas da nuvem, você cria fluxos de trabalho resilientes e altamente seguros, que protegem sua empresa. Para saber mais sobre essas estratégias e ouvir discussões práticas sobre administração moderna de nuvem, não deixe de conferir nosso episódio relacionado: Use Managed Identity with PowerShell for Microsoft Graph. Experimente esses exemplos no seu locatário de sandbox hoje mesmo e leve sua estrutura de automação para o próximo nível!

Perguntas frequentes

O que é o PowerShell?

O PowerShell é um framework de automação de tarefas da Microsoft que combina um shell de linha de comando com uma linguagem de script para simplificar o gerenciamento de sistemas e as operações na nuvem.

O que é a Microsoft Graph API?

A Microsoft Graph API é um endpoint RESTful unificado para acessar dados e serviços do Microsoft 365, incluindo usuários, grupos, e-mails e configurações de diretório.

Como instalo o módulo do PowerShell da Microsoft Graph?

Você pode instalar o módulo executando Install-Module Microsoft.Graph -Scope CurrentUser no seu ambiente do PowerShell 7.

O que são permissões delegadas e de aplicativo?

As permissões delegadas permitem que o seu aplicativo atue em nome de um usuário conectado, enquanto as permissões de aplicativo permitem a execução em segundo plano, sem um contexto de usuário ativo.

Como lido com os limites de taxa da API?

Sempre inspecione os cabeçalhos de resposta em busca do valor Retry-After ao receber um código de status 429, e implemente uma lógica de nova tentativa com backoff exponencial em seus scripts.

O que é OAuth 2.0?

OAuth 2.0 é um framework de autorização que permite que aplicativos obtenham tokens de acesso de forma segura para chamar APIs protegidas, sem expor as credenciais subjacentes do usuário.

Posso usar o PowerShell no Linux?

Sim! O PowerShell é totalmente multiplataforma e roda nativamente no Windows, no macOS e no Linux.

Como exporto dados do PowerShell?

Você pode exportar dados estruturados com facilidade usando cmdlets como Export-Csv ou ConvertTo-Json, dependendo dos requisitos do formato do seu relatório.