Acesso de parceiro através das APIs do Microsoft Defender para Endpoint
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 Us Government, utilize os URIs listados no Microsoft Defender para Endpoint 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 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:
Crie uma aplicação Microsoft Entra multi-inquilino.
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.
Obtenha um token de acesso com esta aplicação.
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 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
Inicie sessão no seu inquilino do Azure com o utilizador que tem a função de Administrador Global .
Navegue paraRegistos> da Aplicação Microsoft Entra ID>Novo registo.
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
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 :
Selecione Alerta de permissões> daaplicação.Read.Todos> selecione adicionar permissões
Selecione Conceder consentimento
- Sempre que adicionar permissão, tem de selecionar Conceder consentimento para que a nova permissão entre em vigor.
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!
Anote o ID da aplicação:
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.
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 o token do Microsoft Entra, consulte o tutorial do Microsoft Entra.
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 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.
Crie uma nova Aplicação de Consola.
Instale o NuGet Microsoft.Identity.Client.
Adicione o seguinte através de código:
using Microsoft.Identity.Client;
Este código foi testado com NuGet
Microsoft.Identity.Client
.Copie/Cole o seguinte código na sua aplicação (não se esqueça de atualizar as três variáveis:
tenantId
,appId
eappSecret
).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
Abra uma janela de comando.
Defina
CLIENT_ID
como o ID da aplicação do Azure.Defina
CLIENT_SECRET
como o segredo da sua aplicação do Azure.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.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.
Copie/cole no JWT o token que obtém no passo anterior para o descodificar.
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
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).
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 ao Microsoft Defender para Endpoint em nome de um utilizador
Dica
Você deseja aprender mais? Contacte a comunidade de Segurança da Microsoft na nossa Comunidade Tecnológica: Microsoft Defender para Endpoint Tech Community.