Compartir a través de

Creación de una aplicación para acceder a Microsoft Defender XDR API en nombre de un usuario

  • Artículo

Se aplica a:

  • Microsoft Defender XDR

Importante

Parte de la información se refiere a productos preliminares que pueden ser modificados sustancialmente antes de su lanzamiento comercial. Microsoft no otorga garantías, expresas o implícitas, con respecto a la información que aquí se proporciona.

En esta página se describe cómo crear una aplicación para obtener acceso mediante programación a Microsoft Defender XDR en nombre de un único usuario.

Si necesita acceso mediante programación a Microsoft Defender XDR sin un usuario definido (por ejemplo, si está escribiendo una aplicación en segundo plano o un demonio), consulte Creación de una aplicación para acceder a Microsoft Defender XDR sin un usuario. Si necesita proporcionar acceso para varios inquilinos(por ejemplo, si está atendiendo a una organización grande o a un grupo de clientes), consulte Creación de una aplicación con acceso de asociado a Microsoft Defender XDR API. Si no está seguro del tipo de acceso que necesita, consulte Introducción.

Microsoft Defender XDR expone gran parte de sus datos y acciones a través de un conjunto de API mediante programación. Esas API le ayudan a automatizar flujos de trabajo y a usar las funcionalidades de Microsoft Defender XDR. Este 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 estas API:

  • Cree una aplicación de Microsoft Entra.
  • Obtenga un token de acceso mediante esta aplicación.
  • Use el token para acceder a Microsoft Defender XDR API.

En este artículo se explica cómo:

  • Creación de una aplicación Microsoft Entra
  • Obtención de un token de acceso para Microsoft Defender XDR
  • Validar el token

Nota:

Al acceder a Microsoft Defender XDR API en nombre de un usuario, necesitará los permisos de aplicación y permisos de usuario correctos.

Sugerencia

Si tiene permiso para realizar una acción en el portal, tiene el permiso para realizar la acción en la API. Para obtener más información sobre los roles y permisos, consulte Administración del acceso a Microsoft Defender XDR con Microsoft Entra roles globales.

Crear una aplicación

  1. Inicie sesión en Azure.

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

    La opción Nuevo registro del panel Administrar de la Azure Portal

  3. En el formulario, elija un nombre para la aplicación y escriba la siguiente información para el URI de redirección y, a continuación, seleccione Registrar.

    Panel de registro de la aplicación en el Azure Portal

  4. En la página de la aplicación, seleccione Permisos> de API Agregar API depermisos>que usa> mi organización, escriba Microsoft Threat Protection y seleccione Microsoft Threat Protection. La aplicación ahora puede acceder a Microsoft Defender XDR.

    Sugerencia

    Microsoft Threat Protection es un nombre anterior para Microsoft Defender XDR y no aparecerá en la lista original. Debe empezar a escribir su nombre en el cuadro de texto para verlo aparecer.

    Panel API de la organización en el portal de Microsoft Defender

    • Elija Permisos delegados. Elija los permisos pertinentes para el escenario (por ejemplo , Incident.Read) y, a continuación, seleccione Agregar permisos.

      Panel Permisos delegados en el portal de Microsoft Defender

    Nota:

    Debe seleccionar los permisos pertinentes para el escenario. Leer todos los incidentes es solo un ejemplo. Para determinar qué permiso necesita, consulte la sección Permisos de la API a la que desea llamar.

    Por ejemplo, para ejecutar consultas avanzadas, seleccione el permiso "Ejecutar consultas avanzadas"; Para aislar un dispositivo, seleccione el permiso "Aislar máquina".

  5. Seleccione Conceder consentimiento de administrador. Cada vez que agregue un permiso, debe seleccionar Conceder consentimiento del administrador para que surta efecto.

    Panel de concesión de consentimiento del administrador en el portal de Microsoft Defender

  6. Registre el identificador de la aplicación y el identificador de inquilino en un lugar seguro. Se enumeran en Información general en la página de la aplicación.

    Panel Información general del portal de Microsoft Defender

Obtener un token de acceso

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

Obtención de un token de acceso en nombre de un usuario mediante PowerShell

Use la biblioteca MSAL.PS para adquirir tokens de acceso con permisos delegados. Ejecute los siguientes comandos para obtener el token de acceso en nombre de un usuario:

Install-Module -Name MSAL.PS # Install the MSAL.PS module from PowerShell Gallery

$TenantId = " " # Paste your directory (tenant) ID here.
$AppClientId="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Paste your application (client) ID here.

$MsalParams = @{
   ClientId = $AppClientId
   TenantId = $TenantId
   Scopes   = 'https://graph.microsoft.com/User.Read.All','https://graph.microsoft.com/Files.ReadWrite','https://api.securitycenter.windows.com/AdvancedQuery.Read'
}

$MsalResponse = Get-MsalToken @MsalParams
$AccessToken  = $MsalResponse.AccessToken
 
$AccessToken # Display the token in PS console

Validar el token

  1. Copie y pegue el token en JWT para descodificarlo.
  2. Asegúrese de que la notificación de roles dentro del token descodificado contiene los permisos deseados.

En la imagen siguiente, puede ver un token descodificado adquirido de una aplicación, con Incidents.Read.Allpermisos , Incidents.ReadWrite.Ally AdvancedHunting.Read.All :

La sección de permisos del panel Token descodificado del portal de Microsoft Defender

Uso del token para acceder a la API de Microsoft Defender XDR

  1. Elija la API que desea usar (incidentes o búsqueda avanzada). Para obtener más información, consulte API de Microsoft Defender XDR compatibles.
  2. En la solicitud HTTP que va a enviar, establezca el encabezado "Bearer" <token>de autorización en , Bearer es el esquema de autorización y el token es el token validado.
  3. El token expirará en una hora. Puede enviar más de una solicitud durante este tiempo con el mismo token.

En el ejemplo siguiente se muestra cómo enviar una solicitud para obtener una lista de incidentes mediante C#.

    var httpClient = new HttpClient();
    var request = new HttpRequestMessage(HttpMethod.Get, "https://api.security.microsoft.com/api/incidents");

    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

    var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

Sugerencia

¿Desea obtener más información? Participe con la comunidad de Seguridad de Microsoft en nuestra Tech Community: Tech Community de Microsoft Defender XDR.