Utilizar Microsoft Defender para Endpoint APIs

Esta página descreve como criar uma aplicação para obter acesso programático ao Defender para Endpoint em nome de um utilizador.

Se precisar de acesso programático Microsoft Defender para Endpoint sem um utilizador, veja Access Microsoft Defender para Endpoint com o contexto da aplicação.

Se não tiver a certeza de qual o acesso de que precisa, leia a página Introduçã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 permitem-lhe automatizar fluxos de trabalho e inovar com base nas capacidades 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:

• Criar uma aplicação Microsoft Entra
• Obter um token de acesso com esta aplicação
• Utilizar o token para aceder à API do Defender para Endpoint

Esta página explica como criar uma aplicação Microsoft Entra, obter um token de acesso para Microsoft Defender para Endpoint e validar o token.

Criar uma aplicação

1. Inicie sessão no portal do Azure.

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

   

3. Quando for apresentada a página Registar uma aplicação , introduza as informações de registo da sua aplicação:

   • Nome – introduza um nome de aplicação relevante que seja apresentado aos utilizadores da aplicação.

   • Tipos de conta suportados – selecione as contas que pretende que a sua aplicação suporte.

     
     

     Tipos de conta suportados	Descrição
     Contas apenas neste diretório organizacional	Selecione esta opção se estiver a criar uma aplicação de linha de negócio (LOB). Esta opção não está disponível se não estiver a registar a aplicação num diretório. Esta opção mapeia para Microsoft Entra inquilino único. Esta opção é a opção predefinida, a menos que esteja a registar a aplicação fora de um diretório. Nos casos em que a aplicação está registada fora de um diretório, a predefinição é Microsoft Entra contas Microsoft multi-inquilino e pessoais.
     Contas em qualquer diretório organizacional	Selecione esta opção se quiser direcionar todos os clientes empresariais e educativos. Esta opção mapeia para um multi-inquilino só de Microsoft Entra. Se registou a aplicação como Microsoft Entra inquilino único, pode atualizá-la para ser Microsoft Entra multi-inquilino e regressar ao inquilino único através do painel Autenticação.
     Contas em qualquer diretório organizacional e contas Microsoft pessoais	Selecione esta opção para direcionar o conjunto mais vasto de clientes. Esta opção mapeia para Microsoft Entra contas Microsoft multi-inquilino e pessoais. Se registou a aplicação como Microsoft Entra contas Microsoft multi-inquilino e pessoais, não poderá alterá-la na IU. Em vez disso, tem de utilizar o editor de manifestos da aplicação para alterar os tipos de conta suportados.

   • URI de Redirecionamento (opcional) – selecione o tipo de aplicação que está a criar, Cliente Web ou Público (móvel & ambiente de trabalho) e, em seguida, introduza o URI de redirecionamento (ou URL de resposta) para a sua aplicação.

     • Para aplicações Web, forneça o URL base da sua aplicação. Por exemplo, http://localhost:31544 pode ser o URL de uma aplicação Web em execução no seu computador local. Os utilizadores utilizariam este URL para iniciar sessão numa aplicação cliente Web.

     • Para aplicações cliente públicas, forneça o URI utilizado pelo Microsoft Entra ID para devolver respostas de tokens. Introduza um valor específico para a sua aplicação, como myapp://auth.

     Para ver exemplos específicos de aplicações Web ou aplicações nativas, veja os nossos inícios rápidos.

     Quando terminar, selecione Registar.

4. Permita que a aplicação aceda a Microsoft Defender para Endpoint e atribua-lhe a permissão "Alertas de leitura":

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

     Nota

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

     

   • Selecione Alerta de permissões>delegadas.Ler> selecione Adicionar permissões.

     

   Importante

   Selecione as permissões relevantes. Os alertas de leitura são apenas um exemplo.

   Por exemplo:

   • Para executar consultas avançadas, selecione Executar permissão de consultas avançadas .

   • Para isolar um dispositivo, selecione Isolar permissão do computador .

   • Para determinar de que permissão precisa, veja a secção Permissões na API que está interessado em chamar.

   • Selecione Conceder consentimento.

     Nota

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

     

5. Anote o ID da aplicação e o ID do inquilino.

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

   

Obter um token de acesso

Para obter mais informações sobre tokens de Microsoft Entra, veja Microsoft Entra tutorial.

Utilizar C#

Este exemplo utiliza a Biblioteca de Autenticação da Microsoft (MSAL) para adquirir um token de forma interativa. Antes de o executar:

• Adicione o pacote NuGet Microsoft.Identity.Client no seu projeto.
• No registo da sua aplicação, configure uma plataforma de aplicações móveis e desktop com o http://localhost URI de redirecionamento, para que o fluxo interativo possa devolver o token.
• Copie/cole a seguinte classe na sua aplicação, depois ligue ao AcquireUserTokenAsync com o ID da sua aplicação e o ID do inquilino. O utilizador é convidado a iniciar sessão de forma interativa; A palavra-passe deles nunca é controlada pela tua aplicação.

    namespace WindowsDefenderATP
    {
        using System.Linq;
        using System.Threading.Tasks;
        using Microsoft.Identity.Client;

        public static class WindowsDefenderATPUtils
        {
            private const string Authority = "https://login.microsoftonline.com";

            // Microsoft Defender for Endpoint APIs expect tokens issued for this resource.
            private static readonly string[] Scopes = { "https://api.securitycenter.microsoft.com/.default" };

            public static async Task<string> AcquireUserTokenAsync(string appId, string tenantId)
            {
                // Public client application for a native (desktop) app.
                // No client secret or user password is stored or handled by the app.
                var app = PublicClientApplicationBuilder
                    .Create(appId)
                    .WithAuthority($"{Authority}/{tenantId}")
                    .WithDefaultRedirectUri() // http://localhost - register as a public client redirect URI
                    .Build();

                var account = (await app.GetAccountsAsync().ConfigureAwait(false)).FirstOrDefault();

                try
                {
                    // Reuse a cached token when one is available.
                    var silentResult = await app
                        .AcquireTokenSilent(Scopes, account)
                        .ExecuteAsync()
                        .ConfigureAwait(false);

                    return silentResult.AccessToken;
                }
                catch (MsalUiRequiredException)
                {
                    // First run or expired session: prompt the user to sign in.
                    // Uses the authorization code flow with PKCE and supports
                    // multifactor authentication and Conditional Access.
                    var interactiveResult = await app
                        .AcquireTokenInteractive(Scopes)
                        .ExecuteAsync()
                        .ConfigureAwait(false);

                    return interactiveResult.AccessToken;
                }
            }
        }
    }

Validar o token

Verifique se tem um token correto:

• Copie/cole no JWT o token que obteve no passo anterior para o descodificar.

• Confirme que obtém uma afirmação "scp" com as permissões de aplicação pretendidas.

• Na captura de ecrã abaixo, pode ver um token descodificado adquirido na aplicação no tutorial:

  

Utilizar o token para aceder à API Microsoft Defender para Endpoint

• Escolha a API que pretende utilizar – Suportada Microsoft Defender para Endpoint APIs.

• Defina o cabeçalho Autorização no pedido HTTP que envia para "Portador {token}" (Portador é o esquema de Autorização).

• A Hora de expiração do token é de 1 hora (pode enviar mais do que um pedido com o mesmo token).

• Exemplo de envio de um pedido para obter uma lista de alertas com C#:

  var httpClient = new HttpClient();
  
  var request = new HttpRequestMessage(HttpMethod.Get, "https://api.security.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 Microsoft Defender para Endpoint
• Aceder Microsoft Defender para Endpoint com o contexto da aplicação