Jak uzyskać dostęp do interfejsów API usługi Intune w programie Microsoft Graph przy użyciu identyfikatora Entra firmy Microsoft

Artykuł
07/30/2024

Interfejs API programu Microsoft Graph obsługuje teraz usługę Microsoft Intune z określonymi interfejsami API i rolami uprawnień. Interfejs API programu Microsoft Graph używa identyfikatora Entra firmy Microsoft do uwierzytelniania i kontroli dostępu.
Dostęp do interfejsów API usługi Intune w programie Microsoft Graph wymaga:

Identyfikator aplikacji z:
- Uprawnienie do wywoływania identyfikatora Entra firmy Microsoft i interfejsów API programu Microsoft Graph.
- Zakresy uprawnień związane z określonymi zadaniami aplikacji.
Poświadczenia użytkownika z:
- Uprawnienie dostępu do dzierżawy usługi Microsoft Entra skojarzonej z aplikacją.
- Uprawnienia roli wymagane do obsługi zakresów uprawnień aplikacji.
Użytkownik końcowy udziela aplikacji uprawnień do wykonywania zadań aplikacji dla dzierżawy platformy Azure.

Ten artykuł:

Przedstawia sposób rejestrowania aplikacji z dostępem do interfejsu API programu Microsoft Graph i odpowiednich ról uprawnień.
Opisuje role uprawnień interfejsu API usługi Intune.
Zawiera przykłady uwierzytelniania interfejsu API usługi Intune dla języka C# i programu PowerShell.
W tym artykule opisano sposób obsługi wielu dzierżaw.

Aby dowiedzieć się więcej, zobacz:

Rejestrowanie aplikacji w celu korzystania z interfejsu API programu Microsoft Graph

Aby zarejestrować aplikację w celu korzystania z interfejsu API programu Microsoft Graph:

Zaloguj się do centrum administracyjnego usługi Microsoft Intune przy użyciu poświadczeń administracyjnych.

W razie potrzeby możesz użyć:
- Konto administratora dzierżawy.
- Konto użytkownika dzierżawy z włączonym ustawieniem Użytkownicy mogą rejestrować aplikacje .
Wybierz pozycję Wszystkie usługi>M365 Microsoft Entra ID>Rejestracje aplikacjiMicrosoft Entra ID>.
Wybierz pozycję Nowa rejestracja , aby utworzyć nową aplikację, lub wybierz istniejącą aplikację. (Jeśli wybierzesz istniejącą aplikację, pomiń następny krok).
W okienku Rejestrowanie aplikacji określ następujące elementy:
- Nazwa aplikacji (wyświetlana podczas logowania użytkowników).
- Obsługiwany typ konta.
- Wartość identyfikatora URI przekierowania . Ta wartość jest opcją.
  
  Uwaga
  
  Interfejs API programu Azure AD Graph jest w fazie wycofywania. Aby uzyskać więcej informacji, zobacz Aktualizowanie aplikacji w celu używania biblioteki Microsoft Authentication Library (MSAL) i interfejsu API programu Microsoft Graph.
  
  Aby dowiedzieć się więcej, zobacz Scenariusze uwierzytelniania dla identyfikatora Entra firmy Microsoft.
W okienku aplikacji:
1. Zanotuj wartość identyfikatora aplikacji (klienta ).
2. Wybierz pozycję Uprawnienia interfejsu API.
W okienku Uprawnienia interfejsu API wybierz pozycję Dodaj uprawnienie>Interfejsy> API firmyMicrosoft Microsoft Graph. Następnie wybierz typ uprawnień wymaganych przez aplikację.

Wybierz role wymagane dla aplikacji, umieszczając znacznik wyboru po lewej stronie odpowiednich nazw. Aby dowiedzieć się więcej o określonych zakresach uprawnień usługi Intune, zobacz Zakresy uprawnień usługi Intune. Aby dowiedzieć się więcej o innych zakresach uprawnień interfejsu API programu Graph, zobacz Dokumentacja uprawnień programu Microsoft Graph.

Aby uzyskać najlepsze wyniki, wybierz najmniejszą liczbę ról potrzebnych do zaimplementowania aplikacji.

Uprawnienia magazynu danych i raportowania

Po dodaniu aplikacji za pośrednictwem centrum administracyjnego Usługi Microsoft Entra możesz wybrać uprawnienia interfejsu API usługi Intune na podstawie wymagań aplikacji.

get_data_warehouse — użyj tego uprawnienia interfejsu API, aby udzielić dostępu do interfejsu API magazynu danych usługi Intune z usługi Microsoft Intune. Aby uzyskać więcej informacji, zobacz Korzystanie z magazynu danych usługi Microsoft Intune.

Interfejsy API rozwiązania partnerskiego

Podczas dodawania aplikacji za pośrednictwem centrum administracyjnego usługi Microsoft Entra są dostępne następujące uprawnienia interfejsu API usługi Intune:

get_device_compliance — to uprawnienie interfejsu API służy do uzyskiwania informacji o stanie urządzenia i zgodności z usługi Microsoft Intune. To uprawnienie interfejsu API jest używane przez partnerów kontroli dostępu do sieci. Aby uzyskać więcej informacji, zobacz Integracja kontroli dostępu do sieci z usługą Intune.
manage_partner_compliance_policy — to uprawnienie interfejsu API służy do zarządzania zasadami zgodności partnerów w usłudze Microsoft Intune. To uprawnienie interfejsu API umożliwia aplikacji wysyłanie zasad zgodności partnerów i jej przypisania grupy Microsoft Entra do usługi Microsoft Intune bez zalogowanego użytkownika. Jest on używany przez partnerów ds. zgodności urządzeń. Aby uzyskać więcej informacji, zobacz Partnerzy zgodności urządzeń innych firm.
pfx_cert_provider — to uprawnienie interfejsu API służy do wysyłania certyfikatów PFX do usługi Intune dla określonego użytkownika. Usługa Intune dostarcza certyfikat do wszystkich urządzeń zarejestrowanych przez użytkownika. Aby uzyskać więcej informacji, zobacz PFX Import PowerShell (Importowanie programu PowerShell w formacie PFX).
scep_challenge_provider — to uprawnienie interfejsu API służy do wysyłania wyzwań protokołu SCEP do usługi Intune w celu weryfikacji żądania certyfikatu. Jest on używany przez partnerów urzędu certyfikacji. Aby uzyskać więcej informacji, zobacz Urząd certyfikacji partnera.
update_device_attributes — to uprawnienie interfejsu API służy do wysyłania informacji o urządzeniu do usługi Intune od partnerów ds. zgodności urządzeń i ochrony przed zagrożeniami mobilnymi. Aby uzyskać więcej informacji, zobacz Integracja usługi Mobile Threat Defense z usługą Intune i partnerami zgodności urządzeń innych firm.
update_device_health — to uprawnienie interfejsu API służy do wysyłania informacji o kondycji urządzenia i stanie zagrożenia do usługi Intune od partnerów ochrony przed zagrożeniami mobilnymi. Aby uzyskać więcej informacji, zobacz Integracja usługi Mobile Threat Defense z usługą Intune.

Jeśli jesteś partnerem zainteresowanym integracją z usługą Intune przy użyciu tych uprawnień interfejsu API, skontaktuj się z zespołem Microsoft Intelligent Security Association] w celu uzyskania informacji.

Po zakończeniu wybierz pozycję Dodaj uprawnienia , aby zapisać zmiany.

W tym momencie możesz również:

Wybierz, aby udzielić uprawnień dla wszystkich kont dzierżawy do korzystania z aplikacji bez podawania poświadczeń.

W tym celu możesz udzielić uprawnień i zaakceptować monit o potwierdzenie.

Po pierwszym uruchomieniu aplikacji zostanie wyświetlony monit o przyznanie aplikacji uprawnień do wykonywania wybranych ról.
Udostępnij aplikację użytkownikom spoza dzierżawy. (Zwykle jest to wymagane tylko w przypadku partnerów obsługujących wiele dzierżaw/organizacji).

W tym celu:
1. Wybierz pozycję Manifest w okienku aplikacji.
2. Zmień wartość ustawienia na availableToOtherTenantstrue.
3. Zapisz zmiany.

Lista aplikacji

Jeśli podczas żądania listy aplikacji podczas korzystania z interfejsu API programu Graph otrzymujesz dużą ilość danych, może wystąpić błąd 503 Usługa niedostępna. Zalecamy ponowienie próby przy mniejszym rozmiarze strony, takim jak 20 lub mniej elementów.

Zakresy uprawnień usługi Intune

Identyfikator Firmy Microsoft Entra i program Microsoft Graph używają zakresów uprawnień do kontrolowania dostępu do zasobów firmy.

Zakresy uprawnień (nazywane również zakresami OAuth) kontrolują dostęp do określonych jednostek usługi Intune i ich właściwości. W tej sekcji podsumowano zakresy uprawnień dla funkcji interfejsu API usługi Intune.

Aby dowiedzieć się więcej:

Po udzieleniu uprawnień do programu Microsoft Graph można określić następujące zakresy kontroli dostępu do funkcji usługi Intune: Poniższa tabela zawiera podsumowanie zakresów uprawnień interfejsu API usługi Intune. Pierwsza kolumna zawiera nazwę funkcji wyświetlaną w centrum administracyjnym usługi Microsoft Intune , a druga kolumna zawiera nazwę zakresu uprawnień.

Ustawienie Włącz dostęp	Nazwa zakresu
Wykonywanie akcji zdalnych wpływających na użytkownika na urządzeniach usługi Microsoft Intune	DeviceManagementManagedDevices.PrivilegedOperations.All
Odczytywanie i zapisywanie urządzeń usługi Microsoft Intune	DeviceManagementManagedDevices.ReadWrite.All
Odczytywanie urządzeń usługi Microsoft Intune	DeviceManagementManagedDevices.Read.All
Odczyt i zapis ustawień kontroli dostępu opartej na rolach usługi Microsoft Intune	DeviceManagementRBAC.ReadWrite.All
Przeczytaj ustawienia kontroli dostępu opartej na rolach w usłudze Microsoft Intune	DeviceManagementRBAC.Read.All
Odczytywanie i pisanie aplikacji usługi Microsoft Intune	DeviceManagementApps.ReadWrite.All
Odczytywanie aplikacji usługi Microsoft Intune	DeviceManagementApps.Read.All
Odczytywanie i zapisywanie zasad i konfiguracji urządzeń usługi Microsoft Intune	DeviceManagementConfiguration.ReadWrite.All
Przeczytaj artykuł Konfiguracja i zasady dotyczące urządzeń w usłudze Microsoft Intune	DeviceManagementConfiguration.Read.All
Odczyt i zapis konfiguracji usługi Microsoft Intune	DeviceManagementServiceConfig.ReadWrite.All
Przeczytaj konfigurację usługi Microsoft Intune	DeviceManagementServiceConfig.Read.All

Tabela zawiera listę ustawień wyświetlanych w centrum administracyjnym usługi Microsoft Intune. W poniższych sekcjach opisano zakresy w kolejności alfabetycznej.

Obecnie wszystkie zakresy uprawnień usługi Intune wymagają dostępu administratora. Oznacza to, że podczas uruchamiania aplikacji lub skryptów uzyskujących dostęp do zasobów interfejsu API usługi Intune potrzebne są odpowiednie poświadczenia.

DeviceManagementApps.Read.All

Ustawienie Włącz dostęp : odczytywanie aplikacji usługi Microsoft Intune
Zezwala na dostęp do odczytu do następujących właściwości i stanu jednostki:
- Aplikacje klienckie
- Kategorie aplikacji mobilnych
- Zasady ochrony aplikacji
- Konfiguracje aplikacji

DeviceManagementApps.ReadWrite.All

Ustawienie Włącz dostęp : odczytywanie i zapisywanie aplikacji usługi Microsoft Intune
Zezwala na te same operacje co DeviceManagementApps.Read.All
Zezwala również na zmiany w następujących jednostkach:
- Aplikacje klienckie
- Kategorie aplikacji mobilnych
- Zasady ochrony aplikacji
- Konfiguracje aplikacji

DeviceManagementConfiguration.Read.All

Ustawienie Włącz dostęp : przeczytaj konfigurację i zasady urządzenia usługi Microsoft Intune
Zezwala na dostęp do odczytu do następujących właściwości i stanu jednostki:
- Konfiguracja urządzenia
- Zasady zgodności urządzeń
- Komunikaty powiadomień

DeviceManagementConfiguration.ReadWrite.All

Ustawienie Włącz dostęp : odczyt i zapis konfiguracji i zasad urządzeń usługi Microsoft Intune
Zezwala na te same operacje co DeviceManagementConfiguration.Read.All
Aplikacje mogą również tworzyć, przypisywać, usuwać i zmieniać następujące jednostki:
- Konfiguracja urządzenia
- Zasady zgodności urządzeń
- Komunikaty powiadomień

DeviceManagementManagedDevices.PrivilegedOperations.All

Ustawienie Włącz dostęp : wykonywanie akcji zdalnych wpływających na użytkownika na urządzeniach usługi Microsoft Intune
Zezwala na następujące akcje zdalne na zarządzanym urządzeniu:
- Wycofaj
- Wyczyść dane
- Resetowanie/odzyskiwanie kodu dostępu
- Zdalne blokowanie
- Włączanie/wyłączanie trybu utraty
- Czysty komputer
- Ponowny rozruch
- Usuwanie użytkownika z urządzenia udostępnionego

DeviceManagementManagedDevices.Read.All

Ustawienie Włącz dostęp : odczyt urządzeń usługi Microsoft Intune
Zezwala na dostęp do odczytu do następujących właściwości i stanu jednostki:
- Urządzenie zarządzane
- Kategoria urządzenia
- Wykryta aplikacja
- Akcje zdalne
- Informacje o złośliwym oprogramowaniu

DeviceManagementManagedDevices.ReadWrite.All

Ustawienie Włącz dostęp : odczyt i zapis urządzeń usługi Microsoft Intune
Zezwala na te same operacje co DeviceManagementManagedDevices.Read.All
Aplikacje mogą również tworzyć, usuwać i zmieniać następujące jednostki:
- Urządzenie zarządzane
- Kategoria urządzenia
Dozwolone są również następujące akcje zdalne:
- Lokalizowanie urządzeń
- Wyłączanie blokady aktywacji
- Żądanie pomocy zdalnej

DeviceManagementRBAC.Read.All

Ustawienie Włącz dostęp : przeczytaj ustawienia kontroli RBAC usługi Microsoft Intune
Zezwala na dostęp do odczytu do następujących właściwości i stanu jednostki:
- Przypisania ról
- Definicje ról
- Operacje zasobów

DeviceManagementRBAC.ReadWrite.All

Ustawienie Włącz dostęp : odczyt i zapis ustawień kontroli DOSTĘPU w usłudze Microsoft Intune
Zezwala na te same operacje co DeviceManagementRBAC.Read.All
Aplikacje mogą również tworzyć, przypisywać, usuwać i zmieniać następujące jednostki:
- Przypisania ról
- Definicje ról

DeviceManagementServiceConfig.Read.All

Ustawienie Włącz dostęp : przeczytaj konfigurację usługi Microsoft Intune
Zezwala na dostęp do odczytu do następujących właściwości i stanu jednostki:
- Rejestrowanie urządzeń
- Apple Push Notification Certificate
- Apple Device Enrollment Program
- Program zakupów zbiorczych firmy Apple
- Exchange Connector
- Warunki i postanowienia
- Infrastruktura kluczy publicznych w chmurze
- Marki
- Ochrona przed zagrożeniami mobilnymi

DeviceManagementServiceConfig.ReadWrite.All

Ustawienie Włącz dostęp : odczyt i zapis konfiguracji usługi Microsoft Intune
Umożliwia wykonywanie tych samych operacji co DeviceManagementServiceConfig.Read.All_
Aplikacje mogą również skonfigurować następujące funkcje usługi Intune:
- Rejestrowanie urządzeń
- Apple Push Notification Certificate
- Apple Device Enrollment Program
- Program zakupów zbiorczych firmy Apple
- Exchange Connector
- Warunki i postanowienia
- Infrastruktura kluczy publicznych w chmurze
- Marki
- Ochrona przed zagrożeniami mobilnymi

Przykłady uwierzytelniania w usłudze Microsoft Entra

W tej sekcji przedstawiono sposób dołączania identyfikatora Usługi Microsoft Entra do projektów języka C# i programu PowerShell.

W każdym przykładzie należy określić identyfikator aplikacji, który ma co najmniej DeviceManagementManagedDevices.Read.All zakres uprawnień (omówiony wcześniej).

Podczas testowania dowolnego przykładu mogą wystąpić błędy stanu HTTP 403 (Zabronione) podobne do następujących:

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

W takim przypadku sprawdź, czy:

Identyfikator aplikacji został zaktualizowany do identyfikatora autoryzowanego do korzystania z interfejsu API programu Microsoft Graph i zakresu DeviceManagementManagedDevices.Read.All uprawnień.
Poświadczenia dzierżawy obsługują funkcje administracyjne.
Kod jest podobny do wyświetlonych przykładów.

Uwierzytelnianie identyfikatora Entra firmy Microsoft w języku C#

W tym przykładzie pokazano, jak pobrać listę urządzeń skojarzonych z kontem usługi Intune przy użyciu języka C#.

Uwaga

Interfejs API programu Azure AD Graph jest w fazie wycofywania. Aby uzyskać więcej informacji, zobacz Aktualizowanie aplikacji w celu używania biblioteki Microsoft Authentication Library (MSAL) i interfejsu API programu Microsoft Graph.

Uruchom program Visual Studio, a następnie utwórz nowy projekt aplikacji konsolowej Visual C# (.NET Framework).
Wprowadź nazwę projektu i podaj inne szczegóły zgodnie z potrzebami.
Użyj Eksploratora rozwiązań, aby dodać pakiet NuGet msal firmy Microsoft do projektu:
1. Kliknij prawym przyciskiem myszy Eksplorator rozwiązań.
2. Wybierz pozycję Zarządzaj pakietami NuGet...>Przeglądaj.
3. Wybierz, Microsoft.Identity.Client a następnie wybierz pozycję Zainstaluj.

Dodaj następujące instrukcje na początku Program.cs:

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

Dodaj metodę, aby utworzyć nagłówek autoryzacji:

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

Pamiętaj, aby zmienić wartość , aby była zgodna z application_ID wartością przyznaną co najmniej zakres uprawnień DeviceManagementManagedDevices.Read.All , zgodnie z wcześniejszym opisem.

Dodaj metodę pobierania listy urządzeń:

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

Zaktualizuj pozycję Main , aby wywołać element GetMyManagedDevices:

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

Skompiluj i uruchom program.

Po pierwszym uruchomieniu programu powinny zostać wyświetlone dwa monity. Pierwszy żąda poświadczeń, a drugi udziela uprawnień do managedDevices żądania.

Aby uzyskać więcej informacji, oto ukończony program:

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

Uwierzytelnianie identyfikatora Entra firmy Microsoft przy użyciu programu Microsoft Graph PowerShell

Skrypty programu PowerShell mogą używać modułu Programu PowerShell programu Microsoft Graph do uwierzytelniania. Aby dowiedzieć się więcej, zobacz Microsoft Graph PowerShell i przykłady programu PowerShell usługi Intune.

Obsługa wielu dzierżaw i partnerów

Jeśli Twoja organizacja obsługuje organizacje z własnymi dzierżawami usługi Microsoft Entra, możesz zezwolić klientom na korzystanie z aplikacji wraz z ich dzierżawami.

W tym celu:

Sprawdź, czy konto klienta istnieje w docelowej dzierżawie usługi Microsoft Entra.
Sprawdź, czy konto dzierżawy umożliwia użytkownikom rejestrowanie aplikacji (zobacz Ustawienia użytkownika).
Ustanawianie relacji między każdą dzierżawą.

Aby to zrobić, wykonaj jedną z następujących czynności:

a. Użyj Centrum partnerskiego firmy Microsoft , aby zdefiniować relację z klientem i jego adresem e-mail.

b. Zaproś użytkownika, aby został gościem twojej dzierżawy.

Aby zaprosić użytkownika do roli gościa dzierżawy:

Wybierz pozycję Dodaj użytkownika-gościa z panelu Szybkie zadania .
Wprowadź adres e-mail klienta i (opcjonalnie) dodaj spersonalizowaną wiadomość dla zaproszenia.
Wybierz pozycję Zaproś.

Spowoduje to wysłanie zaproszenia do użytkownika.

Aby zaakceptować zaproszenie, użytkownik musi wybrać link Wprowadzenie .

Po ustanowieniu relacji (lub zaakceptowaniu zaproszenia) dodaj konto użytkownika do roli Katalog.

Pamiętaj, aby w razie potrzeby dodać użytkownika do innych ról. Aby na przykład zezwolić użytkownikowi na zarządzanie ustawieniami usługi Intune, musi być administratorem globalnym lub administratorem usługi Intune.

Też:

Użyj polecenia https://admin.microsoft.com , aby przypisać licencję usługi Intune do konta użytkownika.
Zaktualizuj kod aplikacji, aby uwierzytelnić się w domenie dzierżawy microsoft entra klienta, a nie w twojej własnej.

Załóżmy na przykład, że domeną dzierżawy jest contosopartner.onmicrosoft.com domena dzierżawy, a domeną dzierżawy klienta jest northwind.onmicrosoft.com, aby zaktualizować kod w celu uwierzytelnienia w dzierżawie klienta.

Aby to zrobić w aplikacji języka C# na podstawie wcześniejszego przykładu, należy zmienić wartość zmiennej authority :
```
string authority = "https://login.microsoftonline.com/common/";
```
do
```
string authority = "https://login.microsoftonline.com/northwind.onmicrosoft.com/";
```

Udostępnij za pośrednictwem