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

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 Create 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 Create 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:

• Create una aplicación 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:

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

Crear una aplicación

1. Inicie sesión en Azure como usuario con el rol Administrador global .

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

   

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.

   

   • Tipo de aplicación: Cliente público
   • URI de redireccionamiento:https://portal.azure.com

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.

   

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

     

   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.

   

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.

   

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 :

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();

Artículos relacionados

• Introducción a las API de Microsoft Defender XDR
• Acceso a las API de Microsoft Defender XDR
• Create una aplicación "Hello mundo"
• Create una aplicación para acceder a Microsoft Defender XDR sin un usuario
• Create una aplicación con acceso de asociado multiinquilino a las API de Microsoft Defender XDR
• Más información sobre los límites de API y las licencias
• Descripción de los códigos de error
• Autorización de OAuth 2.0 para el inicio de sesión de usuario y el acceso a la API

Sugerencia

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