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

Articolo
12/21/2023

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 di 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 di Intune.
Fornisce esempi di autenticazione API di Intune per C# e PowerShell.
Descrive come supportare più tenant.

Per altre informazioni, vedere:

Registrare le app per l'uso di Microsoft API Graph

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

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.
Selezionare Tutti i servizi>M365 Microsoft Entra ID>Microsoft Entra ID>Registrazioni app.
Scegliere Nuova registrazione per creare una nuova applicazione o scegliere un'applicazione esistente. Se si sceglie un'applicazione esistente, ignorare il passaggio successivo.
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.
Dal riquadro dell'applicazione:
1. Si noti il valore dell'ID applicazione (client).
2. Selezionare Autorizzazioni API.
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 sugli ambiti di autorizzazione specifici di Intune, vedere Ambiti di autorizzazione di Intune. 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 di Intune in base ai requisiti dell'applicazione.

get_data_warehouse: usare questa autorizzazione API per concedere l'accesso all'API del data warehouse di Intune da Microsoft Intune. Per altre informazioni, vedere Uso del Microsoft Intune Data Warehouse.

API della soluzione partner

Quando si aggiunge un'applicazione tramite l'Interfaccia di amministrazione di Microsoft Entra, sono disponibili le autorizzazioni api di 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 Network Controllo di accesso integration with Intune (Integrazione di network Controllo di accesso 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 della richiesta 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 da 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 sullo stato di integrità dei dispositivi e minacce a Intune da 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 usando 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.

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

Ulteriori informazioni:

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 di 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.

Abilitare l'impostazione di accesso	Nome ambito
Eseguire azioni remote che influiscono sull'utente nei dispositivi Microsoft Intune	DeviceManagementManagedDevices.PrivilegedOperations.All
Lettura e scrittura di dispositivi Microsoft Intune	DeviceManagementManagedDevices.ReadWrite.All
Leggere Microsoft Intune dispositivi	DeviceManagementManagedDevices.Read.All
Lettura e scrittura Microsoft Intune impostazioni del controllo degli accessi in base al ruolo	DeviceManagementRBAC.ReadWrite.All
Leggere Microsoft Intune impostazioni del controllo degli accessi in base al ruolo	DeviceManagementRBAC.Read.All
Leggere e scrivere app Microsoft Intune	DeviceManagementApps.ReadWrite.All
Leggere le app Microsoft Intune	DeviceManagementApps.Read.All
Lettura e scrittura Microsoft Intune Configurazione e criteri del dispositivo	DeviceManagementConfiguration.ReadWrite.All
Leggere Microsoft Intune Configurazione e criteri del dispositivo	DeviceManagementConfiguration.Read.All
Lettura e scrittura della configurazione Microsoft Intune	DeviceManagementServiceConfig.ReadWrite.All
Leggere Microsoft Intune configurazione	DeviceManagementServiceConfig.Read.All

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 di Intune richiedono l'accesso amministratore. Ciò significa che sono necessarie credenziali corrispondenti quando si eseguono app o script che accedono alle risorse dell'API di 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 di Intune.

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.

Avviare Visual Studio e quindi creare un nuovo progetto di app Console Visual C# (.NET Framework).
Immettere un nome per il progetto e specificare altri dettagli in base alle esigenze.
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.
Aggiungere le istruzioni seguenti all'inizio di Program.cs:
```
using Microsoft.Identity.Client;
using System.Net.Http;
```

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.

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

Aggiornare Main per chiamare GetMyManagedDevices:

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

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 di PowerShell di Intune.

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:

Verificare che l'account client esista nel tenant di Microsoft Entra di destinazione.
Verificare che l'account tenant consenta agli utenti di registrare le applicazioni (vedere Impostazioni utente).
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:

Scegliere Aggiungi un utente guest nel pannello Attività rapide .
Immettere l'indirizzo di posta elettronica del client e (facoltativamente) aggiungere un messaggio personalizzato per l'invito.
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 di Intune, deve essere un amministratore globale o un amministratore del servizio Intune.

Anche:

Usare https://admin.microsoft.com per assegnare una licenza di 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/";
```