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

Nota

¿Quiere experimentar Microsoft 365 Defender? Obtenga más información sobre cómo puede evaluar y probar Microsoft 365 Defender.

Se aplica a:

  • Microsoft 365 Defender

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 365 Defender en nombre de un único usuario.

Si necesita acceso mediante programación a Microsoft 365 Defender 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 365 Defender 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 365 Defender API. Si no está seguro del tipo de acceso que necesita, consulte Introducción.

Microsoft 365 Defender 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 365 Defender. 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 Azure Active Directory (Azure AD).
  • Obtenga un token de acceso mediante esta aplicación.
  • Use el token para acceder a Microsoft 365 Defender API.

En este artículo se explica cómo:

  • Crear una aplicación Azure AD
  • Obtención de un token de acceso para Microsoft 365 Defender
  • Validar el token

Nota

Al acceder a Microsoft 365 Defender 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 Azure Active Directory > 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 de permisos > Que mi organización usa >, escriba Microsoft Threat Protection y seleccione Microsoft Threat Protection. La aplicación ahora puede acceder a Microsoft 365 Defender.

    Sugerencia

    Microsoft Threat Protection es un nombre anterior para Microsoft 365 Defender 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 365 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 365 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 365 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 365 Defender

Obtener un token de acceso

Para obtener más información sobre los tokens de Azure Active Directory, consulte el tutorial de Azure AD.

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'
}

$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 365 Defender

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

  1. Elija la API que desea usar (incidentes o búsqueda avanzada). Para obtener más información, consulte API de Microsoft 365 Defender 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();