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

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

• ID applicazione con:

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

• Credenziali utente con:

  • Autorizzazione per accedere al tenant Microsoft Entra associato all'applicazione.
  • Autorizzazioni dei ruoli necessarie per supportare gli ambiti di autorizzazione dell'applicazione.

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

Questo articolo:

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

• Descrive i ruoli di autorizzazione dell'API Intune.

• Fornisce Intune esempi di autenticazione API 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 Microsoft Entra
• Integrazione di applicazioni con Microsoft Entra ID
• Informazioni su OAuth 2.0

Registrare le app per l'uso di Microsoft API Graph

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

1. Accedere all'interfaccia di amministrazione Microsoft Intune usando le credenziali amministrative.

   In base alle esigenze, è possibile usare:

   • Account amministratore tenant.
   • Un account utente tenant con l'impostazione Utenti può registrare le applicazioni abilitata.

2. Selezionare Tutti i servizi>M365 Microsoft Entra ID>Microsoft Entra ID>Registrazioni app.

   

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

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

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

   • Tipo di account supportato.

   • Valore URI di reindirizzamento . Questo valore è un'opzione.

     Nota

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

     

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

5. Dal riquadro dell'applicazione:

   1. Si noti il valore dell'ID applicazione (client).

   2. Selezionare Autorizzazioni API.

6. Nel riquadro Autorizzazioni API scegliere Aggiungi un'autorizzazione>API> MicrosoftMicrosoft Graph. Selezionare quindi il tipo di autorizzazioni richieste dall'applicazione.

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

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

Autorizzazioni per data warehouse e creazione di report

Quando si aggiunge un'applicazione tramite il Interfaccia di amministrazione di Microsoft Entra, è possibile scegliere le autorizzazioni dell'API 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 altre informazioni, vedere Uso del Microsoft Intune Data Warehouse.

API della soluzione partner

Quando si aggiunge un'applicazione tramite il Interfaccia di amministrazione di Microsoft Entra, sono disponibili le autorizzazioni API Intune seguenti:

• get_device_compliance: questa autorizzazione API viene usata per ottenere informazioni sullo stato del dispositivo e sulla conformità da Microsoft Intune. Questa autorizzazione API viene usata dai partner network Controllo di accesso. Per altre informazioni, vedere Integrazione di Controllo di accesso di rete 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 conformità dei dispositivi di terze parti.
• 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 PFX di PowerShell.
• scep_challenge_provider: questa autorizzazione API viene usata per inviare i problemi SCEP a Intune per la convalida delle richieste di certificato. Viene usato dai partner dell'Autorità di certificazione. Per altre informazioni, vedere Autorità di certificazione partner.
• update_device_attributes: questa autorizzazione API viene usata per inviare informazioni sul dispositivo a Intune dai partner di conformità dei dispositivi e protezione 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 sull'integrità dei dispositivi e sullo stato delle minacce a Intune dai partner di difesa dalle minacce mobili. Per altre informazioni, vedere Integrazione di Mobile Threat Defense con Intune.

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

Al termine, scegliere Aggiungi autorizzazioni per salvare le modifiche.

A questo punto, è anche possibile:

• Scegliere di concedere a tutti gli account tenant l'autorizzazione per l'uso dell'app senza specificare le credenziali.

  A tale 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 per gli utenti esterni al tenant. Questo è in genere necessario solo per i partner che supportano più tenant/organizzazioni.

  A questo scopo:

  1. Scegliere Manifesto nel riquadro dell'applicazione.

     

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

  3. Salvare le modifiche.

Presentazione dell'app

Se si riceve una grande quantità di dati durante la richiesta della presentazione dell'app quando si usa API Graph, potrebbe verificarsi un errore 503 Service Unavailable. È consigliabile riprovare con dimensioni di pagina inferiori, ad esempio 20 o meno elementi.

Intune ambiti di autorizzazione

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à Intune specifiche e alle relative proprietà. Questa sezione riepiloga gli ambiti di autorizzazione per le funzionalità dell'API Intune.

Ulteriori informazioni:

• autenticazione 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: la tabella seguente riepiloga gli ambiti di autorizzazione dell'API Intune. La prima colonna mostra il nome della funzionalità visualizzato nell'interfaccia di amministrazione Microsoft Intune e la seconda colonna specifica il nome dell'ambito delle autorizzazioni.

La tabella elenca le impostazioni visualizzate nell'interfaccia di amministrazione Microsoft Intune. Le sezioni seguenti descrivono gli ambiti in ordine alfabetico.

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

DeviceManagementApps.Read.All

• Abilitare l'impostazione di accesso: Lettura Microsoft Intune app

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

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

DeviceManagementApps.ReadWrite.All

• Abilitare l'impostazione di accesso: App di Microsoft Intune di lettura e scrittura

• Consente le stesse operazioni di DeviceManagementApps.Read.All

• Consente inoltre di modificare le entità seguenti:

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

DeviceManagementConfiguration.Read.All

• Abilitare l'impostazione di accesso: Lettura Microsoft Intune configurazione e criteri del dispositivo

• 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

• Abilitare l'impostazione di accesso: lettura e scrittura Microsoft Intune configurazione e criteri del dispositivo

• 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

• Abilitare l'impostazione di accesso: eseguire azioni remote che influiscono sull'utente nei dispositivi Microsoft Intune

• Consente le azioni remote seguenti in un dispositivo gestito:

  • Ritiro
  • Cancellazione
  • Reimpostare/ripristinare il passcode
  • Blocco remoto
  • Abilitare/disabilitare la modalità smarrita
  • Pulisci PC
  • Riavviare
  • Eliminare l'utente dal dispositivo condiviso

DeviceManagementManagedDevices.Read.All

• Abilitare l'impostazione di accesso: Lettura Microsoft Intune dispositivi

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

  • Dispositivo gestito
  • Categoria di dispositivi
  • App rilevata
  • Azioni remote
  • Informazioni sul malware

DeviceManagementManagedDevices.ReadWrite.All

• Abilitare l'impostazione di accesso: Dispositivi di Microsoft Intune di lettura e scrittura

• Consente le stesse operazioni di DeviceManagementManagedDevices.Read.All

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

  • Dispositivo gestito
  • Categoria di dispositivi

• Sono consentite anche le azioni remote seguenti:

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

DeviceManagementRBAC.Read.All

• Abilitare l'impostazione di accesso: impostazioni di controllo degli accessi in base al ruolo di lettura Microsoft Intune

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

  • Assegnazioni di ruolo
  • Definizioni di ruolo
  • Operazioni delle risorse

DeviceManagementRBAC.ReadWrite.All

• Abilitare l'impostazione di accesso: impostazioni di lettura e scrittura Microsoft Intune controllo degli accessi in base al ruolo

• 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

DeviceManagementServiceConfig.Read.All

• Abilitare l'impostazione di accesso: Configurazione di lettura Microsoft Intune

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

  • Registrazione del dispositivo
  • Certificato di notifica push Apple
  • Apple Device Enrollment Program
  • Apple Volume Purchase Program
  • Exchange Connector
  • Termini e condizioni
  • Cloud PKI
  • Personalizzazione
  • Mobile Threat Defense

DeviceManagementServiceConfig.ReadWrite.All

• Abilitare l'impostazione di accesso: configurazione di Microsoft Intune di lettura e scrittura

• Consente le stesse operazioni di DeviceManagementServiceConfig.Read.All_

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

  • Registrazione del dispositivo
  • Certificato di notifica push Apple
  • Apple Device Enrollment Program
  • Apple Volume Purchase Program
  • Exchange Connector
  • Termini e condizioni
  • Cloud PKI
  • Personalizzazione
  • Mobile Threat Defense

esempi di autenticazione 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 (descritto in precedenza).

Durante il test di uno dei due esempi, è possibile che vengano visualizzati errori di stato HTTP 403 (non consentiti) 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:

• L'ID applicazione è stato aggiornato a uno autorizzato a usare microsoft API Graph e l'ambito delle DeviceManagementManagedDevices.Read.All autorizzazioni.

• Le credenziali del tenant supportano le funzioni amministrative.

• Il codice è simile agli esempi visualizzati.

Autenticare Microsoft Entra ID in C#

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

1. Avviare Visual Studio e quindi creare un nuovo progetto di app Console Visual C# (.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 sul Esplora soluzioni.
   2. Scegliere Gestisci pacchetti NuGet...>Sfoglia.
   3. Selezionare Microsoft.Identity.Client e quindi scegliere Installa.

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

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

5. Aggiungere un metodo per creare l'intestazione di autorizzazione:

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

   Ricordarsi di modificare il valore di application_ID in modo che corrisponda a uno concesso almeno all'ambito di DeviceManagementManagedDevices.Read.All autorizzazione, come descritto in precedenza.

6. Aggiungere un metodo per recuperare l'elenco di 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. Aggiornare Main per chiamare GetMyManagedDevices:

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

8. Compilare ed eseguire il programma.

Quando si esegue il programma per la prima volta, si riceveranno due richieste. La prima richiede le credenziali e la seconda 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 con 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 e gli esempi Intune PowerShell.

Supporto di più tenant e partner

Se l'organizzazione supporta le organizzazioni con i propri tenant 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 Microsoft Entra di destinazione.

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, eseguire le operazioni seguenti:

   a. Usare il Centro per i partner Microsoft per definire una relazione con il client e il relativo indirizzo di posta elettronica.

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

Per invitare l'utente a essere un guest del tenant:

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

   

2. Immettere l'indirizzo di posta elettronica del client 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 Get Started per accettare l'invito.

Quando viene stabilita la relazione (o l'invito è stato accettato), 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 Intune, deve essere almeno un amministratore del servizio Intune.

Anche:

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

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

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

  A tale scopo, 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/";