Criar scripts do PowerShell com o Microsoft Graph e a autenticação somente aplicativo

Este tutorial ensina como criar um script do PowerShell que usa o microsoft API do Graph para acessar dados usando autenticação somente aplicativo. A autenticação somente aplicativo é uma boa opção para serviços em segundo plano ou aplicativos que precisam acessar dados para todos os usuários de uma organização.

Observação

Para saber como usar o Microsoft Graph para acessar dados em nome de um usuário, consulte este tutorial de autenticação de usuário (delegado).

Neste tutorial, você vai:

Listar usuários

Dica

Como alternativa a seguir este tutorial, você pode baixar ou clonar o repositório GitHub e seguir as instruções no README para registrar um aplicativo e configurar o projeto.

Pré-requisitos

Antes de iniciar este tutorial, você deve ter o PowerShell instalado em seu computador de desenvolvimento. O PowerShell 5.1 é o requisito mínimo, mas o PowerShell 7 é recomendado.

Você também deve ter uma conta de trabalho ou de estudante da Microsoft com a função Administrador global. Se você não tiver um locatário do Microsoft 365, poderá se qualificar para um por meio do Programa de Desenvolvedores do Microsoft 365; para obter detalhes, confira as perguntas frequentes. Como alternativa, você pode se inscrever para uma avaliação gratuita de 1 mês ou comprar um plano do Microsoft 365.

Observação

Este tutorial foi escrito com o PowerShell 7.2.2 e o SDK do Microsoft Graph PowerShell versão 1.9.5. As etapas neste guia podem funcionar com outras versões, mas isso não foi testado.

Registrar o aplicativo no portal

15 minutos restantes

Neste exercício, você registrará um novo aplicativo no Azure Active Directory para habilitar a autenticação somente aplicativo.

Criar um certificado autoassinado

O SDK do Microsoft Graph PowerShell requer um certificado para autenticação somente aplicativo. Para fins de desenvolvimento, um certificado autoassinado é suficiente. Você precisa de um certificado com a chave privada instalada no computador local e a chave pública exportada em um . CER. PEM ou . Arquivo CRT.

Windows
Linux/MacOS

No Windows, você pode usar 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"

No Linux ou no MacOS, você pode usar o OpenSSL para gerar as chaves privadas e públicas e, em seguida, usar o PowerShell para instalar a chave privada em um repositório de certificados legível pelo PowerShell.

Gere um novo certificado X509 usando o comando a seguir.

openssl req -x509 -newkey rsa:2048 -sha256 -days 365 -keyout powershell.pem -out powershell.crt -subj "/CN=PowerShell App-Only"

O OpenSSL solicita uma frase de passe PEM. Insira uma frase de passagem que você lembrará.

Crie um arquivo PFX usando o comando a seguir.

openssl pkcs12 -export -out powershell.pfx -inkey powershell.pem -in powershell.crt

O OpenSSL solicita a frase de passagem para powershell.pem, insira a frase de passagem usada na etapa anterior.
O OpenSSL solicita uma senha de exportação. Insira uma senha que você lembrará.

Abra o PowerShell e execute os comandos a seguir, substituindo <export-password> pela senha de exportação usada na etapa anterior.

using namespace System.Security.Cryptography.X509Certificates
$store = [X509Store]::new('My', 'CurrentUser', 'ReadWrite')
$store.Add([X509Certificate2]::new('./powershell.pfx', '<export-password>', [X509KeyStorageFlags]::PersistKeyS
et))
$store.Dispose()

Registrar aplicativo para autenticação somente aplicativo

Nesta seção, você registrará um aplicativo que dará suporte à autenticação somente aplicativo usando o fluxo de credenciais do cliente.

Abra um navegador e navegue até o centro de administração do Azure Active Directory e faça logon usando uma conta Administrador global.
Selecione Azure Active Directory na navegação esquerda e selecione Registros de aplicativos em Gerenciar.
Selecione Novo registro. Insira um nome para seu aplicativo, por exemplo, Graph App-Only Auth Tutorial.
Defina tipos de conta com suporte apenas para contas neste diretório organizacional.
Deixe o URI de Redirecionamento vazio.
Selecione Registrar. Na página Visão geral do aplicativo, copie o valor da ID do Aplicativo (cliente) e da ID do Diretório (locatário) e salve-os, você precisará desses valores na próxima etapa.
Selecione Permissões de API em Gerenciar.
Remova a permissão padrão User.Read em Permissões configuradas selecionando as reticências (...) em sua linha e selecionando 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 selecione Sim para fornecer o consentimento do administrador para a permissão selecionada.
Selecione Certificados e segredos em Gerenciar e selecione Certificados.
Selecione Carregar certificado. Carregue o arquivo PowerShellAppOnly.cer ou powershell.crt que você criou na etapa anterior e selecione Adicionar.

Observação

Observe que, ao contrário das etapas ao se registrar para autenticação do usuário, nesta seção você configurou as permissões do Microsoft Graph no registro do aplicativo. Isso ocorre porque a auth somente aplicativo usa o fluxo de credenciais do cliente, o que exige que as permissões sejam configuradas no registro do aplicativo. Consulte O escopo .default para obter detalhes.

Adicionar autenticação somente aplicativo

10 minutos restantes

Nesta seção, você usará a autenticação somente aplicativo com o SDK do Microsoft Graph PowerShell.

Conectar-se com a autenticação somente aplicativo

Desconecte qualquer conexão existente do Microsoft Graph usando o comando a seguir.
```
Disconnect-MgGraph
```
Abra o PowerShell e use o comando a seguir para definir a $clientID variável de sessão, substituindo <a id> do cliente pela ID do cliente do registro do aplicativo.
```
$clientId = <your-client-id>
```
Defina a $tenantId variável de sessão, substituindo <sua id de locatário pela> ID do locatário da sua organização.
```
$tenantId = <your-tenant-id>
```
Defina a $certificate variável de sessão como o assunto do certificado criado na etapa anterior.
```
$certificate = "CN=PowerShell App-Only"
```

Use o Connect-MgGraph comando para autenticar usando o certificado da etapa anterior.

Connect-MgGraph -ClientId $clientId -TenantId $tenantId -CertificateName $certificate

Use Get-MgContext para verificar se você está autenticado com autenticação somente de aplicativo. Verifique se o 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

8 minutos restantes

Nesta seção, você listará todos os usuários do Azure Active Directory usando autenticação somente aplicativo.

Em sua sessão autenticada do PowerShell, execute o comando a seguir para listar usuários.
```
Get-MgUser -Select "displayName,id,mail" -Top 25 -OrderBy "displayName"
```

Examine a saída.

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 usado para listar usuários.

Ele usa para solicitar propriedades específicas -Select
Ele usa para limitar o número de usuários retornados -Top
Ele usa -OrderBy para classificar a resposta

Opcional: adicionar seu próprio código

5 minutos restantes

Nesta seção, você usará seus próprios comandos do SDK do Microsoft Graph PowerShell. Isso pode ser um snippet de código da documentação do Microsoft Graph ou do Graph Explorer ou código que você criou. Esta seção é opcional.

Escolher uma API

Encontre uma API no Microsoft Graph que você gostaria de experimentar. Por exemplo, a API de grupos de lista . Você pode usar um dos exemplos na documentação da API, personalizar uma solicitação de API no Graph Explorer e usar o snippet gerado ou usar o Find-MgGraphCommand comando para localizar o comando correspondente.

Por exemplo, o ponto de extremidade da API para listar grupos é GET /groups. Você pode usá-lo para localizar 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, …

A saída indica que o Get-MgGroup comando é o comando correspondente.

Configurar as permissões

Verifique a seção Permissões da documentação de referência da API escolhida para ver quais métodos de autenticação têm suporte. Algumas APIs não dão suporte somente a aplicativos, por exemplo.

Para chamar uma API com autenticação somente aplicativo (se a API dá suporte a ela), adicione o escopo de permissão necessário no centro de administração Azure AD. Certifique-se de desconectar e reconectar usando permissão somente de aplicativo.

Dica

O uso do -ForceRefresh parâmetro com o Connect-MgGraph comando garante que as permissões recém-configuradas sejam aplicadas.

Executar o comando

Agora que você está conectado com as permissões necessárias, execute o comando escolhido.

Parabéns!

100% concluído!

Você concluiu o tutorial somente de aplicativo do Microsoft Graph do PowerShell. Agora que você tem um aplicativo de trabalho que chama Microsoft Graph, você pode experimentar e adicionar novos recursos.

Saiba como usar a autenticação de usuário (delegada) com o SDK do Microsoft Graph PowerShell.
Visite a visão geral do Microsoft Graph para ver todos os dados que você pode acessar com o Microsoft Graph.

Compartilhar via

Pré-requisitos

Registrar o aplicativo no portal

Criar um certificado autoassinado

Registrar aplicativo para autenticação somente aplicativo

Adicionar autenticação somente aplicativo

Conectar-se com a autenticação somente aplicativo

Listar usuários

Código explicado

Opcional: adicionar seu próprio código

Escolher uma API

Configurar as permissões

Executar o comando

Parabéns!