Compartir vía

Acceso a Microsoft Defender for Cloud Apps con el contexto de la aplicación

  • Artículo

En esta página se describe cómo crear una aplicación para obtener acceso mediante programación a Defender for Cloud Apps sin un usuario. Si necesitas acceso mediante programación a Defender for Cloud Apps en nombre de un usuario, consulta Obtener acceso con el contexto de usuario. Si no estás seguro de qué acceso necesitas, consulta la página Administración de tokens de API.

Microsoft Defender for Cloud Apps expone gran parte de tus datos y acciones a través de un conjunto de API mediante programación. Esas API te ayudarán a automatizar flujos de trabajo e innovar en función de las funcionalidades de Defender for Cloud Apps. El acceso a la API requiere autenticación de OAuth2.0. Para obtener más información, consulta Flujo de códigos de autorización OAuth 2.0.

En general, deberás realizar los pasos siguientes para usar las API:

  • Crear una aplicación de Microsoft Entra.
  • Obtén un token de acceso mediante esta aplicación.
  • Utiliza el token para acceder a la API de Defender for Cloud Apps.

En este artículo se explica cómo crear una aplicación de Microsoft Entra, obtener un token de acceso a Microsoft Defender for Cloud Apps y validar el token.

Creación de una aplicación

  1. Inicia sesión en Azure con un usuario que tenga el rol de Administrador global.

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

    Image of Microsoft Azure and navigation to application registration.

  3. En el formulario de registro, elige un nombre para la aplicación y, a continuación, selecciona Registrar.

  4. Para permitir que la aplicación acceda a Defender for Cloud Apps asignarle el permiso "Leer todas las alertas", en la página de la aplicación, selecciona Permisos de API>>Añadir permisos API que utiliza mi organización>, escribe Microsoft Cloud App Security y, a continuación, selecciona Microsoft Cloud App Security.

    Nota:

    Microsoft Cloud App Security no aparece en la lista original. Empieza a escribir tu nombre en el cuadro de texto para ver que aparece. Asegúrate de escribir este nombre, aunque el producto ahora se llame Defender for Cloud Apps.

    add permission.

    • Selecciona Investigación de permisos> de aplicación, y después elige Agregar permisos.

      app permission.

      Debes seleccionar los permisos pertinentes. Investigation.Read es solo un ejemplo. Para ver otros ámbitos de permisos, consulta Ámbitos de permisos admitidos

      • Para determinar qué permiso necesitas, consulta la sección Permisos de la API a la que te interesa llamar.

  5. Seleccione Conceder consentimiento de administrador.

    Nota:

    Cada vez que agregues un permiso, debes seleccionar Conceder consentimiento del administrador para que el nuevo permiso surta efecto.

    Grant permissions.

  6. Para agregar un secreto a la aplicación, seleccione Certificados y secretos, seleccione Nuevo secreto de cliente, agregue una descripción al secreto y, a continuación, seleccione Agregar.

    Nota:

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

    Image of create app key.

  7. Anota el identificador de aplicación y el identificador de inquilino. En la página de la aplicación, ve a Información general y copia el Id. de aplicación (cliente) y Id. de directorio (inquilino).

    Image of created app id.

  8. Solo para socios de Microsoft Defender for Cloud Apps. Establece la aplicación en multiinquilino (disponible en todos los inquilinos después del consentimiento). Esto es necesario para aplicaciones de terceros (por ejemplo, si creas una aplicación diseñada para ejecutarse en el inquilino de varios clientes). Esto no es necesario si creas un servicio que deseas ejecutar solo en el inquilino (por ejemplo, si creas una aplicación para tu propio uso que solo interactuará con tus propios datos). Para establecer que la aplicación sea multiinquilino:

    • Ve a Autenticación y agrega https://portal.azure.com como URI de redirección.

    • En la parte inferior de la página, en Tipos de cuenta admitidos, selecciona Cuentas en cualquier consentimiento de aplicación de directorio organizativo para la aplicación multiinquilino.

    Necesitas que la aplicación se apruebe en cada inquilino donde quieras usarla. Esto se debe a que la aplicación interactúa con Defender for Cloud Apps en nombre del cliente.

    Tú (o tu cliente si escribes una aplicación de terceros) debéis seleccionar el enlace de consentimiento y aprobar la aplicación. El consentimiento debe realizarse con un usuario que tenga privilegios administrativos en Active Directory.

    El enlace de consentimiento se crea de la siguiente manera:

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

    Donde 00000000-0000-0000-0000-000000000000 se reemplaza por el identificador de aplicación.

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

Ámbitos de permisos admitidos

Nombre de permiso Descripción Acciones admitidas
Investigation.read Realiza todas las acciones admitidas en actividades y alertas, excepto las alertas de cierre.
Visualiza los intervalos IP, pero no agrega, actualiza o elimina.

Realiza todas las acciones de entidades.		 Lista de actividades, captura, comentarios
Lista de alertas, captura, marcar como leído/no leído
Lista de entidades, captura, árbol de captura
Lista de subredes
Investigation.manage Realiza todas las acciones investigation.read además de administrar alertas e intervalos IP. Lista de actividades, captura, comentarios
Lista de alertas, captura, marcar como leído/no leído, cerrar
Lista de entidades, captura, árbol de captura
Lista de subredes, creación, actualización y eliminación
Discovery.read Realiza todas las acciones admitidas en actividades y alertas, excepto las alertas de cierre.
Enumera los informes y categorías de detección.		 Lista de alertas, captura, marcar como leído/no leído
Informes de lista de detección, categorías de informes de lista
Discovery.manage Permisos discovery.read
Cierra las alertas, carga los archivos de detección y genera scripts de bloqueo		 Lista de alertas, captura, marcar como leído/no leído, cerrar
Informes de lista de detección, categorías de informes de lista
Carga de archivos de detección, generación de script de bloque
Settings.read Lista de intervalos IP. Lista de subredes
Settings.manage Enumera y administra intervalos IP. Lista de subredes, creación, actualización y eliminación

Obtención de un token de acceso

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

Usar PowerShell

# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated quotes below.

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$resourceAppIdUri = '05a65629-4c1b-48c1-a78b-804c4abdd4af'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
    resource = "$resourceAppIdUri"
    client_id = "$appId"
    client_secret = "$appSecret"
    grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token

Uso de C#

El código siguiente se probó con NuGet Microsoft.Identity.Client 4.47.2.

  1. Cree una nueva aplicación de consola.

  2. Instalar NuGet Microsoft.Identity.Client.

  3. Agregue lo siguiente:

    using Microsoft.Identity.Client;

  4. Copia y pega el código siguiente en la aplicación (no olvides actualizar las tres variables: tenantId, appId, 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 = "05a65629-4c1b-48c1-a78b-804c4abdd4af";

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

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

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

string token = authResult.AccessToken;

Uso de Python

Consulta Biblioteca de autenticación de Microsoft (MSAL) para Python.

Uso de Curl

Nota:

En el procedimiento siguiente se supone que Curl para Windows ya está instalado en el equipo.

  1. Abre un símbolo del sistema y establece CLIENT_ID en el identificador de aplicación de Azure.
  2. Establece CLIENT_SECRET en el secreto de la aplicación de Azure.
  3. Establece TENANT_ID en el identificador de inquilino de Azure del cliente que quiere usar la aplicación para acceder a Defender for Cloud Apps.
  4. 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=05a65629-4c1b-48c1-a78b-804c4abdd4af/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k

Obtendrás una respuesta en el siguiente formato:

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

Validar el token

Asegúrate de que tienes el token correcto:

  1. Copia y pega el token obtenido en el paso anterior en JWT para descodificarlo.
  2. Comprueba que obtengas una notificación de "roles" con los permisos deseados
  3. En la imagen siguiente, puedes ver un token descodificado adquirido desde una aplicación con permisos para todos los roles de Microsoft Defender for Cloud Apps:

Image of token validation.

Uso del token para acceder a la API de Microsoft Defender for Cloud Apps

  1. Elige el campo que deseas usar. Para obtener más información, consulta APIs de Defender for Cloud Apps.
  2. Establece el encabezado de autorización en la solicitud http que envíes a "Bearer {token}" (Bearer es el esquema de autorización).
  3. El tiempo de expiración del token es de una hora. Puedes enviar más de una solicitud con el mismo token.

A continuación se muestra un ejemplo de envío de una solicitud para obtener una lista de alertas mediante C#:

    var httpClient = new HttpClient();

    var request = new HttpRequestMessage(HttpMethod.Get, "https://portal.cloudappsecurity.com/cas/api/v1/alerts/");

    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

    var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

    // Do something useful with the response

Consulte también