Create una aplicación con acceso de asociado a las API de Microsoft Defender XDR

  • 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 Microsoft Entra que tenga acceso mediante programación a Microsoft Defender XDR, en nombre de los usuarios de varios inquilinos. Las aplicaciones multiinquilino son útiles para atender a grandes grupos de usuarios.

Si necesita acceso mediante programación a Microsoft Defender XDR en nombre de un único usuario, consulte Create una aplicación para acceder a Microsoft Defender XDR API en nombre de un usuario. Si necesita acceso sin un usuario definido explícitamente (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 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.

Dado que esta aplicación es multiinquilino, también necesitará el consentimiento del administrador de cada inquilino en nombre de sus usuarios.

En este artículo se explica cómo:

  • Create una aplicación de Microsoft Entra multiinquilino
  • Obtenga el consentimiento autorizado del administrador de usuarios para que la aplicación acceda a la Microsoft Defender XDR que necesita.
  • Obtención de un token de acceso para Microsoft Defender XDR
  • Validar el token

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 ayudarán a automatizar los flujos de trabajo e innovar en función de las capacidades Microsoft Defender XDR. 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 de Microsoft Entra multiinquilino.
  • Obtenga autorización (consentimiento) por parte del administrador de usuarios para que la aplicación acceda a Microsoft Defender XDR recursos que necesita.
  • Obtenga un token de acceso mediante esta aplicación.
  • Use el token para acceder a Microsoft Defender XDR API.

En los pasos siguientes se explica cómo crear una aplicación de Microsoft Entra multiinquilino, obtener un token de acceso para Microsoft Defender XDR y validar el token.

Create la aplicación multiinquilino

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

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

    Sección de registro de una aplicación en el portal de Microsoft Defender

  3. En el formulario de registro:

    • Elija un nombre para la aplicación.
    • En Tipos de cuenta admitidos, seleccione Cuentas en cualquier directorio organizativo (cualquier directorio Microsoft Entra): multiinquilino.
    • Rellene la sección URI de redirección . Seleccione El tipo Web y asigne el URI de redireccionamiento como https://portal.azure.com.

    Una vez que haya terminado de rellenar el formulario, seleccione Registrar.

    Secciones de registro de una aplicación en el portal de Microsoft Defender

  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.

    Sección uso de API en el portal de Microsoft Defender

  5. Seleccione Permisos de aplicación. Elija los permisos pertinentes para el escenario (por ejemplo, Incident.Read.All) y, a continuación, seleccione Agregar permisos.

    Panel de permisos de una aplicación 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".

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

    Sección para conceder el consentimiento del administrador en el portal de Microsoft Defender

  7. Para agregar un secreto a la aplicación, seleccione Certificados & secretos, agregue una descripción al secreto y, a continuación, seleccione Agregar.

    Sugerencia

    Después de seleccionar Agregar, seleccione Copiar el valor de secreto generado. No podrá recuperar el valor del secreto después de salir.

    La sección Adición de secretos en el portal de Microsoft Defender

  8. 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

  9. Agregue la aplicación al inquilino del usuario.

    Dado que la aplicación interactúa con Microsoft Defender XDR en nombre de los usuarios, debe aprobarse para cada inquilino en el que quiera usarlo.

    Un administrador global del inquilino del usuario debe ver el vínculo de consentimiento y aprobar la aplicación.

    El vínculo de consentimiento tiene el siguiente formato:

    https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true

    Los dígitos 00000000-0000-0000-0000-000000000000 se deben reemplazar por el identificador de aplicación.

    Después de hacer clic en el vínculo de consentimiento, inicie sesión con el administrador global del inquilino del usuario y dé su consentimiento a la aplicación.

    Página de la aplicación de consentimiento en el portal de Microsoft Defender

    También tendrá que pedir al usuario su identificador de inquilino. El identificador de inquilino es uno de los identificadores que se usan para adquirir tokens de acceso.

  • ¡Listo! Ha registrado correctamente una aplicación.
  • Consulte los ejemplos siguientes para la adquisición y validación de tokens.

Obtener un token de acceso

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

Importante

Aunque los ejemplos de esta sección le animan a pegar valores secretos con fines de prueba, nunca debe codificar de forma rígida los secretos en una aplicación que se ejecuta en producción. Un tercero podría usar el secreto para acceder a los recursos. Puede ayudar a proteger los secretos de la aplicación mediante Azure Key Vault. Para obtener un ejemplo práctico de cómo proteger la aplicación, consulte Administración de secretos en las aplicaciones de servidor con Azure Key Vault.

Sugerencia

En los ejemplos siguientes, use el identificador de inquilino de un usuario para probar que el script funciona.

Obtención de un token de acceso mediante PowerShell

# This code gets the application context token and saves it to a file named "Latest-token.txt" under the current directory.

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # Paste your own app secret here to test, then store it in a safe place!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"

$authBody = [Ordered] @{
    resource = $resourceAppIdUri
    client_id = $clientId
    client_secret = $appSecret
    grant_type = 'client_credentials'
}

$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token

Out-File -FilePath "./Latest-token.txt" -InputObject $token

return $token

Obtención de un token de acceso mediante C#

Nota:

El código siguiente se ha probado con Nuget Microsoft.Identity.Client 3.19.8.

Importante

El paquete NuGet Microsoft.IdentityModel.Clients.ActiveDirectory y Autenticación de Azure AD Library (ADAL) han quedado en desuso. No se han agregado nuevas características desde el 30 de junio de 2020. Le recomendamos encarecidamente que actualice, consulte la guía de migración para obtener más detalles.

  1. Create una nueva aplicación de consola.

  2. Instale NuGet Microsoft.Identity.Client.

  3. Agregue la línea siguiente:

    using Microsoft.Identity.Client;

  4. Copie y pegue el código siguiente en la aplicación (no olvide actualizar las tres variables: tenantId, clientId, appSecret):

    string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place! 
const string authority = https://login.microsoftonline.com;
const string audience = https://api.securitycenter.microsoft.com;

IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();

List<string> scopes = new List<string>() { $"{audience}/.default" };

AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();

string token = authResult.AccessToken;

Obtención de un token de acceso mediante Python

import json
import urllib.request
import urllib.parse

tenantId = '' # Paste your directory (tenant) ID here
clientId = '' # Paste your application (client) ID here
appSecret = '' # Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!

url = "https://login.windows.net/%s/oauth2/token" % (tenantId)

resourceAppIdUri = 'https://api.security.microsoft.com'

body = {
    'resource' : resourceAppIdUri,
    'client_id' : clientId,
    'client_secret' : appSecret,
    'grant_type' : 'client_credentials'
}

data = urllib.parse.urlencode(body).encode("utf-8")

req = urllib.request.Request(url, data)
response = urllib.request.urlopen(req)
jsonResponse = json.loads(response.read())
aadToken = jsonResponse["access_token"]

Obtención de un token de acceso mediante curl

Nota:

Curl está preinstalado en Windows 10, versiones 1803 y posteriores. Para otras versiones de Windows, descargue e instale la herramienta directamente desde el sitio web oficial de curl.

  1. Abra un símbolo del sistema y establezca CLIENT_ID en el identificador de aplicación de Azure.
  2. Establezca CLIENT_SECRET en el secreto de aplicación de Azure.
  3. Establezca TENANT_ID en el identificador de inquilino de Azure del usuario que quiere usar la aplicación para acceder a Microsoft Defender XDR.
  4. Ejecute el comando siguiente:
curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=https://securitycenter.onmicrosoft.com/windowsatpservice/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k

Una respuesta correcta tendrá el siguiente aspecto:

{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}

Validar el token

  1. Copie y pegue el token en el sitio web de validador de token web JSON, 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 :

Panel Token descodificado en el 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? Engage con la comunidad de seguridad de Microsoft en nuestra comunidad tecnológica: Microsoft Defender XDR Tech Community.