Acesso de parceiros através de APIs Microsoft Defender para Ponto de Extremidade

Aplica-se a:

• Plano 1 do Microsoft Defender para Ponto de Extremidade
• Plano 2 do Microsoft Defender para Ponto de Extremidade
• Microsoft Defender para Empresas

Importante

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

Deseja experimentar o Microsoft Defender para Ponto de Extremidade? Inscreva-se para uma avaliação gratuita.

Observação

Se for um cliente do Governo norte-americano, utilize os URIs listados no Microsoft Defender para Ponto de Extremidade para clientes do Us Government.

Dica

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 a Microsoft Defender para Ponto de Extremidade em nome dos seus clientes.

Microsoft Defender para Ponto de Extremidade 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 Microsoft Defender para Ponto de Extremidade. 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 de 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 Microsoft Defender para Ponto de Extremidade.

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

Importante

A Microsoft recomenda que você use funções com o menor número de permissões. Isto ajuda a melhorar a segurança da sua organização. O Administrador Global é uma função altamente privilegiada que deve ser limitada a cenários de emergência quando não for possível usar uma função existente.

Criar a aplicação multi-inquilino

1. Inicie sessão no seu inquilino do Azure.

2. Navegue para Microsoft Entra ID>Registros de aplicativo>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 a Microsoft Defender para Ponto de Extremidade 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 aplicação interage com Microsoft Defender para Ponto de Extremidade aplicação em nome do cliente.

   Uma conta de utilizador com as permissões adequadas para o inquilino do cliente tem de selecionar a ligação de consentimento e aprovar a 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 no inquilino do cliente e, em seguida, conceda consentimento para 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. Concluído! 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 Microsoft Entra token, veja Microsoft Entra tutorial.

Usando 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 Azure AD Authentication Library (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

Observação

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 Microsoft Defender para Ponto de Extremidade aplicação.

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 várias permissões para Microsoft Defender para Ponto de Extremidade:

   

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

Utilizar o token para aceder à API Microsoft Defender para Ponto de Extremidade

1. Escolha a API que pretende utilizar. Para obter mais informações, veja ApIs de Microsoft Defender para Ponto de Extremidade suportadas.

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
   

Confira também

• Suporte de APIs do Microsoft Defender para Ponto de Extremidade
• Aceder Microsoft Defender para Ponto de Extremidade em nome de um utilizador

Dica

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