Crear una aplicación con acceso de asociado a Microsoft 365 API de DefenderCreate an app with partner access to Microsoft 365 Defender APIs

Importante

El Centro de seguridad de Microsoft 365 mejorado está ahora disponible.The improved Microsoft 365 security center is now available. Esta nueva experiencia incluye Defender para punto de conexión, Defender para Office 365, Microsoft 365 Defender y más en el Centro de seguridad de Microsoft 365.This new experience brings Defender for Endpoint, Defender for Office 365, Microsoft 365 Defender, and more into the Microsoft 365 security center. Ver las novedades.Learn what's new.

Se aplica a:Applies to:

  • Microsoft 365 DefenderMicrosoft 365 Defender

Importante

Parte de la información se refiere a productos preliminares que pueden ser modificados sustancialmente antes de su lanzamiento comercial.Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft no otorga garantías, expresas o implícitas, con respecto a la información que aquí se proporciona.Microsoft makes no warranties, express or implied, with respect to the information provided here.

En esta página se describe cómo crear una aplicación Azure Active Directory que tenga acceso mediante programación a Microsoft 365 Defender, en nombre de los usuarios de varios inquilinos.This page describes how to create an Azure Active Directory app that has programmatic access to Microsoft 365 Defender, on behalf of users across multiple tenants. Las aplicaciones multiinquilino son útiles para atender a grandes grupos de usuarios.Multi-tenant apps are useful for serving large groups of users.

Si necesitas acceso mediante programación a Microsoft 365 Defender en nombre de un único usuario, consulta Crear una aplicación para obtener acceso a las API de Microsoft 365 Defender en nombre de un usuario.If you need programmatic access to Microsoft 365 Defender on behalf of a single user, see Create an app to access Microsoft 365 Defender APIs on behalf of a user. Si necesitas acceso sin un usuario definido explícitamente (por ejemplo, si estás escribiendo una aplicación en segundo plano o un demonio), consulta Crear una aplicación para tener acceso a Microsoft 365 Defender sin un usuario.If you need access without a user explicitly defined (for example, if you're writing a background app or daemon), see Create an app to access Microsoft 365 Defender without a user. Si no está seguro del tipo de acceso que necesita, vea Introducción.If you're not sure which kind of access you need, see Get started.

Microsoft 365 Defender expone gran parte de sus datos y acciones a través de un conjunto de API programáticas.Microsoft 365 Defender exposes much of its data and actions through a set of programmatic APIs. Estas API te ayudan a automatizar flujos de trabajo y a usar las capacidades de Microsoft 365 Defender.Those APIs help you automate workflows and make use of Microsoft 365 Defender's capabilities. Este acceso a la API requiere autenticación de OAuth2.0.This API access requires OAuth2.0 authentication. Para obtener más información, vea Código de autorización de OAuth 2.0 Flow.For more information, see OAuth 2.0 Authorization Code Flow.

En general, deberá seguir los siguientes pasos para usar estas API:In general, you'll need to take the following steps to use these APIs:

  • Crear una aplicación Azure Active Directory (Azure AD).Create an Azure Active Directory (Azure AD) application.
  • Obtener un token de acceso con esta aplicación.Get an access token using this application.
  • Use el token para obtener acceso a Microsoft 365 API de Defender.Use the token to access Microsoft 365 Defender API.

Dado que esta aplicación es multiinquilino, también necesitarás el consentimiento de administrador de cada inquilino en nombre de sus usuarios.Since this app is multi-tenant, you'll also need admin consent from each tenant on behalf of its users.

En este artículo se explica cómo:This article explains how to:

  • Crear una aplicación de Azure AD multiinquilinoCreate a multi-tenant Azure AD application
  • Obtenga el consentimiento autorizado del administrador de usuarios para que la aplicación obtenga acceso al Microsoft 365 Defender que necesita.Get authorized consent from your user administrator for your application to access the Microsoft 365 Defender that resources it needs.
  • Obtener un token de acceso a Microsoft 365 DefenderGet an access token to Microsoft 365 Defender
  • Validar el tokenValidate the token

Microsoft 365 Defender expone gran parte de sus datos y acciones a través de un conjunto de API programáticas.Microsoft 365 Defender exposes much of its data and actions through a set of programmatic APIs. Estas API le ayudarán a automatizar los flujos de trabajo e innovar en función de las Microsoft 365 Defender.Those APIs will help you automate work flows and innovate based on Microsoft 365 Defender capabilities. El acceso a la API requiere autenticación de OAuth2.0.The API access requires OAuth2.0 authentication. Para obtener más información, vea Código de autorización de OAuth 2.0 Flow.For more information, see OAuth 2.0 Authorization Code Flow.

En general, deberá seguir los pasos siguientes para usar las API:In general, you’ll need to take the following steps to use the APIs:

  • Crear una aplicación de Azure AD multiinquilino.Create a multi-tenant Azure AD application.
  • Obtenga autorización (consentimiento) del administrador de usuario para que la aplicación obtenga acceso a Microsoft 365 recursos de Defender que necesita.Get authorized (consent) by your user administrator for your application to access Microsoft 365 Defender resources it needs.
  • Obtener un token de acceso con esta aplicación.Get an access token using this application.
  • Use el token para obtener acceso a Microsoft 365 API de Defender.Use the token to access Microsoft 365 Defender API.

Los siguientes pasos le guían sobre cómo crear una aplicación multiinquilino de Azure AD, obtener un token de acceso a Microsoft 365 Defender y validar el token.The following steps with guide you how to create a multi-tenant Azure AD application, get an access token to Microsoft 365 Defender and validate the token.

Crear la aplicación multiinquilinoCreate the multi-tenant app

  1. Inicie sesión en Azure como usuario con el rol Administrador global.Sign in to Azure as a user with the Global Administrator role.

  2. Vaya a Azure Active Directory > registros de aplicaciones Nuevo > registro.Navigate to Azure Active Directory > App registrations > New registration.

    Imagen de Microsoft Azure navegación al registro de aplicaciones

  3. En el formulario de registro:In the registration form:

    • Elija un nombre para la aplicación.Choose a name for your application.
    • En Tipos de cuentas compatibles, seleccione Cuentas en cualquier directorio de la organización (cualquier directorio de Azure AD) - Multitenant.From Supported account types, select Accounts in any organizational directory (Any Azure AD directory) - Multitenant.
    • Rellene la sección URI de redireccionamiento.Fill out the Redirect URI section. Seleccione el tipo Web y dé al URI de redireccionamiento como https://portal.azure.com .Select type Web and give the redirect URI as https://portal.azure.com.

    Una vez que haya terminado de rellenar el formulario, seleccione Registrar.After you're done filling out the form, select Register.

    Imagen del formulario Registrar una aplicación

  4. En la página de la aplicación, seleccione Permisos de API Agregar API de permisos que mi organización usa > > >, escriba Protección contra amenazas de Microsoft y seleccione Protección contra amenazas de Microsoft.On your application page, select API Permissions > Add permission > APIs my organization uses >, type Microsoft Threat Protection, and select Microsoft Threat Protection. La aplicación ahora puede acceder a Microsoft 365 Defender.Your app can now access Microsoft 365 Defender.

    Sugerencia

    Protección contra amenazas de Microsoft es un nombre antiguo de Microsoft 365 Defender y no aparecerá en la lista original.Microsoft Threat Protection is a former name for Microsoft 365 Defender, and will not appear in the original list. Debe empezar a escribir su nombre en el cuadro de texto para verlo aparecer.You need to start writing its name in the text box to see it appear.

    Imagen de selección de permisos de API

  5. Seleccione Permisos de aplicación.Select Application permissions. Elija los permisos relevantes para su escenario (por ejemplo, Incident.Read.All) y, a continuación, seleccione Agregar permisos.Choose the relevant permissions for your scenario (for example, Incident.Read.All), and then select Add permissions.

    Imagen de acceso a api y selección de API

    Nota

    Debe seleccionar los permisos relevantes para su escenario.You need to select the relevant permissions for your scenario. Leer todos los incidentes es solo un ejemplo.Read all incidents is just an example. Para determinar qué permiso necesita, consulte la sección Permisos de la API a la que desea llamar.To determine which permission you need, please look at the Permissions section in the API you want to call.

    Por ejemplo, para ejecutar consultas avanzadas,seleccione el permiso "Ejecutar consultas avanzadas"; para aislar un dispositivo,seleccione el permiso "Aislar máquina".For instance, to run advanced queries, select the 'Run advanced queries' permission; to isolate a device, select the 'Isolate machine' permission.

  6. Seleccione Conceder consentimiento de administrador.Select Grant admin consent. Cada vez que agregue un permiso, debe seleccionar Conceder consentimiento de administrador para que su efecto.Every time you add a permission, you must select Grant admin consent for it to take effect.

    Imagen de concesión de permisos

  7. Para agregar un secreto a la aplicación, seleccione Certificados & secretos, agregue una descripción al secreto y, a continuación, seleccione Agregar.To add a secret to the application, select Certificates & secrets, add a description to the secret, then select Add.

    Sugerencia

    Después de seleccionar Agregar, seleccione copiar el valor secreto generado.After you select Add, select copy the generated secret value. No podrá recuperar el valor secreto después de salir.You won't be able to retrieve the secret value after you leave.

    Imagen de crear clave de aplicación

  8. Registre el identificador de la aplicación y el identificador de inquilino en un lugar seguro.Record your application ID and your tenant ID somewhere safe. Aparecen en Información general en la página de la aplicación.They're listed under Overview on your application page.

    Imagen del identificador de aplicación creado

  9. Agregue la aplicación al inquilino del usuario.Add the application to your user's tenant.

    Dado que la aplicación interactúa con Microsoft 365 Defender en nombre de los usuarios, debe aprobarse para todos los inquilinos en los que desea usarlo.Since your application interacts with Microsoft 365 Defender on behalf of your users, it needs be approved for every tenant on which you intend to use it.

    Un administrador global del inquilino del usuario debe ver el vínculo de consentimiento y aprobar la aplicación.A Global Administrator from your user's tenant needs to view the consent link and approve your application.

    El vínculo de consentimiento es del formulario:Consent link is of the form:

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

    Los 00000000-0000-0000-0000-000000000000 dígitos deben reemplazarse por su id. de aplicación.The digits 00000000-0000-0000-0000-000000000000 should be replaced with your Application ID.

    Después de hacer clic en el vínculo de consentimiento, inicie sesión con el administrador global del inquilino del usuario y consiente la aplicación.After clicking on the consent link, sign in with the Global Administrator of the user's tenant and consent the application.

    Imagen de consentimiento

    También tendrás que pedir al usuario su identificador de inquilino.You'll also need to ask your user for their tenant ID. El identificador de inquilino es uno de los identificadores usados para adquirir tokens de acceso.The tenant ID is one of the identifiers used to acquire access tokens.

  • ¡Listo!Done! Ha registrado correctamente una aplicación.You've successfully registered an application!
  • Vea ejemplos a continuación para la adquisición y validación de tokens.See examples below for token acquisition and validation.

Obtener un token de accesoGet an access token

Para obtener más información sobre los tokens de Azure AD, consulte el tutorial de Azure AD.For more information on Azure AD tokens, see the Azure AD tutorial.

Importante

Aunque los ejemplos de esta sección le animan a pegar valores secretos con fines de prueba, nunca debe codificar los secretos en una aplicación que se ejecute en producción.Although the examples in this section encourage you to paste in secret values for testing purposes, you should never hardcode secrets into an application running in production. Un tercero podría usar el secreto para obtener acceso a los recursos.A third party could use your secret to access resources. Puedes ayudar a proteger los secretos de la aplicación con Azure Key Vault.You can help keep your app's secrets secure by using Azure Key Vault. Para obtener un ejemplo práctico de cómo proteger la aplicación, consulta Administrar secretos en las aplicaciones de servidor con Azure Key Vault.For a practical example of how you can protect your app, see Manage secrets in your server apps with Azure Key Vault.

Sugerencia

En los ejemplos siguientes, use el identificador de inquilino de un usuario para probar que el script funciona.In the following examples, use a user's tenant ID to test that the script is working.

Obtener un token de acceso con PowerShellGet an access token using 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

Obtener un token de acceso con C#Get an access token using C#

Nota

El código siguiente se ha probado con Nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8.The following code was tested with Nuget Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8.

  1. Crear una nueva aplicación de consola.Create a new console application.

  2. Instale NuGet Microsoft.IdentityModel.Clients.ActiveDirectory.Install NuGet Microsoft.IdentityModel.Clients.ActiveDirectory.

  3. Agregue la siguiente línea:Add the following line:

    using Microsoft.IdentityModel.Clients.ActiveDirectory;
    
  4. Copie y pegue el siguiente código en la aplicación (no olvide actualizar las tres variables: tenantId , clientId , appSecret ):Copy and paste the following code into your app (don't forget to update the three variables: tenantId, clientId, appSecret):

    string tenantId = ""; // Paste your directory (tenant) ID here
    string clientId = ""; // Paste your application (client) ID here
    string appSecret = ""; // Paste your own app secret here to test, then store it in a safe place, such as the Azure Key Vault!
    
    const string authority = "https://login.windows.net";
    const string wdatpResourceId = "https://api.security.microsoft.com";
    
    AuthenticationContext auth = new AuthenticationContext($"{authority}/{tenantId}/");
    ClientCredential clientCredential = new ClientCredential(clientId, appSecret);
    AuthenticationResult authenticationResult = auth.AcquireTokenAsync(wdatpResourceId, clientCredential).GetAwaiter().GetResult();
    string token = authenticationResult.AccessToken;
    

Obtener un token de acceso con PythonGet an access token using 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.securitycenter.windows.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"]

Obtener un token de acceso con el rizoGet an access token using curl

Nota

El rizo está preinstalado en Windows 10 versiones 1803 y posteriores.Curl is pre-installed on Windows 10, versions 1803 and later. Para otras versiones de Windows, descargue e instale la herramienta directamente desde el sitio web oficial de curl.For other versions of Windows, download and install the tool directly from the official curl website.

  1. Abra un símbolo del sistema y establezca CLIENT_ID en el identificador de la aplicación de Azure.Open a command prompt, and set CLIENT_ID to your Azure application ID.
  2. Establece CLIENT_SECRET en el secreto de la aplicación de Azure.Set CLIENT_SECRET to your Azure application secret.
  3. Establece TENANT_ID el identificador de inquilino de Azure del usuario que desea usar la aplicación para acceder a Microsoft 365 Defender.Set TENANT_ID to the Azure tenant ID of the user that wants to use your app to access Microsoft 365 Defender.
  4. Ejecute el siguiente comando:Run the following command:
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á este aspecto:A successful response will look like this:

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

Validar el tokenValidate the token

  1. Copie y pegue el token en el sitio web del validador de tokens web JSON, JWT, para descodificarlo.Copy and paste the token into the JSON web token validator website, JWT, to decode it.
  2. Asegúrese de que la notificación de roles dentro del token descodificado contiene los permisos deseados.Make sure that the roles claim within the decoded token contains the desired permissions.

En la siguiente imagen, puedes ver un token descodificado adquirido desde una aplicación, con Incidents.Read.All , Incidents.ReadWrite.All y AdvancedHunting.Read.All permisos:In the following image, you can see a decoded token acquired from an app, with Incidents.Read.All, Incidents.ReadWrite.All, and AdvancedHunting.Read.All permissions:

Imagen de validación de tokens

Usar el token para obtener acceso a la API Microsoft 365 DefenderUse the token to access the Microsoft 365 Defender API

  1. Elige la API que quieras usar (incidentes o búsqueda avanzada).Choose the API you want to use (incidents, or advanced hunting). Para obtener más información, vea Supported Microsoft 365 Defender API.For more information, see Supported Microsoft 365 Defender APIs.
  2. En la solicitud http que está a punto de enviar, establezca el encabezado de autorización en , Bearer es el esquema de autorización "Bearer" <token> y el token es el token validado. In the http request you're about to send, set the authorization header to "Bearer" <token>, Bearer being the authorization scheme, and token being your validated token.
  3. El token expirará en una hora.The token will expire within one hour. Puede enviar más de una solicitud durante este tiempo con el mismo token.You can send more than one request during this time with the same token.

En el ejemplo siguiente se muestra cómo enviar una solicitud para obtener una lista de incidentes mediante C#.The following example shows how to send a request to get a list of incidents using 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();