Creación de una aplicación para acceder a Microsoft Defender para punto de conexión sin un usuario
Se aplica a:
- Microsoft Defender para punto de conexión Plan 1
- Microsoft Defender para punto de conexión Plan 2
- Microsoft Defender para Empresas
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 un cliente del Gobierno de EE. UU., use los URI que aparecen en Microsoft Defender para punto de conexión para 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
- ina.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 de 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:
- Cree 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 a Microsoft Defender para punto de conexión y validar el token.
Importante
Microsoft recomienda utilizar roles con la menor cantidad de permisos. Esto ayuda a mejorar la seguridad de la organización. Administrador global es un rol con muchos privilegios que debe limitarse a escenarios de emergencia cuando no se puede usar un rol existente.
Crear una aplicación
Inicie sesión en Azure Portal con un usuario que tenga el rol Administrador global.
Vaya aRegistros> de aplicaciones de Microsoft Entra ID>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.
Seleccione los permisos adecuados.
Read All Alerts
es solo un ejemplo. Estos son algunos ejemplos:- Para ejecutar consultas avanzadas, seleccione el
Run advanced queries
permiso . - Para aislar un dispositivo, seleccione el
Isolate machine
permiso . - Para determinar qué permiso necesita, consulte la sección Permisos de la API a la que está interesado llamar.
- Para ejecutar consultas avanzadas, seleccione el
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 de 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, siga estos pasos:
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
00000000-0000-0000-0000-000000000000
se reemplaza por el identificador de la 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 la Biblioteca de autenticación de Azure AD (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.
Cree 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 en
CLIENT_ID
el identificador de la aplicación de Azure.Establezca en
CLIENT_SECRET
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 siguiente 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
Obtiene una respuesta similar al siguiente fragmento de código:
{"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 La API de Microsoft Defender para punto de conexión
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
http
solicitud que envíe aBearer {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
Vea también
- API compatibles de Microsoft Defender para punto de conexión
- Acceso a Microsoft Defender para punto de conexión en nombre de un usuario
Sugerencia
¿Desea obtener más información? Interactúe con la comunidad de seguridad de Microsoft en nuestra comunidad tecnológica: Microsoft Defender para punto de conexión Tech Community.
Comentarios
https://aka.ms/ContentUserFeedback.
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea:Enviar y ver comentarios de