Creación de una aplicación con acceso de asociado a las API de Microsoft Defender XDR
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 Creación de 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 Creación de 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:
- 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.
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:
- Creación de 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:
- Cree 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.
Inicie sesión en Azure.
Vaya a Microsoft Entra ID>Registros de aplicaciones>Nuevo registro.
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.
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.
Seleccione Permisos de aplicación. Elija los permisos pertinentes para el escenario (por ejemplo, Incident.Read.All) 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".
Seleccione Conceder consentimiento de administrador. Cada vez que agregue un permiso, debe seleccionar Conceder consentimiento del administrador para que surta efecto.
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.
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.
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 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 como administrador del inquilino del usuario y conceda el consentimiento para la aplicación.
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.
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.
# 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
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.
Cree una nueva aplicación de consola.
Instale NuGet Microsoft.Identity.Client.
Agregue la línea siguiente:
using Microsoft.Identity.Client;
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;
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"]
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.
- Abra un símbolo del sistema y establezca CLIENT_ID en el identificador de aplicación de Azure.
- Establezca CLIENT_SECRET en el secreto de aplicación de Azure.
- Establezca TENANT_ID en el identificador de inquilino de Azure del usuario que quiere usar la aplicación para acceder a Microsoft Defender XDR.
- Ejecute el siguiente comando:
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"}
- Copie y pegue el token en el sitio web de validador de token web JSON, JWT, para descodificarlo.
- 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.All
permisos , Incidents.ReadWrite.All
y AdvancedHunting.Read.All
:
- Elija la API que desea usar (incidentes o búsqueda avanzada). Para obtener más información, consulte API de Microsoft Defender XDR compatibles.
- 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. - 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();
- Introducción a las API de Microsoft Defender XDR
- Acceso a las API de Microsoft Defender XDR
- Creación de una aplicación "Hello mundo"
- Creación de una aplicación para acceder a Microsoft Defender XDR sin un usuario
- Creación de una aplicación para acceder a Microsoft Defender XDR API en nombre de un usuario
- Más información sobre los límites de API y las licencias
- Descripción de los códigos de error
- Administración de secretos en las aplicaciones de servidor con Azure Key Vault
- 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? Participe con la comunidad de Seguridad de Microsoft en nuestra Tech Community: Tech Community de Microsoft Defender XDR.