Acesso de parceiro através das APIs do Microsoft Defender para Endpoint

Aplica-se a:

• API do Microsoft Defender para Endpoint 1
• Microsoft Defender para Endpoint Plano 2
• Microsoft Defender para Empresas

Importante

As capacidades avançadas de investigação não estão incluídas no Defender para Empresas.

Quer experimentar o Microsoft Defender para Ponto Final? Inscrever-se para uma avaliação gratuita.

Nota

Se for um cliente do Us Government, utilize os URIs listados no Microsoft Defender para Endpoint para clientes do Us Government.

Sugestão

Para um melhor desempenho, pode utilizar o servidor mais próximo da localização geográfica:

• us.api.security.microsoft.com
• eu.api.security.microsoft.com
• uk.api.security.microsoft.com
• au.api.security.microsoft.com
• swa.api.security.microsoft.com
• ina.api.security.microsoft.com

Esta página descreve como criar uma aplicação Microsoft Entra para obter acesso programático ao Microsoft Defender para Endpoint em nome dos seus clientes.

O Microsoft Defender para Endpoint 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 inovar com base nas capacidades do Microsoft Defender para Endpoint. 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, tem de seguir os seguintes passos para utilizar as APIs:

1. Crie uma aplicação Microsoft Entra multi-inquilino.

2. Obtenha autorização (consentimento) por parte do administrador do cliente para que a sua aplicação aceda ao Defender para recursos de Ponto Final de que precisa.

3. Obtenha um token de acesso com esta aplicação.

4. Utilize o token para aceder à API do Microsoft Defender para Endpoint.

Os passos seguintes explicam como criar uma aplicação Microsoft Entra, obter um token de acesso para o Microsoft Defender para Endpoint e validar o token.

Importante

A Microsoft recomenda que utilize funções com o menor número de permissões. Isto ajuda a melhorar a segurança da sua organização. Administrador Global é uma função altamente privilegiada que deve ser limitada a cenários de emergência quando não pode utilizar uma função existente.

Criar a aplicação multi-inquilino

1. Inicie sessão no seu inquilino do Azure com o utilizador que tem a função de Administrador Global .

2. Navegue paraRegistos> da Aplicação Microsoft Entra ID>Novo registo.

   

3. No formulário de registo:

   • Escolha um nome para a sua aplicação.

   • Tipos de conta suportados – contas em qualquer diretório organizacional.

   • URI de Redirecionamento - escreva: Web, URI: https://portal.azure.com

     

4. Permita que a aplicação aceda ao Microsoft Defender para Endpoint e atribua-a com o conjunto mínimo de permissões necessárias para concluir a integração.

   • Na página da sua aplicação, selecione Permissões> da API Adicionar APIs depermissão> quea minha organização utiliza>, escreva WindowsDefenderATP e selecione no WindowsDefenderATP.

   • WindowsDefenderATP não aparece na lista original. Comece a escrever o respetivo nome na caixa de texto para vê-lo aparecer.

     

Pedir permissões de API

Para determinar de que permissão precisa, reveja 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 computador .

No exemplo seguinte, utilizamos a permissão Ler todos os alertas :

1. Selecione Alerta de permissões> daaplicação.Read.Todos> selecione adicionar permissões

   

2. Selecione Conceder consentimento

   • Sempre que adicionar permissão, tem de selecionar Conceder consentimento para que a nova permissão entre em vigor.

   

3. Adicione um segredo à aplicação.

   • Selecione Certificados & segredos, adicione a descrição ao segredo e selecione Adicionar.

   Depois de selecionar Adicionar, certifique-se de que copia o valor do segredo gerado. Não poderá recuperá-lo depois de sair!

   

4. Anote o ID da aplicação:

   • Na página da aplicação, aceda a Descrição geral e copie as seguintes informações:

     

5. Adicione a aplicação ao inquilino do cliente.

   Precisa que a sua aplicação seja aprovada em cada inquilino do cliente onde pretende utilizá-la. Esta aprovação é necessária porque a sua aplicação interage com a aplicação Microsoft Defender para Endpoint em nome do cliente.

   Um utilizador com o Administrador Global do inquilino do cliente tem de selecionar 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
   

   Onde 00000000-0000-0000-0000-000000000000 deve ser substituído pelo ID da Aplicação.

   Depois de selecionar a ligação de consentimento, inicie sessão como Administrador Global do inquilino do cliente e consoante a aplicação.

   

   Além disso, terá de pedir ao cliente o respetivo ID de inquilino e guardá-lo para utilização futura ao adquirir o token.

6. Feito! Registou uma aplicação com êxito! Veja os seguintes exemplos de aquisição e validação de tokens.

Obter um exemplo de token de acesso

Para obter o token de acesso em nome do cliente, utilize o ID de inquilino do cliente nas seguintes aquisições de tokens.

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

Utilizar o PowerShell

# That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
# Paste below your Tenant ID, App ID and App Secret (App key).

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
    resource = "$resourceAppIdUri"
    client_id = "$appId"
    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

Utilizar C#

Importante

O pacote NuGet Microsoft.IdentityModel.Clients.ActiveDirectory e a Biblioteca de Autenticação do Azure AD (ADAL) foram preteridos. Não foram adicionadas novas funcionalidades desde 30 de junho de 2020. Para atualizar, veja o guia de migração.

1. Crie uma nova Aplicação de Consola.

2. Instale o NuGet Microsoft.Identity.Client.

3. Adicione o seguinte através de código:

    using Microsoft.Identity.Client;
   

   Este código foi testado com NuGet Microsoft.Identity.Client.

4. Copie/Cole o seguinte código na sua aplicação (não se esqueça de atualizar as três variáveis: tenantId, appIde appSecret).

   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;
   

Utilizar o Python

Veja Obter token com Python.

Utilizar Curl

Nota

O procedimento seguinte suposto Curl para Windows já está instalado no seu computador

1. Abra uma janela de comando.

2. Defina CLIENT_ID como o ID da aplicação do Azure.

3. Defina CLIENT_SECRET como o segredo da sua aplicação do Azure.

4. Defina TENANT_ID como o ID de inquilino do Azure do cliente que pretende utilizar a sua aplicação para aceder à aplicação Microsoft Defender para Endpoint.

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

   Obtém uma resposta semelhante ao seguinte fragmento de código:

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

Validar o token

Confirme que recebeu um token correto.

1. Copie/cole no JWT o token que obtém no passo anterior para o descodificar.

2. Confirme que obtém uma afirmação de funções com as permissões adequadas.

   Na captura de ecrã seguinte, pode ver um token descodificado adquirido a partir de uma Aplicação com múltiplas permissões para o Microsoft Defender para Endpoint:

   

   A afirmação "tid" é o ID de inquilino a que o token pertence.

Utilizar o token para aceder à API do Microsoft Defender para Endpoint

1. Escolha a API que pretende utilizar. Para obter mais informações, consulte Supported Microsoft Defender for Endpoint APIs (APIs suportadas do Microsoft Defender para Endpoint).

2. Defina o cabeçalho Autorização no pedido Http para Bearer {token} o qual envia (Portador é o esquema de Autorização). A Hora de expiração do token é de uma hora (pode enviar mais do que um pedido com o mesmo token).

   Eis um exemplo do envio de um pedido para obter uma lista de alertas com C#:

   var httpClient = new HttpClient();
   
   var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.microsoft.com/api/alerts");
   
   request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
   
   var response = httpClient.SendAsync(request).GetAwaiter().GetResult();
   
    // Do something useful with the response
   

Consulte também

• APIs suportadas pelo Microsoft Defender para Endpoint
• Aceder ao Microsoft Defender para Endpoint em nome de um utilizador

Sugestão

Quer saber mais? Contacte a comunidade de Segurança da Microsoft na nossa Comunidade Tecnológica: Microsoft Defender para Endpoint Tech Community.