Criar um aplicativo para acessar o Microsoft Defender para Ponto de Extremidade sem um usuário

Ao usar Microsoft Defender para Ponto de Extremidade APIs, talvez seja necessário ter acesso a Microsoft Defender para Ponto de Extremidade sem um usuário. 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 você precisar de acesso a um serviço de segundo plano sem que haja um usuário conectado, crie um aplicativo que possa acessar o Defender for Endpoint sem um usuário.

Este artigo mostra como registrar um aplicativo no Microsoft Entra ID, conceder permissões somente de aplicativo e obter um token de acesso para acessar a API do Defender for Endpoint. O acesso à API requer o fluxo de credenciais do cliente OAuth 2.0.

Pré-requisitos

Para criar um registro de aplicativo no Azure, você precisa de uma função Microsoft Entra com permissões de registro de aplicativo que permita a criação do aplicativo, como o Administrador de Aplicativos.

Passo 1: criar uma aplicação no Azure

Execute as seguintes etapas para registrar um aplicativo e conceder a ele permissões de API no Azure:

1. Entre no portal do Azure.

2. Procure Registros de aplicativo e navegue para Registros de aplicativo.

3. Selecione Novo registro.

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

As etapas a seguir descrevem como autenticar seu aplicativo usando um segredo do aplicativo. 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.

Aplicativos multilocatários

Os parceiros do Microsoft Defender para Ponto de Extremidade precisam configurar seus aplicativos para serem multilocatários. 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 do seu aplicativo do Azure, acesse Gerenciar > 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 seu cliente precisará selecionar o link de consentimento e aprovar seu aplicativo. Dê consentimento a um utilizador que tenha privilégios de administrador.

Eis como formar a ligação de consentimento. Quando um administrador de locatário visita essa URL, o fluxo de consentimento do plataforma de identidade da Microsoft é aberto para que o locatário do cliente possa autorizar o aplicativo. Substitua 00000000-0000-0000-0000-000000000000 pelo ID do seu aplicativo.

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 a seguir mostram como obter o token de acesso do aplicativo.

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