Create um aplicativo para acessar Microsoft Defender XDR sem 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 sem um usuário definido, por exemplo, se você estiver criando um serviço daemon ou em segundo plano.

Se você precisar de acesso programático a Microsoft Defender XDR em nome de um ou mais usuários, consulte Create um aplicativo para acessar Microsoft Defender XDR APIs em nome de um usuário e Create um aplicativo com acesso de parceiro a Microsoft Defender XDR APIs. 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
  • Valide o token.

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 guia Novo registro no portal Microsoft Defender

  3. No formulário, escolha um nome para seu aplicativo e selecione Registrar.

  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.

    Guia de uso de APIs da organização 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.

    O painel de permissão do 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.

    O painel relacionado à concessão de consentimento 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.

    O painel criar aplicativo 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. Somente para parceiros Microsoft Defender XDR: siga estas instruções para acesso ao parceiro por meio das APIs Microsoft Defender XDR, defina seu aplicativo como multilocatário, para que ele possa estar disponível em todos os locatários depois que você receber o consentimento do administrador. O acesso ao parceiro é necessário para aplicativos de terceiros, por exemplo, se você criar um aplicativo destinado a ser executado em vários locatários de clientes. Não é necessário criar um serviço que você deseja executar somente em seu locatário, como um aplicativo para seu próprio uso que só interagirá com seus próprios dados. Para definir seu aplicativo como multilocatário:

    • Vá para Autenticação e adicione https://portal.azure.com como o URI de redirecionamento.

    • Na parte inferior da página, em Tipos de conta com suporte, selecione as Contas em qualquer consentimento do aplicativo de diretório organizacional para seu aplicativo multilocatá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.

    O administrador global do Active Directory para cada locatário precisa selecionar o link de consentimento e aprovar seu aplicativo.

    O link de consentimento tem a seguinte estrutura:

    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.

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.

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, such as the Azure Key Vault!

$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):

    csharp
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 cliente 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://api.security.microsoft.com/.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 de token decodificado no portal 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.