Criar uma aplicação para aceder a Microsoft Defender para Endpoint sem um utilizador

Ao usar APIs do Microsoft Defender para Endpoint, pode precisar de acesso ao Microsoft Defender para Endpoint sem utilizador. Por exemplo, poderá querer criar um serviço que é executado em segundo plano e que interage com o Defender para Endpoint em nome da sua organização. Se precisar de acesso a um serviço em segundo plano sem um utilizador com sessão iniciada, crie uma aplicação que possa aceder ao Defender for Endpoint sem um utilizador com sessão iniciada.

Este artigo mostra como registar uma aplicação no Microsoft Entra ID, conceder-lhe permissões apenas para aplicações e obter um token de acesso para o acesso à API do Defender for Endpoint. O acesso à API requer um fluxo de credenciais de cliente OAuth 2.0.

Pré-requisitos

Para criar um registo de aplicação no Azure, precisa de um papel Microsoft Entra com permissões de registo de aplicações que permitam a criação de aplicações, como Administrador de Aplicações.

Passo 1: criar uma aplicação no Azure

Execute os seguintes passos para registar uma aplicação e conceder-lhe permissões de API no Azure:

1. Inicie sessão no portal do Azure.

2. Procure Registos de aplicações e navegue para Registos de aplicações.

3. Selecione Novo registo.

4. Escolha um nome para a sua aplicação e, em seguida, selecione Registar.

5. Na página da sua aplicação, aceda a Gerir > Permissões > de API Adicionar APIs de permissão > que a minha organização utiliza.

6. Na página Pedir permissões da API , procure WindowsDefenderATP e selecione-o.

7. Selecione o tipo de permissões necessárias e, em seguida, selecione Adicionar permissões.

   • Permissões delegadas – inicie sessão com a sua aplicação como se fosse um utilizador.

   • Permissões de aplicação – aceda à API como um serviço.

8. Selecione as permissões adequadas para a sua aplicação. Para determinar de que permissão precisa, veja a secção Permissões na API que está a chamar. Eis dois exemplos:

   • Para executar consultas avançadas, selecione Executar consultas avançadas.

   • Para isolar um dispositivo, selecione Isolar máquina.

9. Selecione Adicionar permissão.

Passo 2: adicionar um segredo à sua aplicação

Os passos seguintes descrevem como autenticar a sua aplicação usando um segredo de aplicação. Para autenticar a sua aplicação com um certificado, veja Criar um certificado público autoassinado para autenticar a sua aplicação.

1. Na página da aplicação, selecione Certificados & segredos>Novo segredo do cliente.

2. No painel Adicionar um segredo do cliente , adicione uma descrição e uma data de expiração.

3. Selecione Adicionar.

4. Copie o Valor do segredo que criou. Não poderá obter este valor depois de sair da página.

5. Na página de descrição geral da aplicação, copie o ID da Aplicação (cliente) e o ID do Diretório (inquilino). Precisa deste ID para autenticar a sua aplicação.

6. Anote o ID da aplicação e o ID do inquilino. Na página da aplicação, aceda a Descrição geral e copie o seguinte.

Aplicações multicliente

Os parceiros do Microsoft Defender para Endpoint têm de configurar as respetivas aplicações como multi-inquilino. Defina a sua aplicação como uma aplicação multi-inquilino se estiver a planear criar uma aplicação que será executada nos inquilinos de vários clientes.

1. Na página da sua aplicação do Azure, aceda a Gerir > Autenticação.

2. Adicionar uma plataforma.

3. No painel Configurar plataformas , selecione Web.

4. Adicione https://portal.azure.com aos URIs de Redirecionamento e selecione Configurar.

5. Nas opções Tipos de conta suportados , selecione Contas em qualquer diretório organizacional e selecione Guardar.

Depois de executar a sua aplicação, tem de a aprovar em cada inquilino onde pretende utilizá-la. Isto deve-se ao facto de a sua aplicação interagir com o Defender para Endpoint em nome do cliente. Você ou o seu cliente terão de selecionar a ligação de consentimento e aprovar a aplicação. Dê consentimento a um utilizador que tenha privilégios de administrador.

Eis como formar a ligação de consentimento. Quando um administrador de inquilinos visita esta URL, abre-se o fluxo de consentimento da plataforma de identidades da Microsoft para que o cliente possa autorizar a aplicação. Substitua 00000000-0000-0000-0000-000000000000 pelo ID da sua aplicação.

https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true

Obter um token de acesso

Os métodos seguintes mostram como obter o token de acesso da sua aplicação.

# This script acquires the App Context Token and stores it in the variable $token for later use.
# Paste your Tenant ID, App ID, and App Secret (App key) into the quotes below.

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

$sourceAppIdUri = 'https://api.securitycenter.microsoft.com/.default'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token"
$authBody = [Ordered] @{
    scope = "$sourceAppIdUri"
    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
$token

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