Autorización y API de seguridad de Microsoft GraphAuthorization and the Microsoft Graph Security API

Los datos de seguridad accesibles a través de la API de seguridad de Microsoft Graph son confidenciales y están protegidos por los permisos y los roles de Azure Active Directory (Azure AD).Security data accessible via the Microsoft Graph Security API is sensitive and protected by both permissions and Azure Active Directory (Azure AD) roles.

La API de seguridad de Microsoft Graph admite dos tipos de autorización:The Microsoft Graph Security API supports two types of authorization:

  • Autorización a nivel de aplicación: ningún usuario inició sesión (por ejemplo, un escenario SIEM).Application-level authorization - There is no signed-in user (for example, a SIEM scenario). Los permisos otorgados a la aplicación determinan la autorización.The permissions granted to the application determine authorization.

    Nota: esta opción también admite casos en los que la aplicación administra el Control de acceso basado en roles (RBAC).Note: This option can also support cases where Role-Based Access Control (RBAC) is managed by the application.

  • Autorización delegada por el usuario: un usuario miembro del espacio empresarial de Azure AD ha iniciado sesión.User delegated authorization - A user who is a member of the Azure AD tenant is signed in. El usuario debe ser miembro de un rol de administrador limitado de Azure AD (ya sea lector o administrador de seguridad) y, además, la aplicación debe contar con los permisos necesarios.The user must be a member of an Azure AD Limited Admin role - either Security Reader or Securty Administrator - in addition to the application having been granted the required permissions.

Si realiza una llamada a la API de seguridad de Microsoft Graph desde Probador de Graph:If you're calling the Microsoft Graph Security API from Graph Explorer:

  • El administrador del espacio empresarial de Azure AD debe conceder de forma explícita los permisos solicitados a la aplicación del Explorador de Graph.The Azure AD tenant admin must explicitly grant consent for the requested permissions to the Graph Explorer application.
  • El usuario debe ser miembro del rol de administrador limitado del lector de seguridad en Azure AD (ya sea lector o administrador de seguridad).The user must be a member of the Security Reader Limited Admin role in Azure AD (either Security Reader or Security Administrator).

Nota: el Explorador de Graph no admite la autorización a nivel de aplicación.Note: Graph Explorer does not support application-level authorization.

Si realiza una llamada a la API de seguridad de Microsoft Graph desde una aplicación propia o personalizada:If you're calling the Microsoft Graph Security API from a custom or your own application:

  • El administrador del espacio empresarial de Azure AD debe conceder de forma explícita los permisos a su aplicación.The Azure AD tenant admin must explicitly grant consent to your application. Esto es necesario tanto para las autorizaciones a nivel de aplicación y delegadas por usuarios.This is required both for application-level authorization and user delegated authorization.
  • Si usa una autorización delegada por usuario, dicha persona debe ser miembro del rol de administrador limitado del lector o administrador de seguridad en Azure AD.If you're using user delegated authorization, the user must be a member of the Security Reader or Security Administrator Limited Admin role in Azure AD.

Administrar la autorización en las aplicaciones cliente con API de seguridadManage authorization in security API client applications

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.Security data provided via the Microsoft Graph Security API is sensitive and must be protected by appropriate authentication and authorization mechanisms. 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.The following table lists the steps to register and create a client application that can access the Microsoft Graph Security API.

QuiénWho AcciónAction
Propietario o desarrollador de la aplicaciónApplication developer or owner Registra la aplicación como una aplicación de empresa.Register the application as an enterprise application.
Administrador de un espacio empresarialTenant admin Le concede permisos a la aplicación.Grant permissions to the application.
Administrador de un espacio empresarialTenant admin Asigna roles a los usuarios.Assign roles to users.
Desarrollador de la aplicaciónApplication developer Inicia sesión como usuario y usa la aplicación para acceder a la API de seguridad de Microsoft Graph.Sign in as the user and use the application to access the Microsoft Graph Security API.

El registro de la aplicación solo define qué permisos necesita la aplicación para poder ejecutarse.Application registration only defines which permissions the application needs in order to run. NO le concede los permisos a la aplicación.It does NOT grant these permissions to the application.

El administrador de espacios empresariales de Azure AD DEBE conceder de forma explícita los permisos a la aplicación.The Azure AD tenant administrator MUST explicitly grant the permissions to the application. Esto debe realizarse por espacio empresarial cada vez que se modifican los permisos de aplicación en el portal de registro correspondiente.This must be done per tenant and must be performed every time the application permissions are changed in the application registration portal.

Por ejemplo, imagine que tiene una aplicación, dos espacios empresariales de Azure AD (E1 y E2) y dos permisos (P1 y P2).For example, assume that you have an application, two Azure AD tenants, T1 and T2, and two permissions, P1 and P2. A continuación, se muestra el proceso de autorización:The following is the authorization process:

  • La aplicación se registra para exigir el permiso P1.The application registers to require permission P1.
  • Cuando los usuarios del espacio empresarial E1 obtienen un token de Azure AD para esta aplicación, el token no contiene ningún permiso.When users in tenant T1 get an Azure AD token for this application, the token does not contain any permissions.
  • El administrador de Azure AD del espacio empresarial E1 concede de forma explícita permisos a la aplicación.The Azure AD admin of tenant T1 explicitly grants permissions to the application. Cuando los usuarios del espacio empresarial E1 obtienen un token de Azure AD para la aplicación, el token contendrá el permiso P1.When users in tenant T1 get an Azure AD token for the application, it will contain permission P1.
  • Cuando los usuarios del espacio empresarial E2 obtienen un token de Azure AD para la aplicación, el token no contiene ningún permiso, ya que el administrador del espacio empresarial E2 todavía no le ha concedido permisos a la aplicación.When users in tenant T2 get an Azure AD token for the application, the token does not contain any permissions - because the admin of tenant T2 did not yet grant permissions to the application. Los permisos deben otorgarse por espacio empresarial y por aplicación.Permission must be granted per tenant and per application.
  • El registro de la aplicación cambia para que ahora se requieran permisos P1 y P2.The application has its registration changed to now require permissions P1 and P2.
  • Cuando los usuarios del espacio empresarial E1 obtienen un token de Azure AD para la aplicación, el token solo contendrá el permiso P1.When users in tenant T1 get an Azure AD token for the application, it only contains permission P1. Los permisos concedidos a una aplicación se registran como instantáneas de lo que se le ha concedido: no cambian automáticamente después de que cambie el registro (permiso) de la aplicación.Permissions granted to an application are recorded as snapshots of what was granted - they do not change automatically after the application registration (permission) changes.
  • El administrador del espacio empresarial E2 le concede permisos P1 y P2 a la aplicación.The admin of tenant T2 grants permissions P1 and P2 to the application. Ahora bien, cuando los usuarios del espacio empresarial E2 obtienen un token de Azure AD para la aplicación, el token contendrá los permisos P1 y P2.Now, when users in tenant T2 get an Azure AD token for the application, the token will contain permissions P1 and P2.

Nota: Los tokens de Azure AD para la aplicación en el espacio empresarial E1 y E2 contienen diferentes permisos, ya que cada administrador del espacio empresarial ha concedido diferentes permisos a la aplicación.Note: The Azure AD tokens for the application in tenant T1 and the application in tenant T2 contain different permissions, because each tenant admin has granted different permissions to the application.

  • 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.To make the application work again in tenant T1, the admin of tenant T1 must explicitly grant permissions P1 and P2 to the application.

Registro de una aplicación con el punto de conexión de la plataforma de identidad de Microsoft para desarrolladoresRegister an application with the Microsoft identity platform endpoint

Para registrar una aplicación con el punto de conexión de plataforma de identidad de Microsoft para desarrolladores, necesitará:To register an application to the Microsoft identity platform endpoint, you'll need:

  • Nombre de la aplicación: una cadena que se usa para el nombre de aplicación.Application name - A string used for the application name.
  • Dirección URL de redirección: la dirección URL desde donde se envía la respuesta de autenticación de Azure AD.Redirect URL - The URL where the authentication response from Azure AD is sent. Para comenzar, puede usar la página principal de prueba de la aplicación web del cliente.To start, you can use the test client web app homepage.
  • Permisos necesarios: los permisos que necesita su aplicación para poder realizar una llamada a Microsoft Graph.Required Permissions - The permissions that your application requires to be able to call Microsoft Graph.

Para registrar su aplicación, haga lo siguiente:To register your application:

  1. Vaya al portal de registro de aplicaciones de Azure e inicie sesión.Go to the Azure app registration portal and sign in.

    Nota: No necesita ser administrador de espacios empresariales. Se lo redirigirá a la lista Mis aplicaciones.Note: You don't have to be a tenant admin. You will be redirected to the My applications list.

  2. Seleccione Nuevo registro.Choose New registration.

  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.On the registration page for the new application, enter a value for Name and select the account types you wish to support. En el campo Dirección URL de redireccionamiento, escriba la URL correspondiente.In the Redirect URI field, enter the redirect URL.

  4. Seleccione Registrar para crear la aplicación y ver su página de información general.Select Register to create the app and view its overview page. *

  5. Vaya a la página Permisos de API.Go to the app's API permissions page.

  6. Seleccione Agregar un permiso y, a continuación, elija Microsoft Graph en el control flotante.Select Add a permission and then choose Microsoft Graph in the flyout. Seleccione Permisos delegadosSelect Delegated permissions. Use el cuadro de búsqueda para buscar y seleccionar los permisos necesarios.Use the search box to find and select the required permissions. Para obtener una lista de permisos, consulte Permisos de seguridad.For a list of permissions, see Security permissions.

    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.Note: The Microsoft Graph Security API requires the *.Read.All scope for GET queries, and the *.ReadWrite.All scope for PATCH/POST/DELETE queries.

    PermisoPermission EntidadEntity Solicitudes admitidasSupported requests
    SecurityActions.Read.AllSecurityActions.Read.All securityActions (versión preliminar)securityActions (preview) GETGET
    SecurityActions.ReadWrite.AllSecurityActions.ReadWrite.All securityActions (versión preliminar)securityActions (preview) GET, POSTGET, POST
    SecurityEvents.Read.AllSecurityEvents.Read.All alertsalerts
    secureScoressecureScores
    secureScoreControlProfilessecureScoreControlProfiles
    OBTENERGET
    SecurityEvents.ReadWrite.AllSecurityEvents.ReadWrite.All alertsalerts
    secureScoressecureScores
    secureScoreControlProfilessecureScoreControlProfiles
    GET, POST, PATCHGET, POST, PATCH
    ThreatIndicators.ReadWrite.OwnedByThreatIndicators.ReadWrite.OwnedBy tiIndicator (versión preliminar)tiIndicator (preview) GET, POST, PATCH, DELETEGET, POST, PATCH, DELETE
  7. Elija Agregar permisos.Choose Add permissions.

Guarde la siguiente información:Save the following information:

  • Identificador de aplicación (cliente)Application (client) ID
  • Dirección URL de redireccionamientoRedirect URL
  • Lita de permisos necesariosList of required permissions

* La Protección contra amenazas avanzada de Windows Defender (WDATP) requiere roles de usuario adicionales a los que necesita la API de seguridad de Microsoft Graph. Por lo tanto, solo los usuarios de los roles de la API Microsoft Graph Security y WDATP pueden tener acceso a los datos de WDATP.* Windows Defender Advanced Threat Protection (WDATP) requires additional user roles than what is required by the Microsoft Graph Security API; therefore, only the users in both WDATP and Microsoft Graph Security API roles can have access to the WDATP data. 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.Application-only authentication is not limited by this; therefore, we recommend that you use an app-only authentication token.

Para más información, vea Registrar la aplicación con la plataforma de identidad de Microsoft.For more information, see Register your app with the Microsoft identity platform.

Conceda permisos a la aplicación.Grant permissions to an application

El registro de la aplicación solo define qué permisos necesita la aplicación y no le concede los permisos.Application registration only defines which permission the application requires - it does not grant these permissions to the application. Un administrador de espacios empresariales de Azure AD explícitamente debe conceder estos permisos de forma explícita mediante una llamada al punto de conexión de consentimiento de administrador.An Azure AD tenant administrator must explicitly grant these permissions by making a call to the admin consent endpoint. Para obtener más información, consulte Usar el punto de conexión de consentimiento de administrador.For details, see Using the admin consent endpoint.

Para conceder permisos a una aplicación, necesitará lo siguiente:To grant permissions to an application, you'll need:

  • Id. de aplicación: el Id. de aplicación del portal de registro de la aplicación de Azure.Application ID - The application ID from the Azure application registration portal.
  • Dirección URL de redireccionamiento: la cadena que configure en el portal de registro de la aplicación de Azure para la respuesta de autenticación.Redirect URL - The string you set in the Azure application registration portal for authentication response.

Para conceder los permisos:To grant the permissions:

  • En un editor de texto, cree la siguiente cadena de dirección URL:In a text editor, create the following URL string:

    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.In a web browser, go to this URL, and sign in as a tenant administrator. 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.The dialog box shows the list of permission the application requires, as specified in the application registration portal. Elija Aceptar para conceder estos permisos a la aplicación.Choose OK to grant the application these permissions.

Nota: Este paso concede permisos a la aplicación, no a los usuarios.Note: This step grants permissions to the application - not to users. Esto significa que a todos los usuarios que pertenezcan al espacio empresarial de Azure AD y que usen esta aplicación se les concederán los permisos, incluso a los usuarios que no son administradores.This means that all users belonging to the Azure AD tenant that use this application will be granted these permissions - even non-admin users.

Asignar roles de Azure AD a usuariosAssign Azure AD roles to users

Después de que se conceden permisos a una aplicación, todos los usuarios con acceso a ella (es decir, los miembros del espacio empresarial de Azure AD) reciben los permisos concedidos.After an application is granted permissions, everyone with access to the application (that is, members of the Azure AD tenant) will receive the granted permissions. Para proteger datos confidenciales de seguridad, la API de seguridad de Microsoft Graph también requiere que a los usuarios se les asigne el rol de lector de seguridad de Azure AD.To further protect sensitive security data, the Microsoft Graph Security API also requires users to be assigned the Azure AD Security Reader role. Para obtener más información, vea Permisos de roles de administrador en Azure Active Directory y Asignar roles de administrador y de no administrador a los usuarios con Azure Active Directory.For details, see Administrator role permissions in Azure Active Directory and Assign administrator and non-administrator roles to users with Azure Active Directory.

Nota: Para realizar este paso, debe ser administrador de un espacio empresarial.Note: You must be a tenant admin to perform this step.

Para asignar un rol a un usuario:To assign an RBAC role to a user

  1. Inicie sesión en Azure Portal (https://portal.azure.com)).Sign in to the Azure portal (https://portal.azure.com).
  2. Haga clic en el icono de la esquina superior izquierda para expandir el menú de Azure Portal.Click the icon in the top left to expand the Azure portal menu. Seleccione Azure Active Directory > Usuarios.Select Azure Active Directory.
  3. Haga clic en el nombre del usuario.Click the user name of the account.
  4. Elija Roles asignados y, después, Agregar tarea.Choose Assigned roles, and then Add assignment.
  5. SeleccioneLector de seguridad y haga clic en Agregar.Select Security reader, and click Add.

Crear un código de autenticaciónCreate an authentication code

Para crear un código de autenticación, necesitará lo siguiente:To create an authentication code, you'll need:

  • Id. de aplicación: el Id. de aplicación del portal de registro de la aplicación.Application ID - The application ID from application registration portal.
  • Dirección URL de redirección: la dirección URL desde donde se envía la respuesta de autenticación de Azure AD.Redirect URL - The URL where the authentication response from Azure AD is sent. Para comenzar, puede usar https://localhost o la página principal de prueba de la aplicación web del cliente.To start, you can use https://localhost or the test client web app homepage.
  • Tecla de aplicación (opcional): la tecla de la aplicación.Application Key (optional) - The key of the application. 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).This applies when you're developing an application that will use application-only authentication code (that is, will not support user delegated authentication).

En la siguiente tabla se indican los recursos que puede usar para crear un código de autenticación.The following table lists resources that you can use to create an authentication code.

Tipo de aplicaciónType of application Biblioteca de autenticaciónAuthentication library
Aplicaciones de escritorio - iOSDesktop apps - iOS MSAL.framework: Biblioteca de autenticación de Microsoft (versión preliminar para iOS)MSAL.framework: Microsoft Authentication Library Preview for iOS
Aplicaciones de escritorio - AndroidDesktop apps - Android Biblioteca de autenticación de Microsoft (MSAL)Microsoft Authentication Library (MSAL)
Aplicaciones de escritorio - .NetDesktop apps - .Net Biblioteca de autenticación de Microsoft (MSAL)Microsoft Authentication Library (MSAL)
Aplicaciones web - JavaScript SPAWeb apps - JavaScript SPA Biblioteca de autenticación de Microsoft para JavaScript (versión preliminar)Microsoft Authentication Library for JavaScript Preview
Aplicaciones web - Servidor web de .NETWeb apps - .NET Web Server OpenIdConnection, Cookies, SystemWebOpenIdConnection, Cookies, SystemWeb
Aplicaciones web - aplicaciones web NodeJSWeb apps - NodeJS Web App

En el caso de las aplicaciones que no utilizan ninguna de las bibliotecas existentes, consulte Obtener acceso en nombre de un usuario.For applications that don't use any of the existing libraries, see Get access on behalf of a user.

  1. Obtenga un código de Azure AD.Get a code from Azure AD. La consulta a la llamada contiene el parámetro de Id. de aplicación, Dirección URL de redirección y los permisos necesarios.The query to call contains parameter for Application ID, Redirect URl, and required permissions.
  2. Use el código para obtener un token de acceso.Use the code to get an access token.

Si usa una biblioteca de OpenId Connect, consulte Autenticarse con Azure AD y OpenID Connect y realice una llamada a app.UseOpenIdConnectAuthentication().If you use OpenId Connect library, see Authenticate using Azure AD and OpenID Connect and call app.UseOpenIdConnectAuthentication().

Nota: Si está solicitando tokens de autenticación delegados por el usuario, el parámetro de la biblioteca es Ámbitos solicitados.Note: If you're requesting user delegated authentication tokens, the parameter for the library is Requested Scopes. Use "User.Read" para este parámetro en lugar de lo que requiere la aplicación registrada.Use User.Read for this parameter instead of what the registered application requires. El parámetro Ámbitos solicitados NO afecta a los permisos que contienen los tokens de autenticación que se muestran.The Requested Scopes parameter does NOT affect the permissions contained in the returned authentication tokens. Estos dependen de los permisos que el administrador del espacio empresarial concede a la aplicación.These are determined by the permissions that the tenant admin granted the application.

Por ejemplo, si usa la biblioteca de .NET MSAL, realice una llamada a lo siguiente:For example, if you're using the .NET MSAL library, call the following:

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

Nota: Este ejemplo debe utilizar los permisos con privilegios mínimos, como "User.Read".Note: This example should use the least privileged permission, such as 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".However, the returned access token can contain permissions that were granted by the tenant admin for the current user tenant, such as User.Read.All or User.ReadWrite.All.

Azure AD muestra un token (cadena) que contiene su información de autenticación y los permisos que necesita la aplicación.A token (string) is returned by Azure AD that contains your authentication information and the permissions required by the application. Asigne este token al encabezado HTTP como un token portador, tal como se muestra en el siguiente ejemplo.Assign this token to the HTTP header as a bearer token, as shown in the following example.

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

Microsoft Graph validará la información que contenga este token y concederá o rechazará el acceso.Microsoft Graph will validate the information contained in this token and grant, or reject, access.

Para ver notificaciones incluidas en el token que se muestre, use la biblioteca "System.IdentityModel.Tokens.Jwt" de NuGet.To view claims contained in the returned token, use NuGet library System.IdentityModel.Tokens.Jwt.

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.The response from Microsoft Graph contains a header called client-request-id, which is a 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.If access is denied, please specify this GUID when seeking support at Microsoft Tech Community, so we can help investigate the cause of this authentication failure.