Create uma aplicação para aceder a Microsoft Defender para Endpoint sem um utilizador

Artigo
04/26/2024

Aplica-se a:

Importante

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

Quer experimentar o Microsoft Defender para Ponto Final? Inscrever-se para uma avaliação gratuita.

Nota

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

Sugestão

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.

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:

Create 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 Microsoft Defender para Endpoint e validar o token.

Create uma aplicação

Inicie sessão no Azure com um utilizador que tenha a função de Administrador Global .
Navegue para Microsoft Entra ID>Registos de aplicações>Novo registo.
No formulário de registo, selecione um nome para a sua aplicação e, em seguida, selecione Registar.
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.

Nota

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.

Tem de selecionar as permissões relevantes. "Ler Todos os Alertas" é apenas um exemplo. Por exemplo:
- Para executar consultas avançadas, selecione a permissão "Executar consultas avançadas".
- Para isolar um dispositivo, selecione a permissão "Isolar máquina".
- Para determinar de que permissão precisa, veja a secção Permissões na API que está interessado em chamar.
Selecione Conceder consentimento.

Nota

Sempre que adicionar uma permissão, tem de selecionar Conceder consentimento para que a nova permissão entre em vigor.
Para adicionar um segredo à aplicação, selecione Certificados & segredos, adicione uma descrição ao segredo e, em seguida, selecione Adicionar.

Nota

Depois de selecionar Adicionar, selecione copiar o valor do segredo gerado. Não poderá obter este valor depois de sair.
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.
Apenas para Parceiros 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 sua aplicação como multi-inquilino:
- Aceda a Autenticação e adicione https://portal.azure.com como URI de Redirecionamento.
- 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
```
Em que 000000000-0000-0000-0000-0000000000000 é substituído pelo ID da aplicação.

Feito! 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 tokens de Microsoft Entra, veja o tutorial Microsoft Entra.

Utilizar o 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 Azure AD Authentication Library (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.

Create uma nova aplicação de consola.
Instale o NuGet Microsoft.Identity.Client.
Adicione o seguinte:
```
using Microsoft.Identity.Client;
```

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

Nota

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

Abra uma linha de comandos e defina CLIENT_ID para o ID da aplicação do Azure.
Defina CLIENT_SECRET para o segredo da sua aplicação do Azure.
Defina TENANT_ID para o ID de inquilino do Azure do cliente que pretende utilizar a sua aplicação para aceder ao Defender para Endpoint.

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

Obterá uma resposta no seguinte formulário:

{"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:

Copie e cole o token que obteve no passo anterior no JWT para o descodificar.
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 de Microsoft Defender para Endpoint:

Utilizar o token para aceder à API Microsoft Defender para Endpoint

Escolha a API que pretende utilizar. Para obter mais informações, veja Supported Defender for Endpoint APIs (APIs suportadas do Defender para Endpoint).
Defina o cabeçalho de autorização no pedido http que envia para "Portador {token}" (Portador é o esquema de autorização).
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

Consulte também