Crear una aplicación para obtener acceso a Microsoft 365 API de Defender en nombre de un usuarioCreate an app to access Microsoft 365 Defender APIs on behalf of a user

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 para obtener acceso mediante programación a Microsoft 365 Defender en nombre de un único usuario.This page describes how to create an application to get programmatic access to Microsoft 365 Defender on behalf of a single user.

Si necesitas acceso mediante programación a Microsoft 365 Defender sin un usuario definido (por ejemplo, si estás escribiendo una aplicación o demonio en segundo plano), consulta Crear una aplicación para tener acceso a Microsoft 365 Defendersin un usuario .If you need programmatic access to Microsoft 365 Defender without a defined user (for example, if you're writing a background app or daemon), see Create an app to access Microsoft 365 Defender without a user. Si necesitas proporcionar acceso a varios inquilinos (por ejemplo, si estás prestando servicio a una organización grande o a un grupo de clientes), consulta Crear una aplicación con acceso de asociado a las API de Microsoft 365 Defender. Si no está seguro del tipo de acceso que necesita, vea Introducción.If you need to provide access for multiple tenants—for example, if you're serving a large organization or a group of customers—see Create an app with partner access to Microsoft 365 Defender APIs.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.

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

  • Crear una aplicación Azure ADCreate an Azure AD application
  • Obtener un token de acceso a Microsoft 365 DefenderGet an access token to Microsoft 365 Defender
  • Validar el tokenValidate the token

Nota

Al acceder Microsoft 365 API de Defender en nombre de un usuario, necesitará los permisos de aplicación y de usuario correctos.When accessing Microsoft 365 Defender API on behalf of a user, you will need the correct application permissions and user permissions.

Sugerencia

Si tiene permiso para realizar una acción en el portal, tiene permiso para realizar la acción en la API.If you have the permission to perform an action in the portal, you have the permission to perform the action in the API.

Crear una aplicaciónCreate an 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, elija un nombre para la aplicación y escriba la siguiente información para el URI de redireccionamiento y, a continuación, seleccione Registrar.In the form, choose a name for your application and enter the following information for the redirect URI, then select Register.

    Imagen de la ventana Crear 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

    • Elija Permisos delegados.Choose Delegated permissions. Elija los permisos relevantes para su escenario (por ejemplo, Incident.Read) y, a continuación, seleccione Agregar permisos.Choose the relevant permissions for your scenario (for example Incident.Read), 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.

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

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

Obtener un token de accesoGet an access token

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

Obtener un token de acceso con PowerShellGet an access token using PowerShell

if(!(Get-Package adal.ps)) { Install-Package -Name adal.ps } # Install the ADAL.PS package in case it's not already present

$tenantId = '' # Paste your directory (tenant) ID here.
$clientId = '' # Paste your application (client) ID here.
$redirectUri = '' # Paste your app's redirection URI

$authority = "https://login.windows.net/$tenantId"
$resourceUrl = 'https://api.security.microsoft.com'

$response = Get-ADALToken -Resource $resourceUrl -ClientId $cleintId -RedirectUri $redirectUri -Authority $authority -PromptBehavior:Always
$response.AccessToken | clip

$response.AccessToken

Validar el tokenValidate the token

  1. Copie y pegue el token en JWT para descodificarlo.Copy and paste the token into 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();