Create um aplicativo com acesso de parceiro a APIs Microsoft Defender XDR

  • 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 Microsoft Entra que tenha acesso programático a Microsoft Defender XDR, em nome de usuários em vários locatários. Aplicativos multilocatários são úteis para atender grandes grupos de usuários.

Se você precisar de acesso programático a Microsoft Defender XDR em nome de um único usuário, consulte Create um aplicativo para acessar Microsoft Defender XDR APIs em nome de um usuário. Se você precisar de acesso sem um usuário definido explicitamente (por exemplo, se você estiver escrevendo um aplicativo em segundo plano ou daemon), consulte Create um aplicativo para acessar Microsoft Defender XDR sem um usuário. 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.

Como esse aplicativo é multilocatário, você também precisará do consentimento do administrador de cada locatário em nome de seus usuários.

Este artigo explica como:

  • Create um aplicativo de Microsoft Entra de vários locatários
  • Obtenha o consentimento autorizado do administrador do usuário para que seu aplicativo acesse o Microsoft Defender XDR de recursos necessários.
  • Obter um token de acesso para Microsoft Defender XDR
  • Validar o token

Microsoft Defender XDR expõe grande parte de seus dados e ações por meio de um conjunto de APIs programáticas. Essas APIs ajudarão você a automatizar fluxos de trabalho e inovar com base em recursos Microsoft Defender XDR. O 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 as APIs:

  • Create um aplicativo de Microsoft Entra de vários locatários.
  • Obtenha autorização (consentimento) pelo administrador do usuário para que seu aplicativo acesse Microsoft Defender XDR recursos necessários.
  • Obtenha um token de acesso usando este aplicativo.
  • Use o token para acessar Microsoft Defender XDR API.

As etapas a seguir com orientam como criar um aplicativo de Microsoft Entra de vários locatários, obter um token de acesso para Microsoft Defender XDR e validar o token.

Create o aplicativo multilocatário

  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.

    Seção de registro de um aplicativo no portal do Microsoft Defender

  3. No formulário de registro:

    • Escolha um nome para seu aplicativo.
    • Em Tipos de conta com suporte, selecione Contas em qualquer diretório organizacional (Qualquer diretório Microsoft Entra) – Multilocatário.
    • Preencha a seção URI de redirecionamento . Selecione digite Web e forneça o URI de redirecionamento como https://portal.azure.com.

    Depois de preencher o formulário, selecione Registrar.

    Seções de registro de um aplicativo no portal Microsoft Defender

  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.

    A seção de uso de APIs no portal Microsoft Defender

  5. Selecione Permissões de aplicativos. Escolha as permissões relevantes para seu cenário (por exemplo, Incident.Read.All) e selecione Adicionar permissões.

    Painel de permissão de um aplicativo 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'.

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

    Uma seção para conceder o consentimento do administrador no portal do Microsoft Defender

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

    Dica

    Depois de selecionar Adicionar, selecione copiar o valor secreto gerado. Você não poderá recuperar o valor secreto depois de sair.

    A seção Adição secreta no portal Microsoft Defender

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

  9. Adicione o aplicativo ao locatário do usuário.

    Como seu aplicativo interage com Microsoft Defender XDR em nome de seus usuários, ele precisa ser aprovado para cada locatário no qual você pretende usá-lo.

    Um administrador global do locatário do usuário precisa exibir o link de consentimento e aprovar seu aplicativo.

    O link de consentimento é do formulário:

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

    Os dígitos devem ser substituídos 00000000-0000-0000-0000-000000000000 pela ID do aplicativo.

    Depois de clicar no link de consentimento, entre com o Administrador Global do locatário do usuário e consenta o aplicativo.

    A página de aplicativo de consentimento no portal Microsoft Defender

    Você também precisará pedir ao usuário sua ID de locatário. A ID do locatário é um dos identificadores usados para adquirir tokens de acesso.

  • Concluído! Você registrou com êxito um aplicativo!
  • Confira exemplos abaixo para aquisição e validação de token.

Obter um token de acesso

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

Importante

Embora os exemplos nesta seção incentivem você a colar em valores secretos para fins de teste, você nunca deve codificar segredos em um aplicativo em execução em produção. Um terceiro pode usar seu segredo para acessar recursos. Você pode ajudar a manter os segredos do aplicativo seguros usando o Azure Key Vault. Para obter um exemplo prático de como você pode proteger seu aplicativo, consulte Gerenciar segredos em seus aplicativos de servidor com o Azure Key Vault.

Dica

Nos exemplos a seguir, use a ID do locatário de um usuário para testar se o script está funcionando.

Obter um token de acesso usando o PowerShell

# This code gets the application context token and saves it to a file named "Latest-token.txt" under the current directory.

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # Paste your own app secret here to test, then store it in a safe place!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"

$authBody = [Ordered] @{
    resource = $resourceAppIdUri
    client_id = $clientId
    client_secret = $appSecret
    grant_type = 'client_credentials'
}

$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token

Out-File -FilePath "./Latest-token.txt" -InputObject $token

return $token

Obter um token de acesso usando C#

Observação

O código a seguir foi testado com Nuget Microsoft.Identity.Client 3.19.8.

Importante

O pacote NuGet Microsoft.IdentityModel.Clients.ActiveDirectory e Azure AD Authentication Library (ADAL) foram preteridos. Nenhum novo recurso foi adicionado desde 30 de junho de 2020. Recomendamos que você atualize, consulte o guia de migração para obter mais detalhes.

  1. Create um novo aplicativo de console.

  2. Instale o NuGet Microsoft.Identity.Client.

  3. Adicione a seguinte linha:

    using Microsoft.Identity.Client;

  4. Copie e cole o seguinte código em seu aplicativo (não se esqueça de atualizar as três variáveis: tenantId, , clientIdappSecret):

    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;

Obter um token de acesso usando o Python

import json
import urllib.request
import urllib.parse

tenantId = '' # Paste your directory (tenant) ID here
clientId = '' # Paste your application (client) ID here
appSecret = '' # Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!

url = "https://login.windows.net/%s/oauth2/token" % (tenantId)

resourceAppIdUri = 'https://api.security.microsoft.com'

body = {
    'resource' : resourceAppIdUri,
    'client_id' : clientId,
    'client_secret' : appSecret,
    'grant_type' : 'client_credentials'
}

data = urllib.parse.urlencode(body).encode("utf-8")

req = urllib.request.Request(url, data)
response = urllib.request.urlopen(req)
jsonResponse = json.loads(response.read())
aadToken = jsonResponse["access_token"]

Obter um token de acesso usando curl

Observação

Curl é pré-instalado em Windows 10, versões 1803 e posterior. Para outras versões do Windows, baixe e instale a ferramenta diretamente do site oficial do curl.

  1. Abra um prompt de comando e defina CLIENT_ID para sua ID do aplicativo do Azure.
  2. Defina CLIENT_SECRET para o segredo do aplicativo do Azure.
  3. Defina TENANT_ID para a ID do locatário do Azure do usuário que deseja usar seu aplicativo para acessar Microsoft Defender XDR.
  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

Uma resposta bem-sucedida será semelhante a esta:

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

Validar o token

  1. Copie e cole o token no site do validador de token Web JSON, 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:

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