Compartir vía

Uso de las API de Microsoft Defender para punto de conexión

  • Artículo

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

Si necesita acceso mediante programación a Microsoft Defender para punto de conexión sin un usuario, consulte Acceso a Microsoft Defender para punto de conexión con contexto de 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 de programación. Esas API le permiten automatizar flujos de trabajo e innovar en función de las funcionalidades 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, debe realizar los pasos siguientes para usar las API:

  • Creación de 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 a Microsoft Defender para punto de conexión y validar el token.

Nota:

Al acceder a la API de Microsoft Defender para punto de conexión 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 el portal de Azure.

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

    Página Registros de aplicaciones en Microsoft Azure Portal

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

    • Nombre : escriba un nombre de aplicación significativo que se muestre 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 está registrando la aplicación en un directorio.

      Esta opción se asigna a Un solo inquilino de Microsoft Entra.

      Esta opción 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 multiinquilino y cuentas personales de Microsoft.
      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 solo de Microsoft Entra.

      Si registró la aplicación como un solo inquilino de Microsoft Entra, puede actualizarla para que sea multiinquilino de Microsoft Entra y volver 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 cuentas microsoft multiinquilino y personales de Microsoft Entra.

      Si registró la aplicación como cuentas microsoft multiinquilino y personales de Microsoft, no puede 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.

      • En el caso de 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.

      agregar permiso.

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

      El tipo de aplicación y los paneles de 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 le interesa llamar.

    • Seleccione Conceder consentimiento.

      Nota:

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

      Opción de consentimiento del gran administrador

  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:

    Identificador de la aplicación creada

Obtener un token de acceso

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

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:

    Página de validación de tokens

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

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

  • 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

Vea también

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.