Uso de api de Microsoft Defender para punto de conexión

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 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 en nombre de un usuario.

Si necesita acceso mediante programación Microsoft Defender para punto de conexión sin un usuario, consulte Acceso a Microsoft Defender para punto de conexión con el contexto de la aplicación.

Si no está seguro de qué acceso necesita, lea la página 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. Estas API le permitirán automatizar los flujos de trabajo e innovar en función de las capacidades de Microsoft 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
• Obtención de un token de acceso mediante esta aplicación
• Uso del token para acceder a Defender for Endpoint API

En esta página 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.

Nota:

Al acceder a Microsoft Defender para punto de conexión API en nombre de un usuario, necesitará el permiso de aplicación y el permiso de usuario correctos. Si no está familiarizado con los permisos de usuario en Microsoft Defender para punto de conexión, consulte Administración del acceso al portal mediante el control de acceso basado en rol.

Sugerencia

Si tiene permiso para realizar una acción en el portal, tiene el permiso para realizar la acción en la API.

Crear una aplicación

1. Inicie sesión en Azure con una cuenta de usuario que tenga el rol Administrador global .

2. Vaya a Microsoft Entra ID>Registros de aplicaciones>Nuevo registro.

   

3. Cuando aparezca la página Registrar una aplicación, escriba la información de registro de la aplicación:

   • Nombre: escriba un nombre significativo para la aplicación, que se mostrará a los usuarios de la aplicación.

   • Tipos de cuentas compatibles: seleccione qué cuentas desea que admita la aplicación.

     
     

     Tipos de cuenta admitidos	Descripción
     Solo las cuentas de este directorio organizativo	Seleccione esta opción si va a crear una aplicación de línea de negocio (LOB). Esta opción no está disponible si no va a registrar la aplicación en un directorio. Esta opción se asigna a Microsoft Entra solo inquilino único. Esta es la opción predeterminada a menos que registre la aplicación fuera de un directorio. En los casos en los que la aplicación está registrada fuera de un directorio, el valor predeterminado es Microsoft Entra cuentas de Microsoft personales y multiinquilino.
     Cuentas en cualquier directorio organizativo	Seleccione esta opción si desea tener como destino todos los clientes de negocios y del sector educativo. Esta opción se asigna a un multiinquilino de solo Microsoft Entra. Si registró la aplicación como solo Microsoft Entra inquilino único, puede actualizarla para que se Microsoft Entra multiinquilino y vuelva a un solo inquilino a través de la hoja Autenticación.
     Cuentas en cualquier directorio organizativo y cuentas personales de Microsoft	Seleccione esta opción para establecer como destino el mayor conjunto posible de clientes. Esta opción se asigna a Microsoft Entra cuentas de Microsoft multiinquilino y personales. Si registró la aplicación como Microsoft Entra cuentas de Microsoft multiinquilino y personales, no podrá cambiarla en la interfaz de usuario. En su lugar, debe usar el editor de manifiestos de aplicación para cambiar los tipos de cuenta admitidos.

   • URI de redirección (opcional): seleccione el tipo de aplicación que se va a crear, Web o Cliente público (móvil y escritorio) y, a continuación, escriba el identificador URI de redireccionamiento (o la dirección URL de respuesta) para la aplicación.

     • Para aplicaciones web, proporcione la dirección URL base de la aplicación. Por ejemplo, http://localhost:31544 podría ser la dirección URL de una aplicación web que se ejecuta en la máquina local. Los usuarios utilizan esta dirección URL para iniciar sesión en una aplicación cliente web.

     • Para las aplicaciones cliente públicas, proporcione el URI que usa Microsoft Entra ID para devolver respuestas de token. Escriba un valor específico para la aplicación, como myapp://auth.

     Si desea ejemplos específicos de aplicaciones web o aplicaciones nativas, visite nuestras guías de inicio rápido.

     Cuando termine, seleccione Registrar.

4. Permita que la aplicación acceda a Microsoft Defender para punto de conexión y asígnele el permiso "Leer alertas":

   • En la página de la aplicación, seleccione Permisos> de APIAgregar API de permisos>Que mi organización usa>, escriba WindowsDefenderATP y seleccione en WindowsDefenderATP.

     Nota:

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

     

   • Elija Permisos delegados>Alert.Read> seleccione Agregar permisos.

     

   Importante

   Seleccione los permisos pertinentes. Las alertas de lectura son solo un ejemplo.

   Por ejemplo:

   • Para ejecutar consultas avanzadas, seleccione El permiso Ejecutar consultas avanzadas .

   • Para aislar un dispositivo, seleccione Aislar permiso de 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 permiso, debe seleccionar en Conceder consentimiento para que el nuevo permiso surta efecto.

     

5. 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 la siguiente información:

   

Obtener un token de acceso

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

Uso de C#

• Copie o pegue la clase siguiente en la aplicación.

• Use el método AcquireUserTokenAsync con el identificador de aplicación, el identificador de inquilino, el nombre de usuario y la contraseña para adquirir un token.

  namespace WindowsDefenderATP
  {
      using System.Net.Http;
      using System.Text;
      using System.Threading.Tasks;
      using Newtonsoft.Json.Linq;
  
      public static class WindowsDefenderATPUtils
      {
          private const string Authority = "https://login.microsoftonline.com";
  
          private const string WdatpResourceId = "https://api.securitycenter.microsoft.com";
  
          public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
          {
              using (var httpClient = new HttpClient())
              {
                  var urlEncodedBody = $"resource={WdatpResourceId}&client_id={appId}&grant_type=password&username={username}&password={password}";
  
                  var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");
  
                  using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                  {
                      response.EnsureSuccessStatusCode();
  
                      var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
  
                      var jObject = JObject.Parse(json);
  
                      return jObject["access_token"].Value<string>();
                  }
              }
          }
      }
  }
  

Validar el token

Compruebe para asegurarse de que tiene un token correcto:

• Copie o pegue en JWT el token que obtuvo en el paso anterior para descodificarlo.

• Valide que obtiene una notificación "scp" con los permisos de aplicación deseados.

• En la captura de pantalla siguiente, puede ver un token descodificado adquirido de la aplicación en el tutorial:

  

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

• Elija la API que desea usar: API de Microsoft Defender para punto de conexión admitidas.

• Establezca el encabezado Authorization 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 1 hora (puede enviar más de una solicitud con el mismo token).

• 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

• API de Microsoft Defender para punto de conexión
• Acceso a Microsoft Defender para punto de conexión con contexto de aplicación

Sugerencia

¿Desea obtener más información? Engage con la comunidad de seguridad de Microsoft en nuestra comunidad tecnológica: Microsoft Defender para punto de conexión Tech Community.