Autorización y API de seguridad de Microsoft Graph

  • Artículo

Los datos de seguridad accesibles a través del API para seguridad de Microsoft Graph son confidenciales y están protegidos por permisos y roles de Microsoft Entra.

La API de seguridad de Microsoft Graph admite dos tipos de autorización:

  • Autorización de nivel de aplicación: No hay ningún usuario que haya iniciado sesión (por ejemplo, un escenario SIEM). Los permisos otorgados a la aplicación determinan la autorización.

    Nota:

    Esta opción también puede admitir casos en los que la aplicación administra el Control de acceso basado en roles (RBAC).

  • Autorización delegada por el usuario: Un usuario que es miembro del inquilino de Microsoft Entra ha iniciado sesión. El usuario debe ser miembro de un rol de Administración Microsoft Entra ID Limited (lector de seguridad o administrador de seguridad), además de que la aplicación tenga concedidos los permisos necesarios.

Si realiza una llamada a la API de seguridad de Microsoft Graph desde Probador de Graph:

  • El administrador de inquilinos de Microsoft Entra debe conceder explícitamente el consentimiento para los permisos solicitados a la aplicación Graph Explorer.

  • El usuario debe ser miembro del rol de Administración lector de seguridad limitado en Microsoft Entra ID (lector de seguridad o administrador de seguridad).

    Nota:

    El probador de Graph no admite la autorización de nivel de aplicación.

Si realiza una llamada a la API de seguridad de Microsoft Graph desde una aplicación propia o personalizada:

  • El administrador de inquilinos de Microsoft Entra debe conceder explícitamente el consentimiento a la aplicación. Esto es necesario tanto para las autorizaciones a nivel de aplicación y delegadas por usuarios.
  • Si usa la autorización delegada por el usuario, el usuario debe ser miembro del rol De lectura de seguridad o Administrador de seguridad limitado Administración en Microsoft Entra ID.

Administrar la autorización en las aplicaciones cliente con API de seguridad

Los datos de seguridad proporcionados a través de la API de seguridad de Microsoft Graph son confidenciales y deben estar protegidos por los mecanismos de autorización y autenticación adecuados. La siguiente tabla indica los pasos para registrarse y crear una aplicación cliente que puede acceder a la API de seguridad de Microsoft Graph.

Quién Acción
Propietario o desarrollador de la aplicación Registra la aplicación como una aplicación de empresa.
Administrador de un espacio empresarial Le concede permisos a la aplicación.
Administrador de un espacio empresarial Asigna roles a los usuarios.
Desarrollador de la aplicación Inicia sesión como usuario y usa la aplicación para acceder a la API de seguridad de Microsoft Graph.

El registro de la aplicación solo define qué permisos necesita la aplicación para poder ejecutarse. NO le concede los permisos a la aplicación.

El administrador de inquilinos Microsoft Entra DEBE conceder explícitamente los permisos a la aplicación. Esto debe realizarse por espacio empresarial cada vez que se modifican los permisos de aplicación en el portal de registro correspondiente.

Por ejemplo, suponga que tiene una aplicación, dos Microsoft Entra inquilinos, T1 y T2, y dos permisos, P1 y P2. A continuación, se muestra el proceso de autorización:

  • La aplicación se registra para exigir el permiso P1.

  • Cuando los usuarios del inquilino T1 obtienen un token de Microsoft Entra para esta aplicación, el token no contiene ningún permiso.

  • El administrador Microsoft Entra del inquilino T1 concede explícitamente permisos a la aplicación. Cuando los usuarios del inquilino T1 obtienen un token de Microsoft Entra para la aplicación, contendrá el permiso P1.

  • Cuando los usuarios del inquilino T2 obtienen un token de Microsoft Entra para la aplicación, el token no contiene ningún permiso porque el administrador del inquilino T2 aún no ha concedido permisos a la aplicación. Los permisos deben otorgarse por espacio empresarial y por aplicación.

  • El registro de la aplicación cambia para que ahora se requieran permisos P1 y P2.

  • Cuando los usuarios del inquilino T1 obtienen un token de Microsoft Entra para la aplicación, solo contiene el permiso P1. Los permisos concedidos a una aplicación se registran como instantáneos de lo que se concedió; no cambian automáticamente después de que cambie el registro de la aplicación (permiso).

  • El administrador del espacio empresarial E2 le concede permisos P1 y P2 a la aplicación. Ahora, cuando los usuarios del inquilino T2 obtienen un token de Microsoft Entra para la aplicación, el token contendrá los permisos P1 y P2.

    Nota:

    Los tokens de Microsoft Entra para la aplicación en el inquilino T1 y la aplicación en el inquilino T2 contienen permisos diferentes, ya que cada administrador de inquilinos ha concedido permisos diferentes a la aplicación.

  • Para que la aplicación vuelva a funcionar en el espacio empresarial E1, el administrador del espacio E1 debe concederle los permisos P1 y P2 de forma explícita a la aplicación.

Registro de una aplicación con el punto de conexión de la plataforma de identidad de Microsoft para desarrolladores

Para registrar una aplicación con el punto de conexión de plataforma de identidad de Microsoft para desarrolladores, necesitará:

  • Nombre de la aplicación: Cadena usada para el nombre de la aplicación.
  • Dirección URL de redireccionamiento: Dirección URL a la que se envía la respuesta de autenticación de Microsoft Entra ID. Para comenzar, puede usar la página principal de prueba de la aplicación web del cliente.
  • Permisos necesarios: Los permisos que requiere la aplicación para poder llamar a Microsoft Graph.

Para registrar su aplicación, haga lo siguiente:

  1. Vaya al portal de registro de aplicaciones de Azure e inicie sesión.

    Nota:

    No es necesario ser administrador de inquilinos. Se le redirigirá a la lista Mis aplicaciones.

  2. Seleccione Nuevo registro.

  3. En la página de registro de la nueva aplicación, escriba un valor para nombre y seleccione los tipos de cuenta que desea usar. En el campo Dirección URL de redireccionamiento, escriba la URL correspondiente.

  4. Seleccione Registrar para crear la aplicación y ver su página de información general. *

  5. Vaya a la página Permisos de API.

  6. Seleccione Agregar un permiso y, a continuación, elija Microsoft Graph en el control flotante. Seleccione Permisos delegados Use el cuadro de búsqueda para buscar y seleccionar los permisos necesarios. Para obtener una lista de permisos, consulte Permisos de seguridad.

    Nota:

    Nota: La API de Microsoft Graph Security requiere el ámbito SecurityEvents.Read.All para las consultas GET y el ámbito SecurityEvents.ReadWrite.All para las consultas PATCH, POST y DELETE.

    Permiso Entidad Solicitudes admitidas
    SecurityActions.Read.All • securityActions (versión preliminar) GET
    SecurityActions.ReadWrite.All • securityActions (versión preliminar) GET, POST
    SecurityEvents.Read.All • alertas
    • secureScores
    • secureScoreControlProfiles    		 GET
    SecurityEvents.ReadWrite.All • alertas
    • secureScores
    • secureScoreControlProfiles    		 GET, POST, PATCH
    ThreatIndicators.ReadWrite.OwnedBy • tiIndicator (versión preliminar) GET, POST, PATCH, DELETE

  7. Elija Agregar permisos.

Guarde la siguiente información:

  • Identificador de aplicación (cliente)
  • Dirección URL de redireccionamiento
  • Lita de permisos necesarios

*Windows Defender Advanced Threat Protection (WDATP) requiere roles de usuario adicionales que los que requiere Microsoft Graph API para seguridad; por lo tanto, solo los usuarios de los roles de API para seguridad de WDATP y Microsoft Graph pueden tener acceso a los datos de WDATP. Esto no limita la autenticación solo de la aplicación, por lo que le recomendamos que use un token de autenticación solo de la aplicación.

Para más información, vea Registrar la aplicación con la plataforma de identidad de Microsoft.

Conceda permisos a la aplicación.

El registro de la aplicación solo define qué permiso requiere la aplicación; no concede estos permisos a la aplicación. Un administrador de inquilinos Microsoft Entra debe conceder explícitamente estos permisos mediante una llamada al punto de conexión de consentimiento del administrador. Para obtener más información, consulte Usar el punto de conexión de consentimiento de administrador.

Para conceder permisos a una aplicación, necesitará lo siguiente:

  • Id. de aplicación: El identificador de aplicación del portal de registro de aplicaciones de Azure.
  • URL de redireccionamiento: Cadena que se establece en el portal de registro de aplicaciones de Azure para la respuesta de autenticación.

Para conceder los permisos:

  • En un editor de texto, cree la siguiente cadena de dirección URL:

    https://login.microsoftonline.com/common/adminconsent?client_id=<Application Id>&state=12345&redirect_uri=<Redirect URL>

  • En un navegador web, vaya a esta dirección URL e inicie sesión como administrador del espacio empresarial. El cuadro de diálogo muestra la lista de permisos que necesita la aplicación, como se indica en el portal de registro de la aplicación. Elija Aceptar para conceder estos permisos a la aplicación.

    Nota:

    Este paso concede permisos a la aplicación, no a los usuarios. Esto significa que a todos los usuarios que pertenecen al inquilino de Microsoft Entra que usan esta aplicación se les concederán estos permisos, incluso a los usuarios que no sean administradores.

Asignación de roles Microsoft Entra a los usuarios

Una vez que se conceden permisos a una aplicación, todos los usuarios con acceso a la aplicación (es decir, los miembros del inquilino de Microsoft Entra) reciben los permisos concedidos. Para proteger aún más los datos de seguridad confidenciales, Microsoft Graph API para seguridad también requiere que se asigne a los usuarios el rol lector de seguridad Microsoft Entra ID. Para obtener más información, consulte Permisos de rol de administrador en Microsoft Entra ID y Asignación de roles de administrador y no administrador a usuarios con Microsoft Entra ID.

Nota:

Debe ser administrador de inquilinos para realizar este paso.

Para asignar un rol a un usuario:

  1. Inicie sesión en el Centro de administración Microsoft Entra.
  2. Expanda el menú >Identidad y seleccione Todos>los usuarios.
  3. Seleccione el usuario.
  4. Elija Roles asignados y, después, Agregar tarea.
  5. SeleccioneLector de seguridad y haga clic en Agregar.

Crear un código de autenticación

Para crear un código de autenticación, necesitará lo siguiente:

  • Id. de aplicación: El identificador de aplicación del portal de registro de aplicaciones.
  • Dirección URL de redireccionamiento: Dirección URL a la que se envía la respuesta de autenticación de Microsoft Entra ID. Para comenzar, puede usar https://localhost o la página principal de prueba de la aplicación web del cliente.
  • Clave de aplicación (opcional): La clave de la aplicación. Esto se aplica al desarrollar una aplicación que usará el código de autenticación solo de la aplicación (es decir, que no admitirá la autenticación delegada por el usuario).

En la siguiente tabla se indican los recursos que puede usar para crear un código de autenticación.

Tipo de aplicación Biblioteca de autenticación
Aplicaciones de escritorio - iOS MSAL.framework: Biblioteca de autenticación de Microsoft (versión preliminar para iOS)
Aplicaciones de escritorio - Android Biblioteca de autenticación de Microsoft (MSAL)
Aplicaciones de escritorio - .Net Biblioteca de autenticación de Microsoft (MSAL)
Aplicaciones web - JavaScript SPA Biblioteca de autenticación de Microsoft para JavaScript (versión preliminar)
Aplicaciones web - Servidor web de .NET OpenIdConnection, Cookies, SystemWeb
Aplicaciones web - aplicaciones web NodeJS

En el caso de las aplicaciones que no utilizan ninguna de las bibliotecas existentes, consulte Obtener acceso en nombre de un usuario.

  1. Obtenga un código de Microsoft Entra ID. La consulta a la llamada contiene el parámetro de Id. de aplicación, Dirección URL de redirección y los permisos necesarios.
  2. Use el código para obtener un token de acceso.

Si usa la biblioteca OpenId Connect, vea Autenticar mediante Microsoft Entra ID y OpenID Connect y llamar a app.UseOpenIdConnectAuthentication().

Nota:

Si solicita tokens de autenticación delegados por el usuario, el parámetro de la biblioteca es Ámbitos solicitados. Use "User.Read" para este parámetro en lugar de lo que requiere la aplicación registrada. El parámetro Ámbitos solicitados NO afecta a los permisos que contienen los tokens de autenticación que se muestran. Estos dependen de los permisos que el administrador del espacio empresarial concede a la aplicación.

Por ejemplo, si usa la biblioteca de .NET MSAL, realice una llamada a lo siguiente:

var accessToken = (await client.AcquireTokenAsync(scopes)).AccessToken;

Nota:

En este ejemplo se debe usar el permiso con privilegios mínimos, como User.Read. Sin embargo, el token de acceso que se muestre puede contener los permisos concedidos por el administrador del espacio empresarial para el espacio empresarial del usuario actual, como "User.Read.All" o "User.ReadWrite.All".

Microsoft Entra ID devuelve un token (cadena) que contiene la información de autenticación y los permisos requeridos por la aplicación. Asigne este token al encabezado HTTP como un token portador, tal como se muestra en el siguiente ejemplo.

request.Headers.Authorization = new AuthenticationHeaderValue("bearer", accessToken);

Microsoft Graph validará la información que contenga este token y concederá o rechazará el acceso.

Para ver notificaciones incluidas en el token que se muestre, use la biblioteca "System.IdentityModel.Tokens.Jwt" de NuGet.

JwtSecurityTokenHandler tokenHandler = new JwtSecurityTokenHandler();
var securityToken = tokenHandler.ReadToken(accessToken) as JwtSecurityToken;

La respuesta de Microsoft Graph contiene un encabezado llamado "client-request-id", que es un GUID. Si se rechaza el acceso, especifique este GUID cuando obtenga asistencia técnica en Microsoft Tech Community. De esta forma, podremos ayudarlo a investigar la causa de este error de autenticación.