Uso del identificador de Microsoft Entra para acceder a las API de Intune en Microsoft Graph

Artículo
07/30/2024

Microsoft Graph API ahora admite Microsoft Intune con API y roles de permisos específicos. Microsoft Graph API usa Microsoft Entra ID para la autenticación y el control de acceso.
El acceso a las API de Intune en Microsoft Graph requiere lo siguiente:

Un identificador de la aplicación con:
- Permiso para llamar a Microsoft Entra ID y las API de Microsoft Graph.
- Ámbitos de permiso pertinentes a tareas de aplicación específicas.
Credenciales de usuario con:
- Permiso para acceder al inquilino de Microsoft Entra asociado a la aplicación.
- Permisos de rol necesarios para admitir los ámbitos de permiso de aplicación.
El usuario final que concederá permiso a la aplicación para realizar tareas de aplicaciones para su inquilino de Azure.

En este artículo:

Muestra cómo registrar una aplicación con acceso a Microsoft Graph API y roles de permisos pertinentes.
Describe los roles de permiso de api de Intune.
Proporciona ejemplos de autenticación de API de Intune para C# y PowerShell.
Describe cómo admitir varios inquilinos.

Para más información, vea:

Registro de aplicaciones para usar la API de Microsoft Graph

Para registrar una aplicación para usar la API de Microsoft Graph:

Inicie sesión en el Centro de administración de Microsoft Intune con credenciales administrativas.

Según corresponda, puede usar:
- La cuenta de administrador de inquilinos.
- Una cuenta de usuario de inquilino con la opción Usuarios puede registrar aplicaciones habilitada.
Seleccione Todos los servicios>M365 Microsoft Entra ID>Microsoft Entra Id>. Registros de aplicaciones.
Elija Nuevo registro para crear una nueva aplicación o elija una aplicación existente. (Si elige una aplicación existente, omita el paso siguiente).
En el panel Registrar una aplicación , especifique lo siguiente:
- Nombre de la aplicación (que se muestra cuando los usuarios inician sesión).
- Tipo de cuenta compatible.
- Valor de URI de redireccionamiento . Este valor es la opción .
  
  Nota:
  
  Graph API de Azure AD está en su fase de retirada. Para obtener más información, consulte Actualizar las aplicaciones para que usen la Biblioteca de autenticación de Microsoft (MSAL) y la API de Microsoft Graph.
  
  Para más información, consulte Escenarios de autenticación para el identificador de microsoft entra.
Desde el panel de la aplicación:
1. Tenga en cuenta el valor de id. de aplicación (cliente).
2. Seleccione Permisos de API.
En el panel Permisos de API, elija Agregar un permiso>API> deMicrosoft Microsoft Graph. A continuación, seleccione el tipo de permisos que requiere la aplicación.

Elija los roles necesarios para la aplicación colocando una marca de verificación a la izquierda de los nombres pertinentes. Para obtener información sobre ámbitos de permisos específicos de Intune, consulte Ámbitos de permisos de Intune. Para obtener información sobre otros ámbitos de permisos de Graph API, consulte Referencia de permisos de Microsoft Graph.

Para obtener mejores resultados, elija la menor cantidad de roles necesarios para implementar la aplicación.

Permisos de almacenamiento de datos e informes

Al agregar una aplicación a través del Centro de administración de Microsoft Entra, puede elegir los permisos de API de Intune en función de los requisitos de la aplicación.

get_data_warehouse : use este permiso de API para conceder acceso a la API de almacenamiento de datos de Intune desde Microsoft Intune. Para obtener más información, consulte Uso del almacenamiento de datos de Microsoft Intune.

API de solución de asociados

Los siguientes permisos de API de Intune están disponibles al agregar una aplicación a través del Centro de administración de Microsoft Entra:

get_device_compliance : este permiso de API se usa para obtener información sobre el estado del dispositivo y el cumplimiento de Microsoft Intune. Los asociados de Control de acceso de red usan este permiso de API. Para obtener más información, consulte Integración del control de acceso de red con Intune.
manage_partner_compliance_policy : este permiso de API se usa para administrar las directivas de cumplimiento de asociados con Microsoft Intune. Este permiso de API permite a la aplicación enviar directivas de cumplimiento de asociados y su asignación de grupo de Microsoft Entra a Microsoft Intune sin que un usuario haya iniciado sesión. Lo usan los asociados de cumplimiento de dispositivos. Para obtener más información, consulte Asociados de cumplimiento de dispositivos de terceros.
pfx_cert_provider : este permiso de API se usa para enviar certificados PFX a Intune para un usuario específico. Intune entrega el certificado a todos los dispositivos inscritos por el usuario. Para obtener más información, vea Importación de PowerShell de PFX.
scep_challenge_provider : este permiso de API se usa para enviar desafíos SCEP a Intune para la validación de solicitudes de certificado. Lo usan los asociados de la entidad de certificación. Para obtener más información, consulte Entidad de certificación de asociados.
update_device_attributes : este permiso de API se usa para enviar información del dispositivo a Intune desde asociados de cumplimiento de dispositivos y de defensa contra amenazas móviles. Para obtener más información, consulte Integración de Mobile Threat Defense con Intune y asociados de cumplimiento de dispositivos de terceros.
update_device_health : este permiso de API se usa para enviar información de estado de amenazas y estado del dispositivo a Intune desde asociados de mobile threat defense. Para obtener más información, consulte Integración de Mobile Threat Defense con Intune.

Si es un asociado interesado en la integración con Intune mediante estos permisos de API, póngase en contacto con el equipo de Microsoft Intelligent Security Association] para obtener información.

Cuando haya terminado, elija Agregar permisos para guardar los cambios.

En este momento, también puede hacer lo siguiente:

Elija conceder permiso para que todas las cuentas de inquilino usen la aplicación sin proporcionar credenciales.

Para ello, puede conceder permisos y aceptar el mensaje de confirmación.

Al ejecutar la aplicación por primera vez, se le pedirá que conceda permiso a la aplicación para realizar los roles seleccionados.
Haga que la aplicación esté disponible para los usuarios fuera de su inquilino. (Normalmente, esto solo es necesario para los asociados que admiten varios inquilinos o organizaciones).

Para ello:
1. Elija Manifiesto en el panel de la aplicación.
2. Cambie el valor de la availableToOtherTenants configuración a true.
3. Guarde los cambios.

Lista de aplicaciones

Si recibe una gran cantidad de datos al solicitar la descripción de la aplicación al usar Graph API, es posible que encuentre un error 503 Service Unavailable. Se recomienda volver a intentarlo con un tamaño de página más pequeño, como 20 o menos elementos.

Ámbitos de permisos de Intune

Microsoft Entra ID y Microsoft Graph usan ámbitos de permisos para controlar el acceso a los recursos corporativos.

Los ámbitos de permisos (también denominados ámbitos de OAuth) controlan el acceso a entidades específicas de Intune y sus propiedades. En esta sección se resumen los ámbitos de permisos de las características de api de Intune.

Para obtener más información:

Al conceder permiso a Microsoft Graph, puede especificar los siguientes ámbitos para controlar el acceso a las características de Intune: en la tabla siguiente se resumen los ámbitos de permisos de la API de Intune. La primera columna muestra el nombre de la característica como se muestra en el Centro de administración de Microsoft Intune y la segunda columna proporciona el nombre del ámbito del permiso.

Habilitación de la configuración de Acceso	Nombre de ámbito
Realizar acciones remotas que repercutan en el usuario en dispositivos de Microsoft Intune	DeviceManagementManagedDevices.PrivilegedOperations.All
Leer y escribir dispositivos de Microsoft Intune	DeviceManagementManagedDevices.ReadWrite.All
Leer dispositivos de Microsoft Intune	DeviceManagementManagedDevices.Read.All
Leer y escribir la configuración de RBAC de Microsoft Intune	DeviceManagementRBAC.ReadWrite.All
Leer la configuración de RBAC de Microsoft Intune	DeviceManagementRBAC.Read.All
Leer y escribir aplicaciones de Microsoft Intune	DeviceManagementApps.ReadWrite.All
Leer aplicaciones de Microsoft Intune	DeviceManagementApps.Read.All
Directivas y configuración de dispositivos de Microsoft Intune de lectura y escritura	DeviceManagementConfiguration.ReadWrite.All
Leer directivas y configuración de dispositivos de Microsoft Intune	DeviceManagementConfiguration.Read.All
Leer y escribir la configuración de Microsoft Intune	DeviceManagementServiceConfig.ReadWrite.All
Leer la configuración de Microsoft Intune	DeviceManagementServiceConfig.Read.All

En la tabla se muestra la configuración tal como aparecen en el Centro de administración de Microsoft Intune. En las secciones siguientes se describen los ámbitos en orden alfabético.

En este momento, todos los ámbitos de permisos de Intune requieren acceso de administrador. Esto significa que necesita las credenciales correspondientes al ejecutar aplicaciones o scripts que acceden a los recursos de la API de Intune.

DeviceManagementApps.Read.All

Habilitar la configuración de Acceso : Leer aplicaciones de Microsoft Intune
Permite el acceso de lectura a las siguientes propiedades y estado de entidad:
- Aplicaciones cliente
- Categorías de aplicaciones móviles
- Directivas de protección de aplicaciones
- Configuraciones de aplicaciones

DeviceManagementApps.ReadWrite.All

Habilitar la configuración de Acceso : Leer y escribir aplicaciones de Microsoft Intune
Permite las mismas operaciones que DeviceManagementApps.Read.All
También permite cambios en las siguientes entidades:
- Aplicaciones cliente
- Categorías de aplicaciones móviles
- Directivas de protección de aplicaciones
- Configuraciones de aplicaciones

DeviceManagementConfiguration.Read.All

Habilitar la configuración de acceso : Leer directivas y configuración de dispositivos de Microsoft Intune
Permite el acceso de lectura a las siguientes propiedades y estado de entidad:
- Configuración de dispositivo
- Directiva de cumplimiento de dispositivos
- Mensajes de notificación

DeviceManagementConfiguration.ReadWrite.All

Habilitar la configuración de acceso : directivas y configuración de dispositivos de Microsoft Intune de lectura y escritura
Permite las mismas operaciones que DeviceManagementConfiguration.Read.All
Las aplicaciones también pueden crear, asignar, eliminar y cambiar las siguientes entidades:
- Configuración de dispositivo
- Directiva de cumplimiento de dispositivos
- Mensajes de notificación

DeviceManagementManagedDevices.PrivilegedOperations.All

Habilitar la configuración de acceso : realizar acciones remotas que afecten al usuario en dispositivos de Microsoft Intune
Permite las siguientes acciones remotas en un dispositivo administrado:
- Retirar
- Barrido
- Restablecer o recuperar código de acceso
- Bloqueo remoto
- Habilitar o deshabilitar el modo perdido
- Limpieza del equipo
- Reiniciar
- Eliminar usuario del dispositivo compartido

DeviceManagementManagedDevices.Read.All

Habilitar la configuración de acceso : Leer dispositivos de Microsoft Intune
Permite el acceso de lectura a las siguientes propiedades y estado de entidad:
- Dispositivo administrado
- Categoría de dispositivo
- Aplicación detectada
- Acciones remotas
- Información de malware

DeviceManagementManagedDevices.ReadWrite.All

Habilitar la configuración de Acceso : Leer y escribir dispositivos de Microsoft Intune
Permite las mismas operaciones que DeviceManagementManagedDevices.Read.All
Las aplicaciones también pueden crear, eliminar y cambiar las siguientes entidades:
- Dispositivo administrado
- Categoría de dispositivo
También se permiten las siguientes acciones remotas:
- Buscar dispositivos
- Deshabilitar bloqueo de activación
- Solicitar asistencia remota

DeviceManagementRBAC.Read.All

Habilitar la configuración de Acceso : Leer la configuración de RBAC de Microsoft Intune
Permite el acceso de lectura a las siguientes propiedades y estado de entidad:
- Asignaciones de roles
- Definiciones de roles
- Operaciones de recursos

DeviceManagementRBAC.ReadWrite.All

Habilitar la configuración de Acceso : lectura y escritura de la configuración de RBAC de Microsoft Intune
Permite las mismas operaciones que DeviceManagementRBAC.Read.All
Las aplicaciones también pueden crear, asignar, eliminar y cambiar las siguientes entidades:
- Asignaciones de roles
- Definiciones de roles

DeviceManagementServiceConfig.Read.All

Habilitar la configuración de acceso : Leer la configuración de Microsoft Intune
Permite el acceso de lectura a las siguientes propiedades y estado de entidad:
- Inscripción de dispositivos
- Certificado de notificación push de Apple
- Programa de inscripción de dispositivos de Apple
- Programa de compras por volumen de Apple
- Exchange Connector
- Términos y Condiciones
- PKI en la nube
- Personalización de marca
- Mobile Threat Defense

DeviceManagementServiceConfig.ReadWrite.All

Habilitación de la configuración de Access : lectura y escritura de la configuración de Microsoft Intune
Permite las mismas operaciones que DeviceManagementServiceConfig.Read.All_
Las aplicaciones también pueden configurar las siguientes características de Intune:
- Inscripción de dispositivos
- Certificado de notificación push de Apple
- Programa de inscripción de dispositivos de Apple
- Programa de compras por volumen de Apple
- Exchange Connector
- Términos y Condiciones
- PKI en la nube
- Personalización de marca
- Mobile Threat Defense

Ejemplos de autenticación de Microsoft Entra

En esta sección se muestra cómo incorporar el identificador de Microsoft Entra en los proyectos de C# y PowerShell.

En cada ejemplo, deberá especificar un identificador de aplicación que tenga al menos el ámbito de DeviceManagementManagedDevices.Read.All permiso (descrito anteriormente).

Al probar cualquiera de los ejemplos, puede recibir errores de estado HTTP 403 (prohibido) similares a los siguientes:

{
  "error": {
    "code": "Forbidden",
    "message": "Application is not authorized to perform this operation - Operation ID " +
       "(for customer support): 00000000-0000-0000-0000-000000000000 - " +
       "Activity ID: cc7fa3b3-bb25-420b-bfb2-1498e598ba43 - " +
       "Url: https://example.manage.microsoft.com/" +
       "Service/Resource/RESTendpoint?" +
       "api-version=2017-03-06 - CustomApiErrorPhrase: ",
    "innerError": {
      "request-id": "00000000-0000-0000-0000-000000000000",
      "date": "1980-01-0112:00:00"
    }
  }
}

Si esto ocurre, compruebe que:

Ha actualizado el identificador de aplicación a uno autorizado para usar Microsoft Graph API y el ámbito de DeviceManagementManagedDevices.Read.All permisos.
Las credenciales de inquilino admiten funciones administrativas.
El código es similar a los ejemplos mostrados.

Autenticación del identificador de Microsoft Entra en C#

En este ejemplo se muestra cómo usar C# para recuperar una lista de dispositivos asociados a su cuenta de Intune.

Nota:

Graph API de Azure AD está en su fase de retirada. Para obtener más información, consulte Actualizar las aplicaciones para que usen la Biblioteca de autenticación de Microsoft (MSAL) y la API de Microsoft Graph.

Inicie Visual Studio y, a continuación, cree un nuevo proyecto de aplicación de consola de Visual C# (.NET Framework).
Escriba un nombre para el proyecto y proporcione otros detalles como desee.
Use el Explorador de soluciones para agregar el paquete NuGet de Microsoft MSAL al proyecto:
1. Haga clic con el botón derecho en el Explorador de soluciones.
2. Elija Administrar paquetes NuGet...>Examinar.
3. Seleccione Microsoft.Identity.Client y, a continuación, elija Instalar.
Agregue las siguientes instrucciones a la parte superior de Program.cs:
```
using Microsoft.Identity.Client;
using System.Net.Http;
```

Agregue un método para crear el encabezado de autorización:

private static async Task<string> GetAuthorizationHeader()
{
    string applicationId = "<Your Application ID>";
    string authority = "https://login.microsoftonline.com/common/";
    Uri redirectUri = new Uri("urn:ietf:wg:oauth:2.0:oob");
    AuthenticationContext context = new AuthenticationContext(authority);
    AuthenticationResult result = await context.AcquireTokenAsync(
        "https://graph.microsoft.com",
        applicationId, redirectUri,
        new PlatformParameters(PromptBehavior.Auto));
    return result.CreateAuthorizationHeader();

Recuerde cambiar el valor de application_ID para que coincida con uno concedido al menos el ámbito de DeviceManagementManagedDevices.Read.All permiso, como se describió anteriormente.

Agregue un método para recuperar la lista de dispositivos:

private static async Task<string> GetMyManagedDevices()
{
    string authHeader = await GetAuthorizationHeader();
    HttpClient graphClient = new HttpClient();
    graphClient.DefaultRequestHeaders.Add("Authorization", authHeader);
    return await graphClient.GetStringAsync(
        "https://graph.microsoft.com/beta/me/managedDevices");
}

Actualice Main para llamar a GetMyManagedDevices:

string devices = GetMyManagedDevices().GetAwaiter().GetResult();
Console.WriteLine(devices);

Compile y ejecute el programa.

Cuando ejecute el programa por primera vez, debería recibir dos mensajes. La primera solicita sus credenciales y la segunda concede permisos para la managedDevices solicitud.

Como referencia, este es el programa completado:

using Microsoft.Identity.Client;
using System;
using System.Net.Http;
using System.Threading.Tasks;

namespace IntuneGraphExample
{
    class Program
    {
        static void Main(string[] args)
        {
            string devices = GetMyManagedDevices().GetAwaiter().GetResult();
            Console.WriteLine(devices);
        }

        private static async Task<string> GetAuthorizationHeader()
        {
            string applicationId = "<Your Application ID>";
            string authority = "https://login.microsoftonline.com/common/";
            Uri redirectUri = new Uri("urn:ietf:wg:oauth:2.0:oob");
            AuthenticationContext context = new AuthenticationContext(authority);
            AuthenticationResult result = await context.AcquireTokenAsync("https://graph.microsoft.com", applicationId, redirectUri, new PlatformParameters(PromptBehavior.Auto));
            return result.CreateAuthorizationHeader();
        }

        private static async Task<string> GetMyManagedDevices()
        {
            string authHeader = await GetAuthorizationHeader();
            HttpClient graphClient = new HttpClient();
            graphClient.DefaultRequestHeaders.Add("Authorization", authHeader);
            return await graphClient.GetStringAsync("https://graph.microsoft.com/beta/me/managedDevices");
        }
    }
}

Autenticación del identificador de Microsoft Entra mediante PowerShell de Microsoft Graph

Los scripts de PowerShell pueden usar el módulo de PowerShell de Microsoft Graph para la autenticación. Para más información, consulte Microsoft Graph PowerShell y los ejemplos de PowerShell de Intune.

Compatibilidad con varios inquilinos y asociados

Si su organización admite organizaciones con sus propios inquilinos de Microsoft Entra, es posible que desee permitir que los clientes usen la aplicación con sus respectivos inquilinos.

Para ello:

Compruebe que la cuenta de cliente existe en el inquilino de Microsoft Entra de destino.
Compruebe que la cuenta de inquilino permite a los usuarios registrar aplicaciones (consulte Configuración de usuario).
Establecer una relación entre cada inquilino.

Para ello, haga lo siguiente:

a. Use el Centro de partners de Microsoft para definir una relación con el cliente y su dirección de correo electrónico.

b. Invite al usuario a convertirse en invitado de su inquilino.

Para invitar al usuario a ser un invitado de su inquilino:

Elija Agregar un usuario invitado en el panel Tareas rápidas .
Escriba la dirección de correo electrónico del cliente y, opcionalmente, agregue un mensaje personalizado para la invitación.
Elija Invitar.

Esto envía una invitación al usuario.

El usuario debe elegir el vínculo Introducción para aceptar la invitación.

Cuando se establezca la relación (o se acepte la invitación), agregue la cuenta de usuario al rol Directorio.

No olvide agregar el usuario a otros roles según sea necesario. Por ejemplo, para permitir que el usuario administre la configuración de Intune, debe ser administrador global o administrador de servicios de Intune.

Además:

Use https://admin.microsoft.com para asignar una licencia de Intune a su cuenta de usuario.
Actualice el código de la aplicación para autenticarse en el dominio de inquilino de Microsoft Entra del cliente, en lugar de en el suyo propio.

Por ejemplo, supongamos que el dominio de inquilino es contosopartner.onmicrosoft.com y el dominio de inquilino del cliente es northwind.onmicrosoft.com, que actualizaría el código para autenticarse en el inquilino del cliente.

Para hacerlo en una aplicación de C# basada en el ejemplo anterior, cambiaría el valor de la authority variable:
```
string authority = "https://login.microsoftonline.com/common/";
```
a
```
string authority = "https://login.microsoftonline.com/northwind.onmicrosoft.com/";
```

Compartir vía