Criar uma aplicação para aceder Microsoft Defender XDR APIs em nome de um utilizador

Aplica-se a:

• Microsoft Defender XDR

Importante

Algumas informações estão relacionadas com o produto pré-lançado que pode ser substancialmente modificado antes de ser lançado comercialmente. A Microsoft não oferece garantias, expressas ou implícitas, em relação às informações aqui fornecidas.

Esta página descreve como criar uma aplicação para obter acesso programático a Microsoft Defender XDR em nome de um único utilizador.

Se precisar de acesso programático a Microsoft Defender XDR sem um utilizador definido (por exemplo, se estiver a escrever uma aplicação em segundo plano ou um daemon), consulte Criar uma aplicação para aceder a Microsoft Defender XDR sem um utilizador. Se precisar de fornecer acesso a vários inquilinos (por exemplo, se estiver a servir uma organização grande ou um grupo de clientes), consulte Criar uma aplicação com acesso de parceiro a apIs Microsoft Defender XDR. Se não tiver a certeza de que tipo de acesso precisa, consulte Introdução.

Microsoft Defender XDR expõe grande parte dos seus dados e ações através de um conjunto de APIs programáticas. Essas APIs ajudam-no a automatizar fluxos de trabalho e a utilizar as capacidades do Microsoft Defender XDR. Este 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 estas APIs:

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

Este artigo explica como:

• Criar uma aplicação Microsoft Entra
• Obter um token de acesso para Microsoft Defender XDR
• Validar o token

Nota

Ao aceder à API Microsoft Defender XDR em nome de um utilizador, precisará das permissões de aplicação e do utilizador corretas.

Sugestão

Se tiver permissão para efetuar uma ação no portal, tem a permissão para executar a ação na API. Para obter mais informações sobre funções e permissões, veja Manage access to Microsoft Defender XDR with Microsoft Entra global roles (Gerir o acesso a Microsoft Defender XDR com Microsoft Entra funções globais).

Criar uma aplicação

1. Inicie sessão no Azure.

2. Navegue para Microsoft Entra ID>Registos de aplicações>Novo registo.

   

3. No formulário, selecione um nome para a sua aplicação e introduza as seguintes informações para o URI de redirecionamento e, em seguida, selecione Registar.

   

   • Tipo de aplicação: Cliente público
   • URI de Redirecionamento:https://portal.azure.com

4. Na página da sua aplicação, selecione Permissões> da API Adicionar APIs depermissão> quea minha organização utiliza>, escreva Proteção Contra Ameaças da Microsoft e selecione Proteção Contra Ameaças da Microsoft. A sua aplicação pode agora aceder a Microsoft Defender XDR.

   Sugestão

   O Microsoft Threat Protection é um nome antigo para Microsoft Defender XDR e não será apresentado na lista original. Tem de começar a escrever o respetivo nome na caixa de texto para vê-lo aparecer.

   

   • Selecione Permissões delegadas. Escolha as permissões relevantes para o seu cenário (por exemplo , Incident.Read) e, em seguida, selecione Adicionar permissões.

     

   Nota

   Tem de selecionar as permissões relevantes para o seu cenário. Ler todos os incidentes é apenas um exemplo. Para determinar de que permissão precisa, veja a secção Permissões na API que pretende chamar.

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

5. Selecione Conceder consentimento do administrador. Sempre que adicionar uma permissão, tem de selecionar Conceder consentimento do administrador para que esta entre em vigor.

   

6. Registe o ID da aplicação e o ID do inquilino num local seguro. Estão listados em Descrição geral na página da sua aplicação.

   

Obter um token de acesso

Para obter mais informações sobre tokens de Microsoft Entra, veja o tutorial Microsoft Entra.

Obter um token de acesso em nome de um utilizador com o PowerShell

Utilize a biblioteca MSAL.PS para adquirir tokens de acesso com permissões Delegadas. Execute os seguintes comandos para obter o token de acesso em nome de um utilizador:

Install-Module -Name MSAL.PS # Install the MSAL.PS module from PowerShell Gallery

$TenantId = " " # Paste your directory (tenant) ID here.
$AppClientId="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Paste your application (client) ID here.

$MsalParams = @{
   ClientId = $AppClientId
   TenantId = $TenantId
   Scopes   = 'https://graph.microsoft.com/User.Read.All','https://graph.microsoft.com/Files.ReadWrite','https://api.securitycenter.windows.com/AdvancedQuery.Read'
}

$MsalResponse = Get-MsalToken @MsalParams
$AccessToken  = $MsalResponse.AccessToken
 
$AccessToken # Display the token in PS console

Validar o token

1. Copie e cole o token no JWT para o descodificar.
2. Confirme que a afirmação de funções no token descodificado contém as permissões pretendidas.

Na imagem seguinte, pode ver um token descodificado adquirido a partir de uma aplicação, com Incidents.Read.All, Incidents.ReadWrite.Alle AdvancedHunting.Read.All permissões:

Utilizar o token para aceder à API de Microsoft Defender XDR

1. Escolha a API que pretende utilizar (incidentes ou investigação avançada). Para obter mais informações, veja ApIs de Microsoft Defender XDR suportadas.
2. No pedido http que está prestes a enviar, defina o cabeçalho de autorização como "Bearer" <token>, Portador sendo o esquema de autorização e token a ser o token validado.
3. O token irá expirar dentro de uma hora. Pode enviar mais do que um pedido durante este período com o mesmo token.

O exemplo seguinte mostra como enviar um pedido para obter uma lista de incidentes com C#.

    var httpClient = new HttpClient();
    var request = new HttpRequestMessage(HttpMethod.Get, "https://api.security.microsoft.com/api/incidents");

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

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

Artigos relacionados

• descrição geral das APIs Microsoft Defender XDR
• Aceder às APIs Microsoft Defender XDR
• Criar uma aplicação "Hello mundo"
• Criar uma aplicação para aceder a Microsoft Defender XDR sem um utilizador
• Criar uma aplicação com acesso de parceiro multi-inquilino às APIs Microsoft Defender XDR
• Saiba mais sobre os limites e o licenciamento da API
• Compreender os códigos de erro
• Autorização OAuth 2.0 para início de sessão do utilizador e acesso à API

Sugestão

Quer saber mais? Interaja com a comunidade do Microsoft Security na nossa Tech Community: Microsoft Defender XDR Tech Community.