How to use Microsoft Entra ID to access the Intune APIs in Microsoft Graph

Статия
11/02/2023

The Microsoft Graph API now supports Microsoft Intune with specific APIs and permission roles. The Microsoft Graph API uses Microsoft Entra ID for authentication and access control.
Access to the Intune APIs in Microsoft Graph requires:

An application ID with:
- Permission to call Microsoft Entra ID and the Microsoft Graph APIs.
- Permission scopes relevant to the specific application tasks.
User credentials with:
- Permission to access the Microsoft Entra tenant associated with the application.
- Role permissions required to support the application permission scopes.
The end user to grant permission to the app to perform applications tasks for their Azure tenant.

This article:

Shows how to register an application with access to the Microsoft Graph API and relevant permission roles.
Describes the Intune API permission roles.
Provides Intune API authentication examples for C# and PowerShell.
Describes how to support multiple tenants.

To learn more, see:

Register apps to use the Microsoft Graph API

To register an app to use Microsoft Graph API:

Sign in to the Microsoft Intune admin center using administrative credentials.

As appropriate, you may use:
- The tenant admin account.
- A tenant user account with the Users can register applications setting enabled.
Select All services > M365 Microsoft Entra ID > Microsoft Entra ID > App registrations.
Either choose New registration to create a new application or choose an existing application. (If you choose an existing application, skip the next step.)
In the Register an application pane, specify the following:
- A Name for the application (displayed when users sign in).
- The Supported account type.
- A Redirect URI value. This value is option.
  
  Note
  
  Azure AD Graph API is in its retirement phase. For more information, see Update your applications to use Microsoft Authentication Library (MSAL) and Microsoft Graph API.
  
  To learn more, see Authentication Scenarios for Microsoft Entra ID.
From the application pane:
1. Note the Application (client) ID value.
2. Select API permissions.
From the API permissions pane, choose Add a permission > Microsoft APIs > Microsoft Graph. Then, select the type of permissions your application requires.

Choose the roles required for your app by placing a checkmark to the left of the relevant names. To learn about specific Intune permission scopes, see Intune permission scopes. To learn about other Graph API permission scopes, see Microsoft Graph permissions reference.

For best results, choose the fewest roles needed to implement your application.

Data warehouse and reporting permissions

When you add an application through the Microsoft Entra admin center, you can choose the Intune API permissions based on the requirements of your application.

get_data_warehouse - Use this API permission to grant access to the Intune data warehouse API from Microsoft Intune. For more information, see Using the Microsoft Intune Data Warehouse.

Partner solution APIs

The following Intune API permissions are available when adding an application through the Microsoft Entra admin center:

get_device_compliance - This API permission is used to get device state and compliance information from Microsoft Intune. This API permission is used by Network Access Control partners. For more information, see Network Access Control integration with Intune.
manage_partner_compliance_policy - This API permission is used to manage partner compliance policies with Microsoft Intune. This API permission allows the app to send partner compliance policies and its Microsoft Entra group assignment to Microsoft Intune without a signed-in user. It is used by device compliance partners. For more information, see Third party device compliance partners.
pfx_cert_provider - This API permission is used to send PFX certificates to Intune for a specific user. Intune delivers the certificate to all devices enrolled by the user. For more information, see PFX Import Powershell.
scep_challenge_provider - This API permission is used to send SCEP challenges to Intune for certificate request validation. It is used by Certification Authority partners. For more information, see Partner Certification Authority.
update_device_attributes - This API permission is used to send device information to Intune from device compliance and mobile threat defense partners. For more information, see Mobile Threat Defense integration with Intune and Third party device compliance partners.
update_device_health - This API permission is used to send device health and threat status information to Intune from mobile threat defense partners. For more information, see Mobile Threat Defense integration with Intune.

If you are a partner interested in integrating with Intune using these API permissions, contact the Microsoft Intelligent Security Association] team for information.

When finished, choose Add permissions to save your changes.

At this point, you may also:

Choose to grant permission for all tenant accounts to use the app without providing credentials.

To do so, you can grant permissions and accept the confirmation prompt.

When you run the application for the first time, you're prompted to grant the app permission to perform the selected roles.
Make the app available to users outside your tenant. (This is typically only required for partners supporting multiple tenants/organizations.)

To do so:
1. Choose Manifest from the application pane.
2. Change the value of the availableToOtherTenants setting to true.
3. Save your changes.

App listing

If you receive a large amount of data while requesting your app listing when using Graph API, you may encounter a 503 Service Unavailable error. We recommended that you try again with a smaller page size, such as 20 or fewer elements.

Intune permission scopes

Microsoft Entra ID and Microsoft Graph use permission scopes to control access to corporate resources.

Permission scopes (also called the OAuth scopes) control access to specific Intune entities and their properties. This section summarizes the permission scopes for Intune API features.

To learn more:

When you grant permission to Microsoft Graph, you can specify the following scopes to control access to Intune features: The following table summarizes the Intune API permission scopes. The first column shows the name of the feature as displayed in the Microsoft Intune admin center and the second column provides the permission scope name.

Enable Access setting	Scope name
Perform user-impacting remote actions on Microsoft Intune devices	DeviceManagementManagedDevices.PrivilegedOperations.All
Read and write Microsoft Intune devices	DeviceManagementManagedDevices.ReadWrite.All
Read Microsoft Intune devices	DeviceManagementManagedDevices.Read.All
Read and write Microsoft Intune RBAC settings	DeviceManagementRBAC.ReadWrite.All
Read Microsoft Intune RBAC settings	DeviceManagementRBAC.Read.All
Read and write Microsoft Intune apps	DeviceManagementApps.ReadWrite.All
Read Microsoft Intune apps	DeviceManagementApps.Read.All
Read and write Microsoft Intune Device Configuration and Policies	DeviceManagementConfiguration.ReadWrite.All
Read Microsoft Intune Device Configuration and Policies	DeviceManagementConfiguration.Read.All
Read and write Microsoft Intune configuration	DeviceManagementServiceConfig.ReadWrite.All
Read Microsoft Intune configuration	DeviceManagementServiceConfig.Read.All

The table lists the settings as they appear in the Microsoft Intune admin center. The following sections describe the scopes in alphabetical order.

At this time, all Intune permission scopes require administrator access. This means you need corresponding credentials when running apps or scripts that access Intune API resources.

DeviceManagementApps.Read.All

Enable Access setting: Read Microsoft Intune apps
Permits read access to the following entity properties and status:
- Client Apps
- Mobile App Categories
- App Protection Policies
- App Configurations

DeviceManagementApps.ReadWrite.All

Enable Access setting: Read and write Microsoft Intune apps
Allows the same operations as DeviceManagementApps.Read.All
Also permits changes to the following entities:
- Client Apps
- Mobile App Categories
- App Protection Policies
- App Configurations

DeviceManagementConfiguration.Read.All

Enable Access setting: Read Microsoft Intune device configuration and policies
Permits read access to the following entity properties and status:
- Device Configuration
- Device Compliance Policy
- Notification Messages

DeviceManagementConfiguration.ReadWrite.All

Enable Access setting: Read and write Microsoft Intune device configuration and policies
Allows the same operations as DeviceManagementConfiguration.Read.All
Apps can also create, assign, delete, and change the following entities:
- Device Configuration
- Device Compliance Policy
- Notification Messages

DeviceManagementManagedDevices.PrivilegedOperations.All

Enable Access setting: Perform user-impacting remote actions on Microsoft Intune devices
Permits the following remote actions on a managed device:
- Retire
- Wipe
- Reset/Recover Passcode
- Remote Lock
- Enable/Disable Lost Mode
- Clean PC
- Reboot
- Delete User from Shared Device

DeviceManagementManagedDevices.Read.All

Enable Access setting: Read Microsoft Intune devices
Permits read access to the following entity properties and status:
- Managed Device
- Device Category
- Detected App
- Remote actions
- Malware information

DeviceManagementManagedDevices.ReadWrite.All

Enable Access setting: Read and write Microsoft Intune devices
Allows the same operations as DeviceManagementManagedDevices.Read.All
Apps can also create, delete, and change the following entities:
- Managed Device
- Device Category
The following remote actions are also allowed:
- Locate devices
- Disable Activation Lock
- Request remote assistance

DeviceManagementRBAC.Read.All

Enable Access setting: Read Microsoft Intune RBAC settings
Permits read access to the following entity properties and status:
- Role Assignments
- Role Definitions
- Resource Operations

DeviceManagementRBAC.ReadWrite.All

Enable Access setting: Read and write Microsoft Intune RBAC settings
Allows the same operations as DeviceManagementRBAC.Read.All
Apps can also create, assign, delete, and change the following entities:
- Role Assignments
- Role Definitions

DeviceManagementServiceConfig.Read.All

Enable Access setting: Read Microsoft Intune configuration
Permits read access to the following entity properties and status:
- Device Enrollment
- Apple Push Notification Certificate
- Apple Device Enrollment Program
- Apple Volume Purchase Program
- Exchange Connector
- Terms and Conditions
- Cloud PKI
- Branding
- Mobile Threat Defense

DeviceManagementServiceConfig.ReadWrite.All

Enable Access setting: Read and write Microsoft Intune configuration
Allows the same operations as DeviceManagementServiceConfig.Read.All_
Apps can also configure the following Intune features:
- Device Enrollment
- Apple Push Notification Certificate
- Apple Device Enrollment Program
- Apple Volume Purchase Program
- Exchange Connector
- Terms and Conditions
- Cloud PKI
- Branding
- Mobile Threat Defense

Microsoft Entra authentication examples

This section shows how to incorporate Microsoft Entra ID into your C# and PowerShell projects.

In each example, you'll need to specify an application ID that has at least the DeviceManagementManagedDevices.Read.All permission scope (discussed earlier).

When testing either example, you may receive HTTP status 403 (Forbidden) errors similar to the following:

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

If this happens, verify that:

You've updated the application ID to one authorized to use the Microsoft Graph API and the DeviceManagementManagedDevices.Read.All permission scope.
Your tenant credentials support administrative functions.
Your code is similar to the displayed samples.

Authenticate Microsoft Entra ID in C#

This example shows how to use C# to retrieve a list of devices associated with your Intune account.

Note

Azure AD Graph API is in its retirement phase. For more information, see Update your applications to use Microsoft Authentication Library (MSAL) and Microsoft Graph API.

Start Visual Studio and then create a new Visual C# Console app (.NET Framework) project.
Enter a name for your project and provide other details as desired.
Use the Solution Explorer to add the Microsoft MSAL NuGet package to the project:
1. Right-click the Solution Explorer.
2. Choose Manage NuGet Packages… > Browse.
3. Select Microsoft.Identity.Client and then choose Install.

Add the following statements to the top of Program.cs:

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

Add a method to create the authorization header:

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

Remember to change the value of application_ID to match one granted at least the DeviceManagementManagedDevices.Read.All permission scope, as described earlier.

Add a method to retrieve the list of devices:

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

Update Main to call GetMyManagedDevices:

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

Compile and run your program.

When you first run your program, you should receive two prompts. The first requests your credentials and the second grants permissions for the managedDevices request.

For reference, here's the completed 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");
        }
    }
}

Authenticate Microsoft Entra ID using Microsoft Graph PowerShell

PowerShell scripts can use the Microsoft Graph PowerShell module for authentication. To learn more, see Microsoft Graph PowerShell and the Intune PowerShell examples.

Support multiple tenants and partners

If your organization supports organizations with their own Microsoft Entra tenants, you may want to permit your clients to use your application with their respective tenants.

To do so:

Verify that the client account exists in the target Microsoft Entra tenant.
Verify that your tenant account allows users to register applications (see User settings).
Establish a relationship between each tenant.

To do so, either:

a. Use the Microsoft Partner Center to define a relationship with your client and their email address.

b. Invite the user to become a guest of your tenant.

To invite the user to be a guest of your tenant:

Choose Add a guest user from the Quick tasks panel.
Enter the client's email address and (optionally) add a personalized message for the invite.
Choose Invite.

This sends an invite to the user.

The user needs to choose the Get Started link to accept your invitation.

When the relationship is established (or your invitation has been accepted), add the user account to the Directory role.

Remember to add the user to other roles as needed. For example, to allow the user to manage Intune settings, they need to be at least an Intune Service administrator.

Also:

Use https://admin.microsoft.com to assign an Intune license to your user account.
Update application code to authenticate to the client's Microsoft Entra tenant domain, rather than your own.

For example, suppose your tenant domain is contosopartner.onmicrosoft.com and your client's tenant domain is northwind.onmicrosoft.com, you would update your code to authenticate to your client's tenant.

To do so in a C# application based on the earlier example, you'd change the value of the authority variable:
```
string authority = "https://login.microsoftonline.com/common/";
```
to
```
string authority = "https://login.microsoftonline.com/northwind.onmicrosoft.com/";
```

Споделяне чрез