Come usare Microsoft Entra ID per accedere alle API di Intune in Microsoft Graph

L'API Graph Microsoft ora supporta Microsoft Intune con API e ruoli di autorizzazione specifici. L'API Graph di Microsoft usa Microsoft Entra ID per l'autenticazione e il controllo degli accessi. L'accesso alle API di Intune in Microsoft Graph richiede:

• Un ID applicazione con:

  • Autorizzazione a chiamare Microsoft Entra ID e le API Microsoft Graph.
  • Ambiti di autorizzazione pertinenti per le specifiche attività dell'applicazione.

• Credenziali utente con:

  • Autorizzazione di accesso al tenant di Microsoft Entra associato all'applicazione.
  • Autorizzazioni del ruolo necessarie per supportare gli ambiti di autorizzazione dell'applicazione.

• L'utente finale deve concedere l'autorizzazione all'app per eseguire attività applicative per il tenant di Azure.

Questo articolo:

• Mostra come registrare un'applicazione con accesso all'API Graph Microsoft e ai ruoli di autorizzazione pertinenti.

• Descrive i ruoli di autorizzazione dell'API di Intune.

• Fornisce esempi di autenticazione API di Intune per C# e PowerShell.

• Descrive come supportare più tenant.

Per altre informazioni, vedere:

• Autorizzare l'accesso alle applicazioni Web tramite OAuth 2.0 e Microsoft Entra ID
• Introduzione all'autenticazione di Microsoft Entra
• Integrazione di applicazioni con Microsoft Entra ID
• Informazioni su OAuth 2.0

Registrare le app per l'uso dell'API Graph Microsoft

Per registrare un'app per l'uso dell'API Graph Microsoft:

1. Accedere all'interfaccia di amministrazione di Microsoft Entra utilizzando le credenziali amministrative.

   Se necessario, è possibile utilizzare:

   • Account amministratore tenant.
   • Un account utente tenant con l'impostazione Gli utenti possono registrare le applicazioni abilitata.

2. Nell'interfaccia di amministrazione espandereApplicazionidi identità> e quindi selezionare Registrazioni app.

   

3. Scegliere Nuova registrazione per creare una nuova applicazione o scegliere un'applicazione esistente. Se scegli un'applicazione esistente, ignora il passaggio successivo.

4. Nel riquadro Registra un'applicazione specificare quanto segue:

   • Un nome per l'applicazione (visualizzato quando gli utenti accedono).

   • Il tipo di account supportato.

   • Valore URI di reindirizzamento . Questo valore è facoltativo.

     Nota

     L'API Graph di Azure AD è in fase di ritiro. Per altre informazioni, vedere Aggiornare le applicazioni per l'uso di Libreria di Autenticazione Microsoft (MSAL) e Microsoft API Graph.

     

     Per altre informazioni, vedere Scenari di autenticazione per Microsoft Entra ID.

5. Selezionare Registrati per aggiungere la nuova applicazione.

   Selezionando Registrati, accetti i criteri della piattaforma Microsoft.

6. Dal riquadro dell'applicazione per l'app:

   1. Prendere nota del valore dell'ID applicazione (client ).

   2. Quindi, dal menu di spostamento, seleziona Autorizzazioni API.

7. Dal riquadro delle autorizzazioni API :

   1. Selezionare Aggiungi un'autorizzazione e quindi nella scheda API Microsoft selezionare il riquadro Microsoft Graph .

   2. Selezionare l'opzione Autorizzazioni applicazione per visualizzare tutte le autorizzazioni disponibili e quindi selezionare il tipo di autorizzazioni richieste dall'applicazione.

   3. Scegliere i ruoli necessari per l'app mettendo un segno di spunta a sinistra dei nomi pertinenti. Per informazioni su ambiti di autorizzazione specifici di Intune, vedere Ambiti di autorizzazione di Intune. Per informazioni su altri ambiti di autorizzazione dell'API Graph, vedere Informazioni di riferimento sulle autorizzazioni di Microsoft Graph.

   Per risultati ottimali, scegliere il numero minimo di ruoli necessari per implementare l'applicazione.

Autorizzazioni per data warehouse e creazione di report

Quando si aggiunge un'applicazione tramite l'interfaccia di amministrazione di Microsoft Entra, è possibile scegliere le autorizzazioni API di Intune in base ai requisiti dell'applicazione.

• get_data_warehouse - Usare questa autorizzazione API per concedere l'accesso all'API del data warehouse Intune da Microsoft Intune. Per ulteriori informazioni, vedere Utilizzo del Microsoft Intune Data Warehouse.

API per le soluzioni partner

Le autorizzazioni API di Intune seguenti sono disponibili quando si aggiunge un'applicazione tramite l'interfaccia di amministrazione di Microsoft Entra:

• get_device_compliance - Questa autorizzazione API viene usata per ottenere informazioni sullo stato e sulla conformità del dispositivo da Microsoft Intune. Questa autorizzazione API viene utilizzata dai partner di Controllo di accesso alla rete. Per ulteriori informazioni, vedere Controllo di accesso alla rete integrazione con Intune.
• manage_partner_compliance_policy - Questa autorizzazione API viene usata per gestire i criteri di conformità dei partner con Microsoft Intune. Questa autorizzazione API consente all'app di inviare i criteri di conformità dei partner e l'assegnazione del gruppo Microsoft Entra a Microsoft Intune senza un utente connesso. Viene usato dai partner di conformità dei dispositivi. Per altre informazioni, vedere Partner di terze parti per la conformità dei dispositivi.
• pfx_cert_provider - Questa autorizzazione API viene usata per inviare certificati PFX a Intune per un utente specifico. Intune recapita il certificato a tutti i dispositivi registrati dall'utente. Per altre informazioni, vedere Importazione di PowerShell PFX.
• scep_challenge_provider - Questa autorizzazione API viene usata per inviare test SCEP a Intune per la convalida della richiesta di certificato. Viene utilizzato dai partner dell'Autorità di certificazione. Per ulteriori informazioni, vedere Autorità di certificazione partner.
• update_device_attributes - Questa autorizzazione API viene usata per inviare informazioni sui dispositivi ai Intune dai partner di conformità dei dispositivi e di difesa dalle minacce mobili. Per altre informazioni, vedere Integrazione di Mobile Threat Defense con Intune e partner di conformità dei dispositivi di terze parti.
• update_device_health - Questa autorizzazione API viene usata per inviare informazioni sullo stato di integrità e sulle minacce del dispositivo ai Intune dei partner di difesa dalle minacce mobili. Per ulteriori informazioni, vedere Integrazione di Mobile Threat Defense con Intune.

Se si è un partner interessato all'integrazione con Intune usando queste autorizzazioni API, contattare il team Microsoft Intelligent Security Association] per informazioni.

Al termine, scegliere Aggiungi autorizzazioni per salvare le modifiche.

A questo punto, puoi anche:

• Scegliere di concedere l'autorizzazione a tutti gli account tenant per usare l'app senza fornire le credenziali.

  A questo scopo, è possibile concedere le autorizzazioni e accettare la richiesta di conferma.

  Quando si esegue l'applicazione per la prima volta, viene richiesto di concedere all'app l'autorizzazione per eseguire i ruoli selezionati.

• Rendere l'app disponibile agli utenti esterni al tenant. In genere è necessario solo per i partner che supportano più tenant/organizzazioni.

  A questo scopo:

  1. Scegliere Manifest dal riquadro dell'applicazione.

  2. Modificare il valore dell'impostazione availableToOtherTenants su true.

  3. Salvare le modifiche.

Inserzione app

Se si riceve una grande quantità di dati durante la richiesta dell'elenco di app quando si usa l'API Graph, è possibile che si verifichi un errore 503 Servizio non disponibile. È consigliabile riprovare con dimensioni della pagina più piccole, ad esempio 20 o meno elementi.

Ambiti di autorizzazione di Intune

Microsoft Entra ID e Microsoft Graph usano gli ambiti di autorizzazione per controllare l'accesso alle risorse aziendali.

Gli ambiti di autorizzazione (detti anche ambiti OAuth) controllano l'accesso a entità di Intune specifiche e alle relative proprietà. In questa sezione sono riepilogati gli ambiti delle autorizzazioni per le funzionalità dell'API di Intune.

Ulteriori informazioni:

• Autenticazione di Microsoft Entra
• Ambiti di autorizzazione dell'applicazione

Quando si concede l'autorizzazione a Microsoft Graph, è possibile specificare gli ambiti seguenti per controllare l'accesso alle funzionalità di Intune: Nella tabella seguente sono riepilogati gli ambiti di autorizzazione dell'API di Intune. La prima colonna mostra il nome della funzionalità visualizzato nell'interfaccia di amministrazione di Microsoft Intune e la seconda colonna fornisce il nome dell'ambito di autorizzazione.

Nella tabella sono elencate le impostazioni così come vengono visualizzate nell'interfaccia di amministrazione di Microsoft Intune. Le sezioni seguenti descrivono gli ambiti in ordine alfabetico.

Al momento, tutti gli ambiti di autorizzazione di Intune richiedono l'accesso come amministratore. Questo significa che sono necessarie le credenziali corrispondenti quando si eseguono app o script che accedono alle risorse API di Intune.

DeviceManagementApps.Read.All

• Abilita l'impostazione di accesso: leggi app di Microsoft Intune

• Consente l'accesso in lettura alle proprietà e allo stato dell'entità seguenti:

  • App client
  • Categorie dell'app per dispositivi mobili
  • Criteri di protezione delle app
  • Configurazioni delle app

DeviceManagementApps.ReadWrite.All

• Abilita l'impostazione di accesso: leggere e scrivere app di Microsoft Intune

• Consente le stesse operazioni di DeviceManagementApps.Read.All

• Consente inoltre di apportare modifiche alle entità seguenti:

  • App client
  • Categorie dell'app per dispositivi mobili
  • Criteri di protezione delle app
  • Configurazioni delle app

DeviceManagementConfiguration.Read.All

• Abilita l'impostazione di accesso: leggi Criteri e configurazione dei dispositivi di Microsoft Intune

• Consente l'accesso in lettura alle proprietà e allo stato dell'entità seguenti:

  • Configurazione dispositivo
  • Criteri di conformità dei dispositivi
  • Messaggi di notifica

DeviceManagementConfiguration.ReadWrite.All

• Abilita l'impostazione di accesso: lettura e scrittura di criteri e configurazione dei dispositivi Microsoft Intune

• Consente le stesse operazioni di DeviceManagementConfiguration.Read.All

• Le app possono anche creare, assegnare, eliminare e modificare le entità seguenti:

  • Configurazione dispositivo
  • Criteri di conformità dei dispositivi
  • Messaggi di notifica

DeviceManagementManagedDevices.PrivilegedOperations.All

• Abilita l'impostazione di accesso: esegui azioni remote che influiscono sull'utente sui dispositivi Microsoft Intune

• Consente le azioni remote seguenti in un dispositivo gestito:

  • Ritiro
  • Cancellazione
  • Reimposta/recupera passcode
  • Blocco remoto
  • Abilitare/disabilitare Modalità smarrito
  • Pulisci PC
  • Riavviare
  • Elimina utente dal dispositivo condiviso

DeviceManagementManagedDevices.Read.All

• Abilita l'impostazione di accesso: lettura dispositivi Microsoft Intune

• Consente l'accesso in lettura alle proprietà e allo stato dell'entità seguenti:

  • Dispositivo gestito
  • Categoria dispositivo
  • App rilevata
  • Azioni remote
  • Informazioni sul malware

DeviceManagementManagedDevices.ReadWrite.All

• Abilita l'impostazione di Access: lettura e scrittura su dispositivi Microsoft Intune

• Consente le stesse operazioni di DeviceManagementManagedDevices.Read.All

• Le app possono anche creare, eliminare e modificare le entità seguenti:

  • Dispositivo gestito
  • Categoria dispositivo

• Sono consentite anche le azioni remote seguenti:

  • Individuare i dispositivi
  • Disabilitare il blocco dell’attivazione
  • Richiedi assistenza remota

DeviceManagementRBAC.Read.All

• Abilita l'impostazione di accesso: leggere le impostazioni RBAC di Microsoft Intune

• Consente l'accesso in lettura alle proprietà e allo stato dell'entità seguenti:

  • Assegnazioni di ruolo
  • Definizioni di ruolo
  • Operazioni sulle risorse

DeviceManagementRBAC.ReadWrite.All

• Abilita l'impostazione di accesso: leggere e scrivere le impostazioni RBAC di Microsoft Intune

• Consente le stesse operazioni di DeviceManagementRBAC.Read.All

• Le app possono anche creare, assegnare, eliminare e modificare le entità seguenti:

  • Assegnazioni di ruolo
  • Definizioni di ruolo

DeviceManagementScripts.Read.All

• Abilita l'impostazione di accesso: leggere gli script di Microsoft Intune

• Le app possono visualizzare (leggere) uno script, in particolare:

  • Script della shell del dispositivo
  • Script per l'integrità del dispositivo
  • Script di conformità dei dispositivi
  • Script della shell degli attributi personalizzati del dispositivo
  • Script per la gestione dispositivi

DeviceManagementScripts.ReadWrite.All

• Abilita l'impostazione di accesso: leggere e scrivere script di Microsoft Intune
  Consente le stesse operazioni di DeviceManagementScripts.Read.All

• Le app possono creare, aggiornare o eliminare uno script, in particolare:

  • Script della shell del dispositivo
  • Script per l'integrità del dispositivo
  • Script di conformità dei dispositivi
  • Script della shell degli attributi personalizzati del dispositivo
  • Script per la gestione dispositivi

DeviceManagementServiceConfig.Read.All

• Abilita l'impostazione di accesso: leggi la configurazione di Microsoft Intune

• Consente l'accesso in lettura alle proprietà e allo stato dell'entità seguenti:

  • Registrazione del dispositivo
  • Certificato per le notifiche push Apple
  • Programma di registrazione dei dispositivi Apple
  • Programma di acquisto a volume Apple
  • Connettore di Exchange
  • Termini e condizioni
  • Cloud PKI
  • Personalizzazione
  • Mobile Threat Defense

DeviceManagementServiceConfig.ReadWrite.All

• Abilita l'impostazione di Access: lettura e scrittura della configurazione di Microsoft Intune

• Consente le stesse operazioni di DeviceManagementServiceConfig.Read.All_

• Le app possono configurare anche le funzionalità di Intune seguenti:

  • Registrazione del dispositivo
  • Certificato per le notifiche push Apple
  • Programma di registrazione dei dispositivi Apple
  • Programma di acquisto a volume Apple
  • Connettore di Exchange
  • Termini e condizioni
  • Cloud PKI
  • Personalizzazione
  • Mobile Threat Defense

Esempi di autenticazione di Microsoft Entra

Questa sezione illustra come incorporare Microsoft Entra ID nei progetti C# e PowerShell.

In ogni esempio è necessario specificare un ID applicazione con almeno l'ambito DeviceManagementManagedDevices.Read.All di autorizzazione (discusso in precedenza).

Durante il test di uno dei due esempi, è possibile ricevere errori di stato HTTP 403 (Accesso negato) simili ai seguenti:

{
  "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"
    }
  }
}

In questo caso, verificare che:

• Hai aggiornato l'ID applicazione con uno autorizzato a usare l'API Graph Microsoft e l'ambito di DeviceManagementManagedDevices.Read.All autorizzazione.

• Le credenziali del tenant supportano le funzioni amministrative.

• Il codice è simile agli esempi visualizzati.

Autenticare Microsoft Entra ID in C#

Questo esempio mostra come usare C# per recuperare un elenco di dispositivi associati all'account Intune.

1. Avviare Visual Studio e quindi creare un nuovo progetto app Visual C# Console (.NET Framework).

2. Immettere un nome per il progetto e specificare altri dettagli in base alle esigenze.

   

3. Usare il Esplora soluzioni per aggiungere il pacchetto NuGet Microsoft MSAL al progetto:

   1. Fare clic con il pulsante destro del mouse su Esplora soluzioni.
   2. Scegliere Manage NuGet Packages...>Sfogliare.
   3. Seleziona Microsoft.Identity.Client e quindi scegli Installa.

4. Aggiungere le istruzioni seguenti all'inizio del Program.cs:

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

5. Aggiungere un metodo per creare l'intestazione authorization:

   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();
   

   Ricorda di modificare il valore di in modo che corrisponda a uno a cui è stato concesso almeno l'ambito DeviceManagementManagedDevices.Read.All di application_ID autorizzazione, come descritto in precedenza.

6. Aggiungere un metodo per recuperare l'elenco dei dispositivi:

   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. Aggiorna principale per chiamare GetMyManagedDevices:

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

8. Compila ed esegui il programma.

Quando esegui il programma per la prima volta, dovresti ricevere due richieste. Il primo richiede le credenziali e il secondo concede le autorizzazioni per la managedDevices richiesta.

Per riferimento, ecco il programma completato:

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

Autenticare Microsoft Entra ID utilizzando Microsoft Graph PowerShell

Gli script di PowerShell possono usare il modulo PowerShell di Microsoft Graph per l'autenticazione. Per altre informazioni, vedere Microsoft Graph PowerShell ed esempi di PowerShell di Intune.

Supporto di più tenant e partner

Se l'organizzazione supporta organizzazioni con i propri tenant di Microsoft Entra, è possibile consentire ai client di usare l'applicazione con i rispettivi tenant.

A questo scopo:

1. Verificare che l'account client esista nel tenant di destinazione di Microsoft Entra.

2. Verificare che l'account tenant consenta agli utenti di registrare le applicazioni (vedere Impostazioni utente).

3. Stabilire una relazione tra ogni tenant.

   A tale scopo, è possibile:

   a. Usa il Centro per i partner Microsoft per definire una relazione con il tuo cliente e il suo indirizzo di posta elettronica.

   b. Invitare l'utente a diventare guest del tenant.

Per invitare l'utente a essere guest del tenant:

1. Scegliere Aggiungi un utente guest dal pannello Attività rapide .

2. Immettere l'indirizzo di posta elettronica del cliente e (facoltativamente) aggiungere un messaggio personalizzato per l'invito.

3. Scegliere Invita.

In questo modo viene inviato un invito all'utente.

L'utente deve scegliere il collegamento Inizia per accettare l'invito.

Una volta stabilita la relazione o accettato l'invito, aggiungere l'account utente al ruolo Directory.

Ricordarsi di aggiungere l'utente ad altri ruoli in base alle esigenze. Ad esempio, per consentire all'utente di gestire le impostazioni di Intune, è necessario essere almeno un amministratore del servizio Intune.

Inoltre:

• Consente https://admin.microsoft.com di assegnare una licenza di Intune all'account utente.

• Aggiornare il codice dell'applicazione per eseguire l'autenticazione al dominio tenant di Microsoft Entra del client, anziché al proprio.

  Si supponga, ad esempio, che il dominio del tenant sia contosopartner.onmicrosoft.com e che il dominio del tenant del client sia northwind.onmicrosoft.com, aggiornare il codice per eseguire l'autenticazione nel tenant del client.

  Per farlo in un'applicazione C# basata sull'esempio precedente, è necessario modificare il valore della authority variabile:

  string authority = "https://login.microsoftonline.com/common/";
  

  a

  string authority = "https://login.microsoftonline.com/northwind.onmicrosoft.com/";