Como usar Microsoft Entra ID para acessar as APIs do Intune no Microsoft Graph

Artigo
12/21/2023

O Microsoft API do Graph agora dá suporte a Microsoft Intune com APIs e funções de permissão específicas. O Microsoft API do Graph usa Microsoft Entra ID para controle de autenticação e acesso.
O acesso às APIs do Intune no Microsoft Graph requer:

Uma ID de aplicativo com:
- Permissão para chamar Microsoft Entra ID e as APIs do Microsoft Graph.
- Escopos de permissões relevantes para as tarefas de aplicativo específicas.
Credenciais do usuário com:
- Permissão para acessar o locatário Microsoft Entra associado ao aplicativo.
- Permissões de função necessárias para dar suporte aos escopos de permissões do aplicativo.
O usuário final a conceder permissão ao aplicativo para executar tarefas de aplicativos para seu locatário do Azure.

Este artigo:

Mostra como registrar um aplicativo com acesso às funções de permissão do Microsoft API do Graph e relevantes.
Descreve as funções de permissão da API do Intune.
Fornece exemplos de autenticação de API do Intune para C# e PowerShell.
Descreve como dar suporte a vários locatários.

Para saber mais, confira:

Registrar aplicativos para usar a API do Microsoft Graph

Para registrar um aplicativo para usar a API do Microsoft Graph:

Entre no centro de administração Microsoft Intune usando credenciais administrativas.

Conforme apropriado, você poderá usar:
- A conta do administrador de locatários.
- Uma conta de usuário de locatário com os Usuários pode registrar a configuração de aplicativos habilitada.
Selecione Todos os serviços>M365 Microsoft Entra ID>Microsoft Entra ID>Registros de aplicativo.
Escolha Novo registro para criar um aplicativo ou escolha um aplicativo existente. (Se você escolher um aplicativo existente, ignore a próxima etapa.)
No painel Registrar um aplicativo , especifique o seguinte:
- Um Nome para o aplicativo (exibido quando os usuários entrarem).
- O tipo de conta com suporte.
- Um valor de URI de redirecionamento . Esse valor é a opção.
  
  Observação
  
  Azure AD API do Graph está em sua fase de aposentadoria. Para obter mais informações, consulte Atualizar seus aplicativos para usar a Biblioteca de Autenticação da Microsoft (MSAL) e a API do Microsoft Graph .
  
  Para saber mais, confira Cenários de Autenticação para Microsoft Entra ID.
No painel do aplicativo:
1. Tome nota do valor da ID do aplicativo (cliente).
2. Selecione Permissões de API.
No painel Permissões de API , escolha Adicionar uma permissão>Microsoft APIs>Microsoft Graph. Em seguida, selecione o tipo de permissões necessárias pelo aplicativo.

Escolha as funções necessárias para seu aplicativo colocando uma marca de seleção à esquerda dos nomes relevantes. Para saber mais sobre escopos de permissão específicos do Intune, consulte Escopos de permissão do Intune. Para saber mais sobre outros escopos de permissão API do Graph, consulte Referência de permissões do Microsoft Graph.

Para obter melhores resultados, escolha o menor número de funções necessárias para implementar o aplicativo.

Permissões de data warehouse e relatórios

Ao adicionar um aplicativo por meio do centro de administração do Microsoft Entra, você pode escolher as permissões de API do Intune com base nos requisitos do seu aplicativo.

get_data_warehouse – use essa permissão de API para conceder acesso à API do data warehouse do Intune de Microsoft Intune. Para obter mais informações, consulte Usando o Microsoft Intune Data Warehouse.

APIs de solução de parceiro

As seguintes permissões de API do Intune estão disponíveis ao adicionar um aplicativo por meio do centro de administração do Microsoft Entra:

get_device_compliance - Essa permissão de API é usada para obter informações de estado e conformidade do dispositivo de Microsoft Intune. Essa permissão de API é usada por parceiros de Controle de Acesso de rede. Para obter mais informações, consulte Integração de Controle de Acesso de rede com o Intune.
manage_partner_compliance_policy - Essa permissão de API é usada para gerenciar políticas de conformidade de parceiros com Microsoft Intune. Essa permissão de API permite que o aplicativo envie políticas de conformidade de parceiro e sua atribuição de grupo Microsoft Entra para Microsoft Intune sem um usuário conectado. Ele é usado por parceiros de conformidade do dispositivo. Para obter mais informações, consulte Parceiros de conformidade de dispositivo de terceiros.
pfx_cert_provider - Essa permissão de API é usada para enviar certificados PFX ao Intune para um usuário específico. O Intune entrega o certificado a todos os dispositivos registrados pelo usuário. Para obter mais informações, consulte PFX Import Powershell.
scep_challenge_provider – Essa permissão de API é usada para enviar desafios de SCEP ao Intune para validação de solicitação de certificado. Ele é usado por parceiros da Autoridade de Certificação. Para obter mais informações, consulte Autoridade de Certificação de Parceiros.
update_device_attributes - Essa permissão de API é usada para enviar informações do dispositivo ao Intune por meio da conformidade do dispositivo e dos parceiros de defesa contra ameaças móveis. Para obter mais informações, confira Integração da Defesa contra Ameaças Móveis com parceiros de conformidade de dispositivos do Intune e de terceiros.
update_device_health - Essa permissão de API é usada para enviar informações de status de integridade e ameaças do dispositivo ao Intune de parceiros de defesa contra ameaças móveis. Para obter mais informações, confira Integração da Defesa contra Ameaças Móveis ao Intune.

Se você for um parceiro interessado em integrar-se ao Intune usando essas permissões de API, entre em contato com a equipe da Microsoft Intelligent Security Association] para obter informações.

Quando terminar, escolha Adicionar permissões para salvar suas alterações.

Neste ponto, você também pode:

Escolha conceder permissão para que todas as contas de locatário usem o aplicativo sem fornecer credenciais.

Para fazer isso, você pode conceder permissões e aceitar o prompt de confirmação.

Ao executar o aplicativo pela primeira vez, você será solicitado a conceder a permissão do aplicativo para executar as funções selecionadas.
Disponibilize o aplicativo para usuários fora do locatário. (Normalmente, isso é necessário apenas para parceiros que dão suporte a vários locatários/organizações.)

Para fazer isso:
1. Escolha Manifesto no painel do aplicativo.
2. Altere o valor da availableToOtherTenants configuração para true.
3. Salve suas alterações.

Listagem de aplicativos

Se você receber uma grande quantidade de dados ao solicitar a listagem do aplicativo ao usar API do Graph, poderá encontrar um erro 503 do Serviço Indisponível. Recomendamos que você tente novamente com um tamanho de página menor, como 20 ou menos elementos.

Escopos de permissão do Intune

Microsoft Entra ID e o Microsoft Graph usam escopos de permissão para controlar o acesso a recursos corporativos.

Escopos de permissão (também chamados de escopos OAuth) controlam o acesso a entidades específicas do Intune e suas propriedades. Esta seção resume os escopos de permissão para recursos de API do Intune.

Para saber mais:

Ao conceder permissão ao Microsoft Graph, você pode especificar os seguintes escopos para controlar o acesso aos recursos do Intune: a tabela a seguir resume os escopos de permissão da API do Intune. A primeira coluna mostra o nome do recurso exibido no centro de administração Microsoft Intune e a segunda coluna fornece o nome do escopo de permissão.

Habilitar a configuração de acesso	Nome do escopo
Executar ações remotas de impacto no usuário nos dispositivos do Microsoft Intune	DeviceManagementManagedDevices.PrivilegedOperations.All
Ler e registrar dispositivos do Microsoft Intune	DeviceManagementManagedDevices.ReadWrite.All
Ler dispositivos do Microsoft Intune	DeviceManagementManagedDevices.Read.All
Ler e registrar as configurações RBAC do Microsoft Intune	DeviceManagementRBAC.ReadWrite.All
Ler as configurações RBAC (Controle de Acesso com Base em Função) do Microsoft Intune	DeviceManagementRBAC.Read.All
Ler e registrar os aplicativos do Microsoft Intune	DeviceManagementApps.ReadWrite.All
Ler aplicativos do Microsoft Intune	DeviceManagementApps.Read.All
Ler e gravar Microsoft Intune Configuração e Políticas do Dispositivo	DeviceManagementConfiguration.ReadWrite.All
Ler Microsoft Intune configuração e políticas do dispositivo	DeviceManagementConfiguration.Read.All
Ler e registrar o Microsoft Intune	DeviceManagementServiceConfig.ReadWrite.All
Configuração de leitura Microsoft Intune	DeviceManagementServiceConfig.Read.All

A tabela lista as configurações conforme elas aparecem no centro de administração Microsoft Intune. As seções a seguir descrevem os escopos em ordem alfabética.

Neste momento, todos os escopos de permissão do Intune exigem acesso do administrador. Isso significa que você precisa de credenciais correspondentes ao executar aplicativos ou scripts que acessam recursos da API do Intune.

DeviceManagementApps.Read.All

Habilitar a configuração de acesso: ler aplicativos Microsoft Intune
Permite acesso de leitura às seguintes propriedades da entidade e status:
- Aplicativos cliente
- Categorias de Aplicativo Móvel
- Políticas de Proteção de Aplicativo
- Configurações do aplicativo

DeviceManagementApps.ReadWrite.All

Habilitar a configuração de acesso: ler e gravar aplicativos Microsoft Intune
Permite as mesmas operações que DeviceManagementApps.Read.All
Também permite alterações nas seguintes entidades:
- Aplicativos cliente
- Categorias de Aplicativo Móvel
- Políticas de Proteção de Aplicativo
- Configurações do aplicativo

DeviceManagementConfiguration.Read.All

Habilitar a configuração de acesso: ler Microsoft Intune configuração e políticas do dispositivo
Permite acesso de leitura às seguintes propriedades da entidade e status:
- Configuração do dispositivo
- Política de Conformidade do Dispositivo
- Mensagens de Notificação

DeviceManagementConfiguration.ReadWrite.All

Habilitar a configuração de acesso: ler e gravar Microsoft Intune configuração e políticas do dispositivo
Permite as mesmas operações que DeviceManagementConfiguration.Read.All
Os aplicativos também podem criar, atribuir, excluir e alterar as seguintes entidades:
- Configuração do dispositivo
- Política de Conformidade do Dispositivo
- Mensagens de Notificação

DeviceManagementManagedDevices.PrivilegedOperations.All

Habilitar a configuração de acesso: executar ações remotas que afetam o usuário em dispositivos Microsoft Intune
Permite as seguintes ações remotas em um dispositivo gerenciado:
- Desativar
- Revelar
- Redefinir/Recuperar Senha
- Bloqueio remoto
- Habilitar/desabilitar o modo perdido
- Limpar computador
- Reiniciar
- Excluir usuário do dispositivo compartilhado

DeviceManagementManagedDevices.Read.All

Habilitar a configuração de acesso: ler dispositivos Microsoft Intune
Permite acesso de leitura às seguintes propriedades da entidade e status:
- Dispositivo Gerenciado
- Categoria do dispositivo
- Aplicativo Detectado
- Ações remotas
- Informações sobre malware

DeviceManagementManagedDevices.ReadWrite.All

Habilitar a configuração de acesso: dispositivos de Microsoft Intune de leitura e gravação
Permite as mesmas operações que DeviceManagementManagedDevices.Read.All
Os aplicativos também podem criar, excluir e alterar as seguintes entidades:
- Dispositivo Gerenciado
- Categoria do dispositivo
As seguintes ações remotas também são permitidas:
- Localizar dispositivos
- Desabilitar bloqueio de ativação
- Solicitar assistência remota

DeviceManagementRBAC.Read.All

Habilitar a configuração de acesso: ler Microsoft Intune configurações do RBAC
Permite acesso de leitura às seguintes propriedades da entidade e status:
- Atribuições de função
- Definições de função
- Operações de recurso

DeviceManagementRBAC.ReadWrite.All

Habilitar a configuração de acesso: leitura e gravação Microsoft Intune configurações do RBAC
Permite as mesmas operações que DeviceManagementRBAC.Read.All
Os aplicativos também podem criar, atribuir, excluir e alterar as seguintes entidades:
- Atribuições de função
- Definições de função

DeviceManagementServiceConfig.Read.All

Habilitar a configuração de Acesso: Leitura Microsoft Intune configuração
Permite acesso de leitura às seguintes propriedades da entidade e status:
- Registro de Dispositivo
- Certificado de notificação por push da Apple
- Programa de Registro de Dispositivos Apple
- Programa de Compra de Volume da Apple
- Conector do Exchange
- Termos e condições
- PKI em nuvem
- Identidade Visual
- Defesa contra Ameaças Móveis

DeviceManagementServiceConfig.ReadWrite.All

Habilitar a configuração de acesso: configuração de Microsoft Intune de leitura e gravação
Permite as mesmas operações que DeviceManagementServiceConfig.Read.All_
Os aplicativos também podem configurar os seguintes recursos do Intune:
- Registro de Dispositivo
- Certificado de notificação por push da Apple
- Programa de Registro de Dispositivos Apple
- Programa de Compra de Volume da Apple
- Conector do Exchange
- Termos e condições
- PKI em nuvem
- Identidade Visual
- Defesa contra Ameaças Móveis

Microsoft Entra exemplos de autenticação

Esta seção mostra como incorporar Microsoft Entra ID em seus projetos do C# e do PowerShell.

Em cada exemplo, você precisará especificar uma ID do aplicativo que tenha pelo menos o escopo de DeviceManagementManagedDevices.Read.All permissão (discutido anteriormente).

Ao testar qualquer exemplo, você pode receber erros HTTP status 403 (Proibido) semelhantes aos seguintes:

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

Se isso acontecer, verifique se:

Você atualizou a ID do aplicativo para uma autorizada a usar o microsoft API do Graph e o escopo de DeviceManagementManagedDevices.Read.All permissão.
Suas credenciais de locatário dão suporte a funções administrativas.
Seu código é semelhante aos exemplos exibidos.

Autenticar Microsoft Entra ID em C#

Este exemplo mostra como usar o C# para recuperar uma lista de dispositivos associados à sua conta do Intune.

Observação

Azure AD API do Graph está em sua fase de aposentadoria. Para obter mais informações, consulte Atualizar seus aplicativos para usar a Biblioteca de Autenticação da Microsoft (MSAL) e a API do Microsoft Graph .

Inicie o Visual Studio e crie um novo projeto de aplicativo de console do Visual C# (.NET Framework).
Insira um nome para seu projeto e forneça outros detalhes conforme desejado.
Use o Gerenciador de Soluções para adicionar o pacote NuGet do Microsoft MSAL ao projeto:
1. Clique com o botão direito do mouse no Gerenciador de Soluções.
2. Escolha Gerenciar Pacotes NuGet...>Navegue.
3. Selecione Microsoft.Identity.Client e escolha Instalar.
Adicione as seguintes instruções à parte superior do Program.cs:
```
using Microsoft.Identity.Client;
using System.Net.Http;
```

Adicione um método para criar o cabeçalho de autorização:

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

Lembre-se de alterar o valor de application_ID para corresponder a um concedido pelo menos o escopo de DeviceManagementManagedDevices.Read.All permissão, conforme descrito anteriormente.

Adicione um método para recuperar a lista de dispositivos:

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

Atualizar Main para chamar GetMyManagedDevices:

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

Compile e execute seu programa.

Ao executar seu programa pela primeira vez, você deve receber dois prompts. O primeiro solicita suas credenciais e o segundo concede permissões para a solicitação managedDevices .

Para referência, aqui está o programa concluído:

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

Autenticar Microsoft Entra ID usando o Microsoft Graph PowerShell

Os scripts do PowerShell podem usar o módulo do Microsoft Graph PowerShell para autenticação. Para saber mais, consulte o Microsoft Graph PowerShell e os exemplos do Intune PowerShell.

Suporte a vários locatários e parceiros

Se sua organização dá suporte a organizações com seus próprios locatários Microsoft Entra, talvez você queira permitir que seus clientes usem seu aplicativo com seus respectivos locatários.

Para fazer isso:

Verifique se a conta do cliente existe no locatário de Microsoft Entra de destino.
Verifique se sua conta de locatário permite que os usuários registrem aplicativos (consulte Configurações do usuário).
Estabeleça uma relação entre cada locatário.

Para fazer isso, também:

a. Use o Microsoft Partner Center para definir uma relação com seu cliente e seu endereço de email.

b. Convide o usuário para se tornar um convidado do seu locatário.

Para convidar o usuário para ser um convidado do seu locatário:

Escolha Adicionar um usuário convidado no painel Tarefas rápidas .
Insira o endereço de email do cliente e (opcionalmente) adicione uma mensagem personalizada para o convite.
Escolha Convidar.

Isso envia um convite para o usuário.

O usuário precisa escolher o link Introdução para aceitar o convite.

Quando a relação for estabelecida (ou o convite tiver sido aceito), adicione a conta de usuário à função Diretório.

Lembre-se de adicionar o usuário a outras funções conforme necessário. Por exemplo, para permitir que o usuário gerencie as configurações do Intune, ele precisa ser um administrador global ou um administrador do Serviço do Intune.

Também:

Use https://admin.microsoft.com para atribuir uma licença do Intune à sua conta de usuário.
Atualize o código do aplicativo para autenticar no domínio de locatário Microsoft Entra do cliente, em vez do seu.

Por exemplo, suponha que seu domínio de locatário seja contosopartner.onmicrosoft.com e o domínio de locatário do cliente seja northwind.onmicrosoft.com, você atualizaria seu código para autenticar o locatário do seu cliente.

Para fazer isso em um aplicativo C# com base no exemplo anterior, você alteraria o valor da authority variável:
```
string authority = "https://login.microsoftonline.com/common/";
```
para
```
string authority = "https://login.microsoftonline.com/northwind.onmicrosoft.com/";
```

Compartilhar via