Create una aplicación para acceder a Microsoft Defender para punto de conexión sin un usuario

Artículo
05/03/2024

Se aplica a:

Importante

Las funcionalidades avanzadas de búsqueda no se incluyen en Defender para empresas.

¿Quiere experimentar Microsoft Defender para punto de conexión? Regístrese para obtener una prueba gratuita.

Nota:

Si es cliente del Gobierno de EE. UU., use los URI que aparecen en Microsoft Defender para punto de conexión para los clientes del Gobierno de EE. UU.

Sugerencia

Para mejorar el rendimiento, puede usar el servidor más cercano a la ubicación 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

En esta página se describe cómo crear una aplicación para obtener acceso mediante programación a Defender for Endpoint sin un usuario. Si necesita acceso mediante programación a Defender para punto de conexión en nombre de un usuario, consulte Obtención de acceso con el contexto de usuario. Si no está seguro de qué acceso necesita, consulte Introducción.

Microsoft Defender para punto de conexión expone gran parte de sus datos y acciones a través de un conjunto de API mediante programación. Esas API le ayudarán a automatizar los flujos de trabajo e innovar en función de las funcionalidades de Defender para punto de conexión. El acceso a la API requiere la autenticación de OAuth2.0. Para obtener más información, vea Flujo de código de autorización de OAuth 2.0.

En general, deberá realizar los pasos siguientes para usar las API:

Create una aplicación Microsoft Entra.
Obtenga un token de acceso mediante esta aplicación.
Use el token para acceder a Defender for Endpoint API.

En este artículo se explica cómo crear una aplicación Microsoft Entra, obtener un token de acceso para Microsoft Defender para punto de conexión y validar el token.

Crear una aplicación

Inicie sesión en Azure con un usuario que tenga el rol De administrador global .
Vaya a Microsoft Entra ID>Registros de aplicaciones>Nuevo registro.
En el formulario de registro, elija un nombre para la aplicación y, a continuación, seleccione Registrar.
Para permitir que la aplicación acceda a Defender para punto de conexión y asígnele el permiso "Leer todas las alertas", en la página de la aplicación, seleccione Permisos> de API Agregar API depermisos>que usa> mi organización, escriba WindowsDefenderATP y, a continuación, seleccione WindowsDefenderATP.

Nota:

WindowsDefenderATP no aparece en la lista original. Empiece a escribir su nombre en el cuadro de texto para verlo aparecer.

Seleccione Permisos> de aplicaciónAlert.Read.All y, a continuación, seleccione Agregar permisos.

Debe seleccionar los permisos pertinentes. "Leer todas las alertas" es solo un ejemplo. Por ejemplo:
- Para ejecutar consultas avanzadas, seleccione el permiso "Ejecutar consultas avanzadas".
- Para aislar un dispositivo, seleccione el permiso "Aislar máquina".
- Para determinar qué permiso necesita, consulte la sección Permisos de la API a la que está interesado llamar.
Seleccione Conceder consentimiento.

Nota:

Cada vez que agregue un permiso, debe seleccionar Conceder consentimiento para que el nuevo permiso surta efecto.
Para agregar un secreto a la aplicación, seleccione Certificados & secretos, agregue una descripción al secreto y, a continuación, seleccione Agregar.

Nota:

Después de seleccionar Agregar, seleccione Copiar el valor de secreto generado. No podrá recuperar este valor después de salir.
Anote el identificador de la aplicación y el identificador de inquilino. En la página de la aplicación, vaya a Información general y copie lo siguiente.
Solo para asociados Microsoft Defender para punto de conexión. Establezca la aplicación en multiinquilino (disponible en todos los inquilinos después del consentimiento). Esto es necesario para aplicaciones de terceros (por ejemplo, si crea una aplicación destinada a ejecutarse en el inquilino de varios clientes). Esto no es necesario si crea un servicio que solo desea ejecutar en el inquilino (por ejemplo, si crea una aplicación para su propio uso que solo interactuará con sus propios datos). Para establecer que la aplicación sea multiinquilino:
- Vaya a Autenticación y agregue https://portal.azure.com como uri de redirección.
- En la parte inferior de la página, en Tipos de cuenta admitidos, seleccione el consentimiento de la aplicación Cuentas en cualquier directorio organizativo para la aplicación multiinquilino.
Necesita que la aplicación se apruebe en cada inquilino donde quiera usarla. Esto se debe a que la aplicación interactúa con Defender para punto de conexión en nombre del cliente.

Usted (o el cliente si está escribiendo una aplicación de terceros) debe seleccionar el vínculo de consentimiento y aprobar la aplicación. El consentimiento debe realizarse con un usuario que tenga privilegios administrativos en Active Directory.

El vínculo de consentimiento se forma de la siguiente manera:
```
https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
```
Donde 0000000000-0000-0000-0000-0000000000000 se reemplaza por el identificador de aplicación.

¡Listo! Ha registrado correctamente una aplicación. Consulte los ejemplos siguientes para la adquisición y validación de tokens.

Obtener un token de acceso

Para obtener más información sobre los tokens de Microsoft Entra, consulte el tutorial de Microsoft Entra.

Usar PowerShell

# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated 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

Use C#:

El código siguiente se ha probado con NuGet Microsoft.Identity.Client 3.19.8.

Importante

El paquete NuGet Microsoft.IdentityModel.Clients.ActiveDirectory y Autenticación de Azure AD Library (ADAL) han quedado en desuso. No se han agregado nuevas características desde el 30 de junio de 2020. Le recomendamos encarecidamente que actualice, consulte la guía de migración para obtener más detalles.

Create una nueva aplicación de consola.
Instale NuGet Microsoft.Identity.Client.
Agregue lo siguiente:
```
using Microsoft.Identity.Client;
```

Copie y pegue el código siguiente en la aplicación (no olvide actualizar las tres variables: tenantId, appId, 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;

Uso de Python

Consulte Obtención de token mediante Python.

Uso de Curl

Nota:

En el procedimiento siguiente se supone que Curl para Windows ya está instalado en el equipo.

Abra un símbolo del sistema y establezca CLIENT_ID en el identificador de aplicación de Azure.
Establezca CLIENT_SECRET en el secreto de aplicación de Azure.
Establezca TENANT_ID en el identificador de inquilino de Azure del cliente que quiere usar la aplicación para acceder a Defender para punto de conexión.

Ejecute el comando siguiente:

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

Obtendrá una respuesta con el siguiente formato:

{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}

Validar el token

Asegúrese de que tiene el token correcto:

Copie y pegue el token que obtuvo en el paso anterior en JWT para descodificarlo.
Valide que obtiene una notificación de "roles" con los permisos deseados.

En la imagen siguiente, puede ver un token descodificado adquirido de una aplicación con permisos para todos los roles de Microsoft Defender para punto de conexión:

Uso del token para acceder a Microsoft Defender para punto de conexión API

Elija la API que desea usar. Para obtener más información, vea Supported Defender for Endpoint API (Defender para API de punto de conexión admitido).
Establezca el encabezado de autorización en la solicitud http que envíe a "Bearer {token}" (Bearer es el esquema de autorización).
La hora de expiración del token es de una hora. Puede enviar más de una solicitud con el mismo token.

A continuación se muestra un ejemplo de envío de una solicitud para obtener una lista de alertas mediante 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

Consulte también