Criar scripts do PowerShell com o Microsoft Graph e a autenticação apenas de aplicações
Este tutorial ensina-o a criar um script do PowerShell que utiliza a Microsoft Graph API para aceder a dados através da autenticação apenas de aplicações. A autenticação apenas de aplicações é uma boa opção para serviços em segundo plano ou aplicações que precisam de aceder aos dados de todos os utilizadores numa organização.
Observação
Para saber como utilizar o Microsoft Graph para aceder a dados em nome de um utilizador, veja este tutorial de autenticação de utilizador (delegado).
Neste tutorial, você vai:
Dica
Como alternativa a seguir este tutorial, pode transferir ou clonar o repositório do GitHub e seguir as instruções no README para registar uma aplicação e configurar o projeto.
Pré-requisitos
Antes de iniciar este tutorial, deverá ter o PowerShell instalado no seu computador de desenvolvimento. O PowerShell 5.1 é o requisito mínimo, mas recomenda-se o PowerShell 7.
Também deve ter uma conta escolar ou profissional da Microsoft com a função de Administrador global. Se não tiver um inquilino do Microsoft 365, poderá qualificar-se para um através do Programa para Programadores do Microsoft 365; para obter detalhes, veja as FAQ. Em alternativa, pode inscrever-se numa avaliação gratuita de um mês ou comprar um plano do Microsoft 365.
Observação
Este tutorial foi escrito com o PowerShell 7.2.2 e o Microsoft Graph PowerShell SDK versão 1.9.5. Os passos neste guia podem funcionar com outras versões, mas isso não foi testado.
Registrar o aplicativo no portal
Neste exercício, irá registar uma nova aplicação no Microsoft Entra para ativar a autenticação apenas de aplicações.
Criar um certificado autoassinado
O SDK do PowerShell do Microsoft Graph requer um certificado para autenticação apenas de aplicações. Para fins de desenvolvimento, um certificado autoassinado é suficiente. Precisa de um certificado com a chave privada instalada no computador local e a chave pública exportada num . CER, . PEM ou . Ficheiro CRT.
No Windows, pode utilizar o módulo pki do PowerShell para gerar o certificado.
$cert = New-SelfSignedCertificate -Subject "CN=PowerShell App-Only" -CertStoreLocation `
"Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 `
-KeyAlgorithm RSA -HashAlgorithm SHA256
Export-Certificate -Cert $cert -FilePath "./PowerShellAppOnly.cer"
Registar aplicação para autenticação apenas de aplicação
Nesta secção, irá registar uma aplicação que irá suportar a autenticação apenas da aplicação através do fluxo de credenciais de cliente.
Abra um browser e navegue para o centro de administração do Microsoft Entra e inicie sessão com uma conta de Administrador global.
Selecione Microsoft Entra ID no painel de navegação esquerdo, expanda Identidade, expanda Aplicações e, em seguida, selecione Registos de aplicações.
Selecione Novo registro. Introduza um nome para a sua aplicação, por exemplo,
Graph App-Only Auth Tutorial.Defina Tipos de conta suportados como Contas apenas neste diretório organizacional.
Deixe o URI de Redirecionamento vazio.
Selecione Registrar. Na página Descrição Geral da aplicação, copie o valor do ID da Aplicação (cliente) e do ID do Diretório (inquilino) e guarde-os, irá precisar destes valores no próximo passo.
Selecione Permissões de API em Gerenciar.
Remova a permissão User.Read predefinida em Permissões configuradas ao selecionar as reticências (...) na respetiva linha e selecionar Remover permissão.
Selecione Adicionar uma permissão e, em seguida, Microsoft Graph.
Selecione Permissões de aplicativos.
Selecione User.Read.All e, em seguida, selecione Adicionar permissões.
Selecione Conceder consentimento do administrador para...e, em seguida, selecione Sim para dar consentimento do administrador para a permissão selecionada.
Selecione Certificados e segredos em Gerir e, em seguida, selecione Certificados.
Selecione Carregar certificado. Carregue o ficheiro PowerShellAppOnly.cer ou powershell.crt que criou no passo anterior e, em seguida, selecione Adicionar.
Observação
Repare que, ao contrário dos passos ao registar para autenticação de utilizador, nesta secção, configurou as permissões do Microsoft Graph no registo de aplicações. Isto deve-se ao facto de a autenticação apenas da aplicação utilizar o fluxo de credenciais do cliente, o que requer que as permissões sejam configuradas no registo de aplicações. Veja O âmbito .default para obter detalhes.
Adicionar autenticação apenas de aplicação
Nesta secção, irá utilizar a autenticação apenas de aplicações com o SDK do PowerShell do Microsoft Graph.
Ligar com autenticação apenas de aplicação
Desligue qualquer ligação existente do Microsoft Graph com o seguinte comando.
Disconnect-MgGraphAbra o PowerShell e utilize o seguinte comando para definir a
$clientIDvariável de sessão, substituindo <your-client-id> pelo ID de cliente do registo da aplicação.$clientId = <your-client-id>Defina a
$tenantIdvariável de sessão, substituindo <your-tenant-id pelo> ID de inquilino da sua organização.$tenantId = <your-tenant-id>Defina a
$certificatevariável de sessão para o assunto do certificado criado no passo anterior.$certificate = "CN=PowerShell App-Only"Utilize o
Connect-MgGraphcomando para autenticar com o certificado do passo anterior.Connect-MgGraph -ClientId $clientId -TenantId $tenantId -CertificateName $certificateUtilize
Get-MgContextpara verificar se está autenticado com autenticação apenas de aplicação. Verifique se AuthType éAppOnly.PS > Get-MgContext ClientId : 2fb1652f-a9a0-4db9-b220-b224b8d9d38b TenantId : 601faea3-be45-4960-898f-92b379b17cd9 CertificateThumbprint : Scopes : {User.Read.All} AuthType : AppOnly AuthProviderType : ClientCredentialProvider CertificateName : CN=PowerShell App-Only Account : AppName : PowerShell Graph Tutorial ContextScope : Process Certificate : PSHostVersion : 2022.4.1 ClientTimeout : 00:05:00
Listar usuários
Nesta secção, irá listar todos os utilizadores no Azure Active Directory através da autenticação apenas de aplicações.
Na sua sessão autenticada do PowerShell, execute o seguinte comando para listar utilizadores.
Get-MgUser -Select "displayName,id,mail" -Top 25 -OrderBy "displayName"Reveja o resultado.
Id DisplayName Mail UserPrincipalName UserType -- ----------- ---- ----------------- -------- 05fb57bf-2653-4396-846d-2f210a91d9cf Adele Vance AdeleV@contoso.com a36fe267-a437-4d24-b39e-7344774d606c Alex Wilber AlexW@contoso.com 54cebbaa-2c56-47ec-b878-c8ff309746b0 Allan Deyoung AllanD@contoso.com 9cb2ad7c-8e69-46a6-a947-a02c255048de Automate Bot 9a7dcbd0-72f0-48a9-a9fa-03cd46641d49 Bianca Pisani a8989e40-be57-4c2e-bf0b-7cdc471e9cc4 Brian Johnson (TAILSPIN) BrianJ@contoso.com 9e2d4937-44ee-4af4-bd56-77a12cc3ecc4 Cameron White 8990227d-31dc-4120-a38e-f652576974f4 Christie Cline ChristieC@contoso.com ...
Código explicado
Considere o comando utilizado para listar utilizadores.
-
-SelectUtiliza para pedir propriedades específicas -
-TopUtiliza para limitar o número de utilizadores devolvidos -
-OrderByUtiliza para ordenar a resposta
Opcional: adicionar o seu próprio código
Nesta secção, irá utilizar os seus próprios comandos do SDK do PowerShell do Microsoft Graph. Pode ser um fragmento de código da documentação do Microsoft Graph ou do Graph Explorer ou código que criou. Esta secção é opcional.
Escolher uma API
Localize uma API no Microsoft Graph que gostaria de experimentar. Por exemplo, a API grupos de lista . Pode utilizar um dos exemplos na documentação da API, personalizar um pedido de API no Graph Explorer e utilizar o fragmento gerado ou utilizar o Find-MgGraphCommand comando para localizar o comando correspondente.
Por exemplo, o ponto final da API para listar grupos é GET /groups. Pode utilizá-lo para encontrar o comando do PowerShell correspondente.
PS > Find-MgGraphCommand -Uri "/groups" -Method "GET"
APIVersion: v1.0
Command Module Method URI OutputType Permissions
------- ------ ------ --- ---------- -----------
Get-MgGroup Groups GET /groups IMicrosoftGraphGroup {Directory.Read.All, Directory.ReadWrite.All, Group.Read.All, G…
APIVersion: beta
Command Module Method URI OutputType Permissions
------- ------ ------ --- ---------- -----------
Get-MgGroup Groups GET /groups IMicrosoftGraphGroup1 {Directory.Read.All, Directory.ReadWrite.All, Group.Read.All, …
O resultado indica que o Get-MgGroup comando é o comando correspondente.
Configurar as permissões
Verifique a secção Permissões da documentação de referência da API escolhida para ver que métodos de autenticação são suportados. Algumas APIs não suportam apenas aplicações, por exemplo.
Para chamar uma API com autenticação apenas de aplicação (se a API a suportar), adicione o âmbito de permissão necessário no centro de administração do Azure AD. Certifique-se de que desliga e volta a ligar utilizando a permissão apenas da aplicação.
Dica
A utilização do -ForceRefresh parâmetro com o Connect-MgGraph comando garante que as permissões recentemente configuradas são aplicadas.
Executar o comando
Agora que está ligado às permissões necessárias, execute o comando escolhido.
Parabéns!
Concluiu o tutorial apenas para aplicações do Microsoft Graph do PowerShell. Agora que tem uma aplicação de trabalho que chama o Microsoft Graph, pode experimentar e adicionar novas funcionalidades.
- Saiba como utilizar a autenticação de utilizador (delegado) com o SDK do PowerShell do Microsoft Graph.
- Visite a Descrição Geral do Microsoft Graph para ver todos os dados a que pode aceder com o Microsoft Graph.
Tem algum problema com essa seção? Se tiver, envie seus comentários para que possamos melhorar esta seção.