Use Managed Identity with PowerShell for Microsoft Graph

À medida que as empresas dependem cada vez mais do Microsoft 365, automatizar tarefas de gestão torna-se essencial. Você pode aumentar a eficiência e economizar tempo valioso integrando PowerShell + Graph API. Essa combinação poderosa desbloqueia recursos de gestão robustos que simplificam as operações.

No entanto, muitos usuários enfrentam desafios. Por exemplo, algumas funcionalidades essenciais não possuem endpoints documentados, o que complica os esforços de automação. Além disso, APIs legadas podem causar falhas silenciosas, dificultando a manutenção dos seus scripts. Não se preocupe! Este post vai dividir esses conceitos complexos em etapas simples e acionáveis, guiando você pelo processo com soluções claras.

Principais Conclusões

• Integre o PowerShell com a Graph API para automatizar tarefas do Microsoft 365 e aumentar a eficiência.
• Garanta que seu sistema atenda aos pré-requisitos, como PowerShell 7 ou superior e o módulo mais recente do Microsoft Graph, para uma execução tranquila.
• Entenda as permissões e os escopos para controlar o que seus scripts podem acessar no Microsoft 365, seguindo o princípio do menor privilégio.
• Registre seu app no Azure AD para criar uma identidade segura para seus scripts, permitindo acesso seguro ao Microsoft Graph.
• Escolha o fluxo de autenticação adequado, como Device Code Flow ou Managed Identity Flow, para proteger eficazmente seus tokens de acesso.
• Construa requisições HTTP bem formadas usando PowerShell para interagir com a Microsoft Graph API e recuperar dados.
• Trate erros e limites de API com cuidado para garantir que seus scripts sejam executados sem interrupções.
• Otimize seus scripts usando a recuperação seletiva de propriedades e o agrupamento de requisições (batching) para melhorar o desempenho e reduzir o consumo de recursos.

Pré-requisitos para PowerShell + Graph API

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

Instalando os Módulos do PowerShell

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

Requisito	Descrição
Versão do PowerShell	É necessário o PowerShell versão 7 ou superior.
.NET Framework	É necessário o .NET Framework 4.7.2 ou posterior no macOS.
PowerShellGet	Atualize o PowerShellGet para a versão mais recente.
Política de Execução	Defina a política de execução como remote signed ou menos restritiva.

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 facilmente.

Configurando o Ambiente Microsoft 365

Configurar corretamente seu ambiente Microsoft 365 é fundamental para a automação. Siga estas etapas para começar:

1. Confirme que seu sistema atende aos requisitos: PowerShell 7.2 ou posterior, .NET Framework 4.7.2 ou mais recente e o módulo PowerShellGet mais recente.
2. Instale o módulo do Microsoft Graph para PowerShell conforme mostrado acima.
3. Conecte-se ao seu tenant 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 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 seus scripts podem acessar ou modificar no Microsoft 365. A Microsoft Graph API utiliza dois tipos principais de permissão:

• Permissões delegadas: Aplicam-se 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: Permitem que seu app ou script acesse dados em toda a organização sem um usuário conectado.

Permissões comuns incluem *.Read.All para acesso somente leitura e *.ReadWrite.All para capacidades completas de leitura e gravação. 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 tenant deve aprovar essas permissões para garantir a segurança. Além disso, os usuários precisam de funções apropriadas no Microsoft Entra, como Security Reader, para acessar dados sensíveis. Esse controle de acesso baseado em funções acrescenta uma camada extra de segurança.

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

Ao compreender e configurar as permissões com cuidado, você protege seu ambiente e, ao mesmo tempo, habilita uma automação poderosa com PowerShell + Graph API.

Identidade do App no Azure AD

Registrando um Novo App

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

1. Abra o portal do Azure e navegue até Azure Active Directory > Registros de aplicativo > Novo registro.
2. Dê ao seu app um nome significativo, como "Meu App Graph".
3. Escolha os tipos de conta compatíveis:
   • Locatário único: Somente usuários do seu tenant do Azure AD podem fazer login.
   • Multilocatário: Usuários de qualquer tenant do Azure AD podem fazer login.
   • Multilocatário e contas pessoais: Inclui usuários do Azure AD e contas pessoais da Microsoft.