Criar uma aplicação para aceder ao Microsoft Defender para Endpoint sem um utilizador

Aplica-se a:

• Plano 1 do Microsoft Defender para Ponto de Extremidade
• Plano 2 do Microsoft Defender para Ponto de Extremidade
• Microsoft Defender para Empresas

Importante

As capacidades avançadas de investigação não estão incluídas no Defender para Empresas.

Deseja experimentar o Microsoft Defender para Ponto de Extremidade? Inscreva-se para uma avaliação gratuita.

Observação

Se for um cliente do Us Government, utilize os URIs listados no Microsoft Defender para Endpoint para clientes do Us Government.

Dica

Para um melhor desempenho, pode utilizar o servidor mais próximo da localização geográfica:

• us.api.security.microsoft.com
• eu.api.security.microsoft.com
• uk.api.security.microsoft.com
• au.api.security.microsoft.com
• swa.api.security.microsoft.com

Esta página descreve como criar uma aplicação para obter acesso programático ao Defender para Endpoint sem um utilizador. Se precisar de acesso programático ao Defender para Endpoint em nome de um utilizador, veja Obter acesso com o contexto de utilizador. Se não tiver a certeza de qual o acesso de que precisa, consulte Introdução.

O Microsoft Defender para Endpoint expõe grande parte dos seus dados e ações através de um conjunto de APIs programáticas. Essas APIs irão ajudá-lo a automatizar fluxos de trabalho e a inovar com base nas capacidades do Defender para Endpoint. O acesso à API requer autenticação OAuth2.0. Para obter mais informações, veja OAuth 2.0 Authorization Code Flow (Fluxo de Código de Autorização do OAuth 2.0).

Em geral, terá de seguir os seguintes passos para utilizar as APIs:

• Crie uma aplicação Microsoft Entra.
• Obtenha um token de acesso com esta aplicação.
• Utilize o token para aceder à API do Defender para Endpoint.

Este artigo explica como criar uma aplicação Microsoft Entra, obter um token de acesso para o Microsoft Defender para Endpoint e validar o token.

Importante

A Microsoft recomenda que utilize funções com menos permissões. Isto ajuda a melhorar a segurança da sua organização. O Administrador Global é uma função altamente privilegiada que deve ser limitada a cenários de emergência quando não pode utilizar uma função existente.

Criar um aplicativo

1. Inicie sessão no portal do Azure com um utilizador que tenha a função de Administrador Global.

2. Navegue paraRegistos> da Aplicação Microsoft Entra ID>Novo registo.

   

3. No formulário de registo, selecione um nome para a sua aplicação e, em seguida, selecione Registar.

4. Para permitir que a sua aplicação aceda ao Defender para Endpoint e lhe atribua a permissão "Ler todos os alertas", na página da aplicação, selecione Permissões> da API Adicionar APIs depermissão> que aminha organização utiliza>, escreva WindowsDefenderATP e, em seguida, selecione WindowsDefenderATP.

   Observação

   WindowsDefenderATP não aparece na lista original. Comece a escrever o respetivo nome na caixa de texto para vê-lo aparecer.

   

   Selecione Alerta de permissões> daaplicação.Read.All e, em seguida, selecione Adicionar permissões.

   

5. Selecione as permissões adequadas. Read All Alerts é apenas um exemplo. Aqui estão alguns exemplos:

   • Para executar consultas avançadas, selecione a Run advanced queries permissão.
   • Para isolar um dispositivo, selecione a Isolate machine permissão.
   • Para determinar de que permissão precisa, veja a secção Permissões na API que está interessado em chamar.

6. Selecione Conceder consentimento.

   Observação

   Sempre que adicionar uma permissão, tem de selecionar Conceder consentimento para que a nova permissão entre em vigor.

   

7. Para adicionar um segredo à aplicação, selecione Certificados & segredos, adicione uma descrição ao segredo e, em seguida, selecione Adicionar.

   Observação

   Depois de selecionar Adicionar, selecione copiar o valor do segredo gerado. Não poderá obter este valor depois de sair.

   

8. Anote o ID da aplicação e o ID do inquilino. Na página da aplicação, aceda a Descrição geral e copie o seguinte.

   

9. Apenas para Parceiros do Microsoft Defender para Endpoint. Defina a aplicação como multi-inquilino (disponível em todos os inquilinos após o consentimento). Isto é necessário para aplicações de terceiros (por exemplo, se criar uma aplicação que se destina a ser executada no inquilino de vários clientes). Isto não é necessário se criar um serviço que pretenda executar apenas no seu inquilino (por exemplo, se criar uma aplicação para a sua própria utilização que só irá interagir com os seus próprios dados). Para definir a aplicação como multi-inquilino, siga estes passos:

   1. Aceda a Autenticação e adicione https://portal.azure.com como URI de Redirecionamento.

   2. Na parte inferior da página, em Tipos de conta suportados, selecione o consentimento de contas em qualquer aplicação de diretório organizacional para a sua aplicação multi-inquilino.

      Precisa que a sua aplicação seja aprovada em cada inquilino onde pretende utilizá-la. Isto deve-se ao facto de a sua aplicação interagir com o Defender para Endpoint em nome do cliente.

      O utilizador (ou o seu cliente, se estiver a escrever uma aplicação de terceiros) tem de selecionar a ligação de consentimento e aprovar a sua aplicação. O consentimento deve ser feito com um utilizador que tenha privilégios administrativos no Active Directory.

      A ligação de consentimento é formada da seguinte forma:

      https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
      

      Onde 00000000-0000-0000-0000-000000000000 é substituído pelo ID da aplicação.

Concluído! Registou uma aplicação com êxito! Veja os exemplos abaixo para obter a aquisição e validação de tokens.

Obter um token de acesso

Para obter mais informações sobre os tokens do Microsoft Entra, consulte o tutorial do Microsoft Entra.

Usar o Windows PowerShell!

# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated quotes below.

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$sourceAppIdUri = 'https://api.securitycenter.microsoft.com/.default'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token"
$authBody = [Ordered] @{
    scope = "$sourceAppIdUri"
    client_id = "$appId"
    client_secret = "$appSecret"
    grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
$token

Utilizar C#:

O código seguinte foi testado com o NuGet Microsoft.Identity.Client 3.19.8.

Importante

O pacote NuGet Microsoft.IdentityModel.Clients.ActiveDirectory e a Biblioteca de Autenticação do Azure AD (ADAL) foram preteridos. Não foram adicionadas novas funcionalidades desde 30 de junho de 2020. Recomendamos vivamente que atualize, veja o guia de migração para obter mais detalhes.

1. Crie uma nova aplicação de consola.

2. Instale o NuGet Microsoft.Identity.Client.

3. Adicione o seguinte:

   using Microsoft.Identity.Client;
   

4. Copie e cole o seguinte código na sua aplicação (não se esqueça de atualizar as três variáveis: tenantId, appId, appSecret):

   string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
   string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
   string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place! 
   const string authority = "https://login.microsoftonline.com";
   const string audience = "https://api.securitycenter.microsoft.com";
   
   IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();
   
   List<string> scopes = new List<string>() { $"{audience}/.default" };
   
   AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();
   
   string token = authResult.AccessToken;
   

Utilizar Python

Veja Obter token com Python.

Utilizar Curl

Observação

O procedimento seguinte pressupõe que o Curl para Windows já está instalado no seu computador.

1. Abra uma linha de comandos e defina CLIENT_ID para o ID da aplicação do Azure.

2. Defina CLIENT_SECRET como o segredo da sua aplicação do Azure.

3. Defina TENANT_ID como o ID de inquilino do Azure do cliente que pretende utilizar a sua aplicação para aceder ao Defender para Endpoint.

4. Execute o seguinte comando:

   curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=https://securitycenter.onmicrosoft.com/windowsatpservice/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k
   

   Obtém uma resposta semelhante ao seguinte fragmento de código:

   {"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}
   

Validar o token

Certifique-se de que obteve o token correto:

1. Copie e cole o token que obteve no passo anterior no JWT para o descodificar.

2. Confirme que obtém uma afirmação de funções com as permissões pretendidas.

   Na imagem seguinte, pode ver um token descodificado adquirido a partir de uma aplicação com permissões para todas as funções do Microsoft Defender para Endpoint:

   

Utilizar o token para aceder à API do Microsoft Defender para Endpoint

1. Escolha a API que pretende utilizar. Para obter mais informações, veja Supported Defender for Endpoint APIs (APIs suportadas do Defender para Endpoint).

2. Defina o cabeçalho de autorização no http pedido que envia para Bearer {token} (Portador é o esquema de autorização).

3. O tempo de expiração do token é de uma hora. Pode enviar mais do que um pedido com o mesmo token.

Segue-se um exemplo de envio de um pedido para obter uma lista de alertas com C#:

var httpClient = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");

request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

// Do something useful with the response

Confira também

• Suporte de APIs do Microsoft Defender para Ponto de Extremidade
• Aceder ao Microsoft Defender para Endpoint em nome de um utilizador

Dica

Você deseja aprender mais? Contacte a comunidade de Segurança da Microsoft na nossa Comunidade Tecnológica: Microsoft Defender para Endpoint Tech Community.