Partilhar via

Criar uma aplicação com acesso de parceiro a APIs Microsoft Defender XDR

  • Artigo

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 Microsoft Entra que tem acesso programático a Microsoft Defender XDR, em nome de utilizadores em vários inquilinos. As aplicações multi-inquilino são úteis para servir grandes grupos de utilizadores.

Se precisar de acesso programático a Microsoft Defender XDR em nome de um único utilizador, consulte Criar uma aplicação para aceder Microsoft Defender XDR APIs em nome de um utilizador. Se precisar de acesso sem um utilizador explicitamente definido (por exemplo, se estiver a escrever uma aplicação em segundo plano ou um daemon), veja Criar uma aplicação para aceder a Microsoft Defender XDR sem um utilizador. 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.

Uma vez que esta aplicação é multi-inquilino, também precisará do consentimento do administrador de cada inquilino em nome dos respetivos utilizadores.

Este artigo explica como:

  • Criar uma aplicação de Microsoft Entra multi-inquilino
  • Obtenha o consentimento autorizado do administrador de utilizador para que a sua aplicação aceda à Microsoft Defender XDR de que precisa.
  • Obter um token de acesso para Microsoft Defender XDR
  • Validar o token

Microsoft Defender XDR 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 Microsoft Defender XDR. 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:

  • Criar uma aplicação de Microsoft Entra multi-inquilino.
  • Obtenha autorização (consentimento) por parte do administrador de utilizador para que a sua aplicação aceda aos recursos Microsoft Defender XDR de que precisa.
  • Obtenha um token de acesso com esta aplicação.
  • Utilize o token para aceder à API Microsoft Defender XDR.

Os passos seguintes mostram-lhe como criar uma aplicação de Microsoft Entra multi-inquilino, obter um token de acesso para Microsoft Defender XDR e validar o token.

Criar a aplicação multi-inquilino

  1. Inicie sessão no Azure.

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

    Secção de registo de uma aplicação no portal do Microsoft Defender

  3. No formulário de registo:

    • Escolha um nome para a sua aplicação.
    • Em Tipos de conta suportados, selecione Contas em qualquer diretório organizacional (Qualquer Microsoft Entra diretório) – Multi-inquilino.
    • Preencha a secção URI de Redirecionamento . Selecione Escrever Web e atribua o URI de redirecionamento como https://portal.azure.com.

    Depois de preencher o formulário, selecione Registar.

    Secções de registo de uma aplicação no portal do Microsoft Defender

  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.

    A secção utilização de APIs no portal do Microsoft Defender

  5. Selecione Permissões da aplicação. Escolha as permissões relevantes para o seu cenário (por exemplo, Incident.Read.All) e, em seguida, selecione Adicionar permissões.

    Painel de permissões de uma aplicação no portal do Microsoft Defender

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

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

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

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

    Sugestão

    Depois de selecionar Adicionar, selecione copiar o valor do segredo gerado. Não poderá obter o valor do segredo depois de sair.

    A secção Adição de segredos no portal do Microsoft Defender

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

    O painel Descrição Geral no portal do Microsoft Defender

  9. Adicione a aplicação ao inquilino do utilizador.

    Uma vez que a sua aplicação interage com Microsoft Defender XDR em nome dos seus utilizadores, tem de ser aprovada para todos os inquilinos nos quais pretenda utilizá-la.

    Um administrador do inquilino do utilizador tem de ver a ligação de consentimento e aprovar a sua aplicação.

    A ligação 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 00000000-0000-0000-0000-000000000000 devem ser substituídos pelo ID da Aplicação.

    Depois de clicar na ligação de consentimento, inicie sessão como administrador do inquilino do utilizador e conceda consentimento para a aplicação.

    A página da aplicação de consentimento no portal do Microsoft Defender

    Também terá de pedir ao utilizador o ID do inquilino. O ID do inquilino é um dos identificadores utilizados para adquirir tokens de acesso.

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

Importante

Embora os exemplos nesta secção o incentivem a colar valores secretos para fins de teste, nunca deve codificar segredos para uma aplicação em execução na produção. Um terceiro pode utilizar o segredo para aceder aos recursos. Pode ajudar a manter os segredos da sua aplicação seguros com o Azure Key Vault. Para obter um exemplo prático de como pode proteger a sua aplicação, veja Gerir segredos nas suas aplicações de servidor com o Azure Key Vault.

Sugestão

Nos exemplos seguintes, utilize o ID de inquilino de um utilizador para testar se o script está a funcionar.

Obter um token de acesso com 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 com C#

Nota

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.

  1. Crie uma nova aplicação de consola.

  2. Instale o NuGet Microsoft.Identity.Client.

  3. Adicione a seguinte linha:

    using Microsoft.Identity.Client;

  4. Copie e cole o seguinte código na sua aplicação (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 com 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 com o curl

Nota

O Curl está pré-instalado no Windows 10, versões 1803 e posteriores. Para outras versões do Windows, transfira e instale a ferramenta diretamente a partir do site oficial do Curl.

  1. Abra uma linha de comandos e defina CLIENT_ID para o ID da aplicação do Azure.
  2. Defina CLIENT_SECRET para o segredo da sua aplicação do Azure.
  3. Defina TENANT_ID para o ID de inquilino do Azure do utilizador que pretende utilizar a sua aplicação para aceder a 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 terá o seguinte aspeto:

{"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 tokens Web JSON, 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:

O painel Token Descodificado no portal do Microsoft Defender

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();

Sugestão

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