Compartir a través de

Acceso a Microsoft Defender for Cloud Apps API con contexto de usuario

  • 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 en nombre de un usuario.

Si necesita acceso mediante programación Microsoft Defender for Cloud Apps sin un usuario, consulte Access Microsoft Defender for Cloud Apps with application context (Acceso a Microsoft Defender for Cloud Apps con contexto de aplicación).

Si no está seguro de qué acceso necesita, lea la página Introducción.

Microsoft Defender for Cloud Apps expone gran parte de sus datos y acciones a través de un conjunto de API mediante programación. Estas API le permiten automatizar flujos de trabajo e innovar en función de Microsoft Defender for Cloud Apps capacidades. 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, debe realizar los pasos siguientes para usar las API:

  • Creación de una aplicación Microsoft Entra
  • Obtención de un token de acceso mediante esta aplicación
  • Uso del token para acceder a Defender for Cloud Apps API

En esta página se explica cómo crear una aplicación Microsoft Entra, obtener un token de acceso para Microsoft Defender for Cloud Apps y validar el token.

Nota:

Al acceder a Microsoft Defender for Cloud Apps API en nombre de un usuario, necesitará el permiso de aplicación y el permiso de usuario correctos. Si no está familiarizado con los permisos de usuario en Microsoft Defender for Cloud Apps, consulte Administración del acceso de administrador.

Sugerencia

Si tiene permiso para realizar una acción en el portal, tiene el permiso para realizar la acción en la API.

Crear una aplicación

  1. En el Centro de administración Microsoft Entra, registre una nueva aplicación. Para obtener más información, consulte Inicio rápido: Registro de una aplicación con el Centro de administración Microsoft Entra.

  2. Cuando aparezca la página Registrar una aplicación, escriba la información de registro de la aplicación:

    • Nombre : escriba un nombre de aplicación significativo que se muestre a los usuarios de la aplicación.

    • Tipos de cuentas compatibles: seleccione qué cuentas desea que admita la aplicación.

      Tipos de cuenta admitidos Descripción
      Solo las cuentas de este directorio organizativo Seleccione esta opción si va a crear una aplicación de línea de negocio (LOB). Esta opción no está disponible si no está registrando la aplicación en un directorio.

      Esta opción se asigna a Microsoft Entra solo inquilino único.

      Esta es la opción predeterminada a menos que registre la aplicación fuera de un directorio. En los casos en los que la aplicación está registrada fuera de un directorio, el valor predeterminado es Microsoft Entra cuentas de Microsoft multiinquilino y personales.
      Cuentas en cualquier directorio organizativo Seleccione esta opción si desea tener como destino todos los clientes de negocios y del sector educativo.

      Esta opción se asigna a un multiinquilino solo Microsoft Entra.

      Si registró la aplicación como solo Microsoft Entra inquilino único, puede actualizarla para que sea Microsoft Entra multiinquilino y volver a un solo inquilino a través del panel Autenticación.
      Cuentas en cualquier directorio organizativo y cuentas personales de Microsoft Seleccione esta opción para establecer como destino el mayor conjunto posible de clientes.

      Esta opción se asigna a Microsoft Entra cuentas de Microsoft multiinquilino y personales.

      Si registró la aplicación como Microsoft Entra cuentas de Microsoft multiinquilino y personales, no puede cambiarla en la interfaz de usuario. En su lugar, debe usar el editor de manifiestos de aplicación para cambiar los tipos de cuenta admitidos.

    • URI de redireccionamiento (opcional): seleccione el tipo de aplicación que va a compilar, **Web o Cliente público (escritorio de & móvil) y, a continuación, escriba el URI de redireccionamiento (o dirección URL de respuesta) de la aplicación.

      • Para aplicaciones web, proporcione la dirección URL base de la aplicación. Por ejemplo, http://localhost:31544 podría ser la dirección URL de una aplicación web que se ejecuta en la máquina local. Los usuarios utilizan esta dirección URL para iniciar sesión en una aplicación cliente web.
      • Para las aplicaciones cliente públicas, proporcione el URI que usa Microsoft Entra ID para devolver respuestas de token. Escriba un valor específico para la aplicación, como myapp://auth.

      Si desea ejemplos específicos de aplicaciones web o aplicaciones nativas, visite nuestras guías de inicio rápido.

      Cuando termine, seleccione Registrar.

  3. Permita que la aplicación acceda a Microsoft Defender for Cloud Apps y asígnele el permiso "Leer alertas":

    • En la página de la aplicación, seleccione Permisos> de APIAgregar API de permisos>. Mi organización usa> el tipo Microsoft Cloud App Security y, a continuación, seleccione Microsoft Cloud App Security.

    • Nota: Microsoft Cloud App Security no aparece en la lista original. Empiece a escribir su nombre en el cuadro de texto para verlo aparecer. Asegúrese de escribir este nombre, aunque el producto se llame ahora Defender for Cloud Apps.

      Captura de pantalla de la adición de permisos.

    • Elija Permisos> delegadosInvestigation.Read> seleccione Agregar permisos.

      Captura de pantalla de la adición de permisos de aplicación.

    • Nota importante: Seleccione los permisos pertinentes. Investigation.Read es solo un ejemplo. Para ver otros ámbitos de permisos, consulte Ámbitos de permisos admitidos.

      • Para determinar qué permiso necesita, consulte la sección Permisos de la API a la que le interesa llamar.

    • Seleccione Conceder consentimiento del administrador

      Nota: Cada vez que agregue permiso, debe seleccionar Conceder consentimiento del administrador para que el nuevo permiso surta efecto.

      Captura de pantalla de la concesión de permisos de administrador.

  4. Anote el identificador de aplicación y el identificador de inquilino:

    • En la página de la aplicación, vaya a Información general y copie la siguiente información:

      Captura de pantalla del identificador de aplicación creado.

Ámbitos de permisos admitidos

Nombre del permiso Descripción Acciones admitidas
Investigation.read Realice todas las acciones admitidas en las actividades y alertas excepto las alertas de cierre.
Vea los intervalos IP, pero no agregue, actualice ni elimine.

Realice todas las acciones de entidades.		 Lista de actividades, captura y comentarios
Lista de alertas, capturar, marcar como leído o no leído
Lista de entidades, capturar, capturar árbol
Lista de subredes
Investigation.manage Realice todas las acciones de investigation.read además de administrar alertas e intervalos IP. Lista de actividades, captura y comentarios
Lista de alertas, capturar, marcar como leído/no leído, cerrar
Lista de entidades, capturar, capturar árbol
Lista de subredes, crear, actualizar o eliminar
Discovery.read Realice todas las acciones admitidas en las actividades y alertas excepto las alertas de cierre.
Enumera los informes y categorías de detección.		 Lista de alertas, capturar, marcar como leído o no leído
Informes de lista de detección, categorías de informes de lista
Discovery.manage Permisos discovery.read
Cerrar alertas, cargar archivos de detección y generar scripts de bloque		 Lista de alertas, capturar, 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 Enumerar intervalos IP. Lista de subredes
Settings.manage Enumeración y administración de intervalos IP. Lista de subredes, crear, actualizar o eliminar

Obtener un token de acceso

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

Uso de C#

  • Copie o pegue la siguiente clase en la aplicación.
  • Use el método AcquireUserTokenAsync con el identificador de aplicación, el identificador de inquilino y la autenticación para adquirir un token.

Nota:

Aunque en el ejemplo de código siguiente se muestra cómo adquirir un token mediante el flujo de nombre de usuario y contraseña, Microsoft recomienda usar flujos de autenticación más seguros en un entorno de producción.

namespace MDA
{
    using System.Net.Http;
    using System.Text;
    using System.Threading.Tasks;
    using Newtonsoft.Json.Linq;

    public static class MDAUtils
    {
        private const string Authority = "https://login.microsoftonline.com";

        private const string MDAId = "05a65629-4c1b-48c1-a78b-804c4abdd4af";
        private const string Scope = "Investigation.read";

        public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
        {
            using (var httpClient = new HttpClient())
            {
                var urlEncodedBody = $"scope={MDAId}/{Scope}&client_id={appId}&grant_type=password&username={username}&password={password}";

                var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded");

                using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false))
                {
                    response.EnsureSuccessStatusCode();

                    var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);

                    var jObject = JObject.Parse(json);

                    return jObject["access_token"].Value<string>();
                }
            }
        }
    }
}

Validar el token

Compruebe para asegurarse de que tiene un token correcto:

  • Copie y pegue en JWT el token que obtuvo en el paso anterior para descodificarlo.

  • Valide que obtiene una notificación "scp" con los permisos de aplicación deseados.

  • En la captura de pantalla siguiente, puede ver un token descodificado adquirido de la aplicación en el tutorial:

    Captura de pantalla de la validación de tokens.

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

  • Elija la API que desea usar. Para obtener más información, consulte Defender for Cloud Apps API.

  • Establezca el encabezado Authorization en la solicitud HTTP que envíe a "Bearer {token}" (Bearer es el esquema de autorización)

  • La hora de expiración del token es de 1 hora (puede enviar más de una solicitud con el mismo token)

  • 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

Recursos adicionales