Create um aplicativo para acessar APIs Microsoft Defender XDR em nome de um usuário

  • Artigo

Aplica-se a:

  • Microsoft Defender XDR

Importante

Algumas informações estão relacionadas a produtos pré-lançados que podem ser substancialmente modificados antes de seu lançamento comercial. A Microsoft não faz garantias, expressas ou implícitas, quanto às informações fornecidas aqui.

Esta página descreve como criar um aplicativo para obter acesso programático a Microsoft Defender XDR em nome de um único usuário.

Se você precisar de acesso programático a Microsoft Defender XDR sem um usuário definido (por exemplo, se estiver escrevendo um aplicativo em segundo plano ou daemon), consulte Create um aplicativo para acessar Microsoft Defender XDR sem um usuário. Se você precisar fornecer acesso para vários locatários, por exemplo, se estiver atendendo uma grande organização ou um grupo de clientes, consulte Create um aplicativo com acesso de parceiro a APIs Microsoft Defender XDR. Se você não tiver certeza de qual tipo de acesso precisa, consulte Introdução.

Microsoft Defender XDR expõe grande parte de seus dados e ações por meio de um conjunto de APIs programáticas. Essas APIs ajudam você a automatizar fluxos de trabalho e a usar os recursos do Microsoft Defender XDR. Esse acesso à API requer autenticação OAuth2.0. Para obter mais informações, consulte Fluxo de código de autorização do OAuth 2.0.

Em geral, você precisará tomar as seguintes etapas para usar estas APIs:

  • Create um aplicativo de Microsoft Entra.
  • Obtenha um token de acesso usando este aplicativo.
  • Use o token para acessar Microsoft Defender XDR API.

Este artigo explica como:

  • Create um aplicativo de Microsoft Entra
  • Obter um token de acesso para Microsoft Defender XDR
  • Validar o token

Observação

Ao acessar Microsoft Defender XDR API em nome de um usuário, você precisará das permissões corretas do aplicativo e das permissões do usuário.

Dica

Se você tiver a permissão para executar uma ação no portal, terá a permissão para executar a ação na API.

Criar um aplicativo

  1. Entre no Azure como usuário com a função de Administrador Global .

  2. Navegue até Microsoft Entra ID>Registros de aplicativo>Novo registro.

    A opção Novo registro no painel Gerenciar no portal do Azure

  3. No formulário, escolha um nome para seu aplicativo e insira as seguintes informações para o URI de redirecionamento e selecione Registrar.

    O painel de registro do aplicativo no portal do Azure

  4. Em sua página de aplicativo, selecione Permissões >de APIAdicionar APIs depermissão>que minha organização usa>, digite Proteção contra Ameaças da Microsoft e selecione Proteção contra Ameaças da Microsoft. Seu aplicativo agora pode acessar Microsoft Defender XDR.

    Dica

    A Proteção contra Ameaças da Microsoft é um nome antigo para Microsoft Defender XDR e não aparecerá na lista original. Você precisa começar a escrever seu nome na caixa de texto para vê-lo aparecer.

    Painel APIs da sua organização no portal Microsoft Defender

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

      O painel Permissões Delegadas no portal Microsoft Defender

    Observação

    Você precisa selecionar as permissões relevantes para o cenário. Ler todos os incidentes é apenas um exemplo. Para determinar qual permissão você precisa, examine a seção Permissões na API que você deseja 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 você adicionar uma permissão, você deve selecionar Conceder consentimento do administrador para que ela entre em vigor.

    O painel de concessão de consentimento do administrador no portal Microsoft Defender

  6. Registre sua ID do aplicativo e sua ID de locatário em algum lugar seguro. Eles estão listados em Visão geral em sua página de aplicativo.

    O painel Visão geral no portal Microsoft Defender

Obter um token de acesso

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

Obter um token de acesso em nome de um usuário usando o PowerShell

Use 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 usuário:

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 decodificá-lo.
  2. Verifique se a declaração de funções dentro do token decodificado contém as permissões desejadas.

Na imagem a seguir, você pode ver um token decodificado adquirido de um aplicativo, com Incidents.Read.All, Incidents.ReadWrite.Alle AdvancedHunting.Read.All permissões:

A seção permissões no painel Token Decodificado no portal do Microsoft Defender

Use o token para acessar a API Microsoft Defender XDR

  1. Escolha a API que você deseja usar (incidentes ou caça avançada). Para obter mais informações, consulte APIs de Microsoft Defender XDR com suporte.
  2. Na solicitação http que você está prestes a enviar, defina o cabeçalho de autorização como "Bearer" <token>, Portador sendo o esquema de autorização e token sendo seu token validado.
  3. O token expirará dentro de uma hora. Você pode enviar mais de uma solicitação durante esse tempo com o mesmo token.

O exemplo a seguir mostra como enviar uma solicitação para obter uma lista de incidentes usando 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();

Dica

Você deseja aprender mais? Engage com a comunidade de Segurança da Microsoft em nossa Comunidade Tecnológica: Microsoft Defender XDR Tech Community.