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

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 usar roles con los permisos más mínimos. Esto ayuda a mejorar la seguridad de su organización. Administrador global es un rol con privilegios elevados que debe limitarse a escenarios de emergencia cuando no se puede usar un rol existente.

Crear una aplicación

1. Inicie sesión en Azure Portal con un usuario que tenga el rol Administrador global.

2. Vaya aRegistros> de aplicaciones de Microsoft Entra ID>Nuevo registro.

   

3. En el formulario de registro, elija un nombre para la aplicación y, a continuación, seleccione Registrar.

4. 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.

   

5. 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.

6. Seleccione Conceder consentimiento.

   Nota:

   Cada vez que agregue un permiso, debe seleccionar Conceder consentimiento para que el nuevo permiso surta efecto.

   

7. 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.

   

8. 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.

   

9. 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:

   1. Vaya a Autenticación y agregue https://portal.azure.com como uri de redirección.

   2. 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.

1. Cree una nueva aplicación de consola.

2. Instale NuGet Microsoft.Identity.Client.

3. Agregue lo siguiente:

   using Microsoft.Identity.Client;
   

4. 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.

1. Abra un símbolo del sistema y establezca en CLIENT_ID el identificador de la aplicación de Azure.

2. Establezca en CLIENT_SECRET el secreto de aplicación de Azure.

3. 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.

4. 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:

1. Copie y pegue el token que obtuvo en el paso anterior en JWT para descodificarlo.

2. 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

1. 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).

2. Establezca el encabezado de autorización en la http solicitud que envíe a Bearer {token} (Bearer es el esquema de autorización).

3. 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.