Cómo usar Azure AD para obtener acceso a las API de Intune en Microsoft Graph

La API Graph microsoft ahora admite Microsoft Intune con API y roles de permisos específicos. La API Graph Microsoft usa Azure Active Directory (Azure AD) para la autenticación y el control de acceso.
El acceso a las API de Intune en Microsoft Graph requiere:

• Un identificador de aplicación con:

  • Permiso para llamar a Azure AD y las API Graph Microsoft.
  • Ámbitos de permisos relevantes para las tareas de aplicación específicas.

• Credenciales de usuario con:

  • Permiso para obtener acceso al Azure AD empresarial asociado a la aplicación.
  • Permisos de rol necesarios para admitir los ámbitos de permisos de aplicación.

• El usuario final para 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 la API de Microsoft Graph y roles de permisos relevantes.

• Describe los roles de permisos de la API de Intune.

• Proporciona ejemplos de autenticación de API de Intune C# y PowerShell.

• Describe cómo admitir varios inquilinos.

Para más información, vea:

• Autorizar el acceso a aplicaciones web mediante OAuth 2.0 y Azure Active Directory
• Introducción a la Azure AD autenticación
• Integración de aplicaciones con Azure Active Directory
• Comprender OAuth 2.0

Registrar aplicaciones para usar la API Graph Microsoft

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

1. Inicie sesión en el centro Microsoft Endpoint Manager administración con credenciales administrativas.

   Según corresponda, puede usar:

   • Cuenta de administrador de inquilinos.
   • Una cuenta de usuario de inquilino con la configuración Usuarios puede registrar aplicaciones habilitadas.

2. Seleccione Todos los servicios > M365 Azure Active Directory > Azure Active Directory registros de > aplicaciones.

   

3. 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).

4. En el panel Registrar una aplicación, especifique lo siguiente:

   • Un nombre para la aplicación (que se muestra cuando los usuarios inician sesión).

   • El tipo de cuenta compatible.

   • Valor uri de redireccionamiento. Este valor es una opción.

     Nota

     Azure Active Directory (Azure AD) authentication library (ADAL) y Azure AD Graph API de autenticación estarán en desuso. Para obtener más información, vea Update your applications to use Microsoft Authentication Library (MSAL) and Microsoft Graph API.

     

     Para obtener más información, vea Escenarios de autenticación para Azure AD.

5. Desde el panel de aplicaciones:

   1. Tenga en cuenta el valor de id. de aplicación (cliente).

   2. Seleccione Permisos de API.

6. En el panel Permisos de api, elija Agregar un permiso Api de > Microsoft > Microsoft Graph. A continuación, seleccione el tipo de permisos que necesita la aplicación.

   Elige los roles necesarios para la aplicación colocando una marca de verificación a la izquierda de los nombres relevantes. 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 Graph de permisos de la API, vea Referencia de permisos Graph microsoft.

   Para obtener los mejores resultados, elija los roles más mínimos necesarios para implementar la aplicación.

Permisos de almacenamiento de datos e informes

Al agregar una aplicación a través del centro Azure Active Directory administración, puede elegir los permisos de la 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, vea Using the Microsoft Intune Data Warehouse.

API de soluciones de partners

Los siguientes permisos de la API de Intune están disponibles al agregar una aplicación a través del centro Azure Active Directory administración:

• get_device_compliance: este permiso de API se usa para obtener información de estado y cumplimiento del dispositivo 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 directivas de cumplimiento de partners con Microsoft Intune. Este permiso de API permite a la aplicación enviar directivas de cumplimiento de partners y su asignación Azure AD grupo a Microsoft Intune sin un usuario que haya iniciado sesión. Lo usan los socios de cumplimiento de dispositivos. Para obtener más información, consulta Partners 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 PFX Import Powershell.
• 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, vea Partner Certification Authority.
• send_data_usage: este permiso de api se usa para desencadenar cambios de directiva para dispositivos basados en umbrales de administración de gastos de telecomunicaciones. Se usa para integraciones de partners de administración de gastos de telecomunicaciones. Para obtener más información, vea Administración de gastos de telecomunicaciones en Intune.
• update_device_attributes: este permiso de api se usa para enviar información del dispositivo a Intune desde socios de cumplimiento de dispositivos y defensa contra amenazas móviles. Para obtener más información, consulte Mobile Threat Defense integration with Intune and Third party device compliance partners.
• update_device_health: este permiso de api se usa para enviar información de estado de amenazas y estado del dispositivo a Intune desde socios de defensa contra amenazas móviles. Para obtener más información, vea Mobile Threat Defense integration with Intune.

Si es un partner interesado en integrarse con Intune con 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 punto, también puede:

• Elige 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.

  Cuando ejecutes la aplicación por primera vez, se te pedirá que concedas permiso a la aplicación para realizar los roles seleccionados.

• Haz que la aplicación esté disponible para los usuarios externos a tu inquilino. (Normalmente, esto solo es necesario para los partners que admiten varios inquilinos u organizaciones).

  Para ello:

  1. Elija Manifiesto en el panel de aplicaciones.

     

  2. Cambie el valor de la availableToOtherTenants configuración a true .

  3. Guarde los cambios.

Ámbitos de permisos de Intune

Azure AD y Microsoft Graph á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 para las características de la API de Intune.

Para obtener más información:

• Azure AD autenticación
• Ámbitos de permisos de aplicació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 tal como se muestra en el centro de administración de Microsoft Endpoint Manager y la segunda columna proporciona el nombre del ámbito de permisos.

La tabla enumera la configuración tal como aparecen en el centro Microsoft Endpoint Manager de administración. 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 necesitas las credenciales correspondientes al ejecutar aplicaciones o scripts que tienen acceso a recursos de la API de Intune.

DeviceManagementApps.Read.All

• Habilitar configuración de Access: leer Microsoft Intune aplicaciones

• 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 Access: leer y escribir Microsoft Intune aplicaciones

• 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 configuración de Access: leer Microsoft Intune configuración y directivas de dispositivos

• 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 configuración de Access: lectura y escritura Microsoft Intune configuración y directivas de dispositivos

• 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 configuración de Access: realizar acciones remotas que afectan al usuario en Microsoft Intune dispositivos

• Permite las siguientes acciones remotas en un dispositivo administrado:

  • Retirar
  • Barrido
  • Restablecer/recuperar código de acceso
  • Bloqueo remoto
  • Habilitar o deshabilitar el modo perdido
  • Pc limpio
  • Reiniciar
  • Eliminar usuario del dispositivo compartido

DeviceManagementManagedDevices.Read.All

• Habilitar configuración de Access: leer Microsoft Intune dispositivos

• 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 Access: leer y escribir Microsoft Intune dispositivos

• 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:

  • Localizar dispositivos
  • Deshabilitar bloqueo de activación
  • Solicitar asistencia remota

DeviceManagementRBAC.Read.All

• Habilitar configuración de Access: leer Microsoft Intune rbac

• 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 configuración de Access: lectura y escritura Microsoft Intune rbac

• 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 configuración de Access: leer Microsoft Intune configuración

• Permite el acceso de lectura a las siguientes propiedades y estado de entidad:

  • Inscripción de dispositivos
  • Certificado de notificación de inserción de Apple
  • Programa de inscripción de dispositivos Apple
  • Programa de compras por volumen de Apple
  • Exchange Conector
  • Términos y Condiciones
  • Administración de gastos de telecomunicaciones
  • PKI en la nube
  • Personalización de marca
  • Mobile Threat Defense

DeviceManagementServiceConfig.ReadWrite.All

• Habilitar configuración de Access: lectura y escritura Microsoft Intune configuración

• 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 de inserción de Apple
  • Programa de inscripción de dispositivos Apple
  • Programa de compras por volumen de Apple
  • Exchange Conector
  • Términos y Condiciones
  • Administración de gastos de telecomunicaciones
  • PKI en la nube
  • Personalización de marca
  • Mobile Threat Defense

Azure AD de autenticación

En esta sección se muestra cómo incorporar Azure AD a los proyectos C# y PowerShell.

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

Al probar cualquiera de los dos 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 sucede, compruebe que:

• Ha actualizado el identificador de la aplicación a uno autorizado para usar la API de Microsoft Graph y el DeviceManagementManagedDevices.Read.All ámbito de permisos.

• Las credenciales de inquilino admiten funciones administrativas.

• El código es similar a los ejemplos mostrados.

Autenticar Azure AD en C#

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

1. Inicie Visual Studio y, a continuación, cree un nuevo proyecto de aplicación de C# visual (.NET Framework).

2. Escriba un nombre para el proyecto y proporcione otros detalles como desee.

   

3. Use el Explorador de soluciones para agregar el paquete de NuGet Microsoft ADAL al proyecto:

   1. Haga clic con el botón secundario en el Explorador de soluciones.
   2. Elija Administrar NuGet paquetes... >Examinar.
   3. Seleccione Microsoft.IdentityModel.Clients.ActiveDirectory y, a continuación, elija Instalar.
   

4. Agregue las siguientes instrucciones a la parte superior de Program.cs:

   using Microsoft.IdentityModel.Clients.ActiveDirectory;
   using System.Net.Http;
   

5. 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 para que coincida con uno concedido al menos application_ID el DeviceManagementManagedDevices.Read.All ámbito de permisos, como se describió anteriormente.

6. 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");
   }
   

7. Actualizar Main para llamar a GetMyManagedDevices:

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

8. Compile y ejecute el programa.

Cuando ejecute el programa por primera vez, debe recibir dos avisos. La primera solicita sus credenciales y la segunda concede permisos para la managedDevices solicitud.

Como referencia, este es el programa completado:

using Microsoft.IdentityModel.Clients.ActiveDirectory;
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 Azure AD (PowerShell)

El siguiente script de PowerShell usa el módulo de PowerShell de AzureAD para la autenticación. Para obtener más información, vea Azure Active Directory PowerShell Version 2 y los ejemplos de PowerShell de Intune.

En este ejemplo, actualice el valor de $clientID para que coincida con un identificador de aplicación válido.

function Get-AuthToken {
    [cmdletbinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        $User
    )

    $userUpn = New-Object "System.Net.Mail.MailAddress" -ArgumentList $User
    $tenant = $userUpn.Host

    Write-Host "Checking for AzureAD module..."

    $AadModule = Get-Module -Name "AzureAD" -ListAvailable
    if ($AadModule -eq $null) {
        Write-Host "AzureAD PowerShell module not found, looking for AzureADPreview"
        $AadModule = Get-Module -Name "AzureADPreview" -ListAvailable
    }

    if ($AadModule -eq $null) {
        write-host
        write-host "AzureAD Powershell module not installed..." -f Red
        write-host "Install by running 'Install-Module AzureAD' or 'Install-Module AzureADPreview' from an elevated PowerShell prompt" -f Yellow
        write-host "Script can't continue..." -f Red
        write-host
        exit
    }

    # Getting path to ActiveDirectory Assemblies
    # If the module count is greater than 1 find the latest version

    if ($AadModule.count -gt 1) {
        $Latest_Version = ($AadModule | select version | Sort-Object)[-1]
        $aadModule = $AadModule | ? { $_.version -eq $Latest_Version.version }
        $adal = Join-Path $AadModule.ModuleBase "Microsoft.IdentityModel.Clients.ActiveDirectory.dll"
        $adalforms = Join-Path $AadModule.ModuleBase "Microsoft.IdentityModel.Clients.ActiveDirectory.Platform.dll"
    }

    else {
        $adal = Join-Path $AadModule.ModuleBase "Microsoft.IdentityModel.Clients.ActiveDirectory.dll"
        $adalforms = Join-Path $AadModule.ModuleBase "Microsoft.IdentityModel.Clients.ActiveDirectory.Platform.dll"
    }

    [System.Reflection.Assembly]::LoadFrom($adal) | Out-Null
    [System.Reflection.Assembly]::LoadFrom($adalforms) | Out-Null

    $clientId = "<Your Application ID>"
    $redirectUri = "urn:ietf:wg:oauth:2.0:oob"
    $resourceAppIdURI = "https://graph.microsoft.com"
    $authority = "https://login.microsoftonline.com/$Tenant"

    try {
        $authContext = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext" -ArgumentList $authority
        # https://msdn.microsoft.com/library/azure/microsoft.identitymodel.clients.activedirectory.promptbehavior.aspx
        # Change the prompt behaviour to force credentials each time: Auto, Always, Never, RefreshSession
        $platformParameters = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.PlatformParameters" -ArgumentList "Auto"
        $userId = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.UserIdentifier" -ArgumentList ($User, "OptionalDisplayableId")
        $authResult = $authContext.AcquireTokenAsync($resourceAppIdURI, $clientId, $redirectUri, $platformParameters, $userId).Result
        # If the accesstoken is valid then create the authentication header
        if ($authResult.AccessToken) {
            # Creating header for Authorization token
            $authHeader = @{
                'Content-Type' = 'application/json'
                'Authorization' = "Bearer " + $authResult.AccessToken
                'ExpiresOn' = $authResult.ExpiresOn
            }
            return $authHeader
        }
        else {
            Write-Host
            Write-Host "Authorization Access Token is null, please re-run authentication..." -ForegroundColor Red
            Write-Host
            break
        }
    }
    catch {
        write-host $_.Exception.Message -f Red
        write-host $_.Exception.ItemName -f Red
        write-host
        break
    }   
}

$authToken = Get-AuthToken -User "<Your AAD Username>"

try {
    $uri = "https://graph.microsoft.com/beta/me/managedDevices"
    Write-Verbose $uri
    (Invoke-RestMethod -Uri $uri –Headers $authToken –Method Get).Value
}
catch {
    $ex = $_.Exception
    $errorResponse = $ex.Response.GetResponseStream()
    $reader = New-Object System.IO.StreamReader($errorResponse)
    $reader.BaseStream.Position = 0
    $reader.DiscardBufferedData()
    $responseBody = $reader.ReadToEnd();
    Write-Host "Response content:`n$responseBody" -f Red
    Write-Error "Request to $Uri failed with HTTP Status $($ex.Response.StatusCode) $($ex.Response.StatusDescription)"
    write-host
    break
}

Admitir varios inquilinos y asociados

Si su organización admite organizaciones con sus propios inquilinos Azure AD, es posible que desee permitir que sus clientes usen la aplicación con sus respectivos inquilinos.

Para ello:

1. Compruebe que la cuenta de cliente existe en el inquilino Azure AD destino.

2. Compruebe que su cuenta de inquilino permite a los usuarios registrar aplicaciones (consulte Configuración de usuario).

3. Establecer una relación entre cada espacio empresarial.

   Para ello, haga lo siguiente:

   a. Use el Centro de partners de Microsoft para definir una relación con su 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 invitado de su inquilino:

1. Elija Agregar un usuario invitado en el panel Tareas rápidas.

   

2. Escriba la dirección de correo electrónico del cliente y ,opcionalmente, agregue un mensaje personalizado para la invitación.

   

3. 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 haya aceptado la invitación), agregue la cuenta de usuario al rol Directorio.

Recuerde agregar el usuario a otros roles según sea necesario. Por ejemplo, para permitir al usuario administrar la configuración de Intune, debe ser un administrador global o un administrador de servicio de Intune.

También:

• Se https://admin.microsoft.com usa para asignar una licencia de Intune a tu cuenta de usuario.

• Actualice el código de la aplicación para autenticarse en el dominio Azure AD inquilino del cliente, en lugar de en el suyo propio.

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

  Para hacerlo en una aplicación 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/";