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

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

• Uma ID de aplicativo com:

  • Permissão para chamar o 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 do 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 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 à API do Graph Microsoft e às funções de permissão 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:

• Autorizar o acesso a aplicativos Web usando o OAuth 2.0 e o Microsoft Entra ID
• Introdução à autenticação do Microsoft Entra
• Integrando aplicativos com o Microsoft Entra ID
• Entender o OAuth 2.0

Registrar aplicativos para usar a API do Microsoft Graph

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

1. Entre no centro de administração do Microsoft Entra usando credenciais de administrativas.

   Conforme apropriado, você poderá usar:

   • A conta do administrador de locatários.
   • Uma conta de usuário de locatário com a configuração Usuários podem registrar aplicativos habilitada.

2. No centro de administração, expanda Aplicativos de identidade> e selecione Registros de aplicativo.

   

3. Escolha Novo registro para criar um aplicativo ou escolha um aplicativo existente. (Se você escolher um aplicativo existente, pule a próxima etapa.)

4. No painel Registrar um aplicativo , especifique o seguinte:

   • Um Nome para o aplicativo (exibido quando os usuários entram).

   • O tipo de conta com suporte.

   • Um valor de URI de redirecionamento . Esse valor é opcional.

     Observação

     Azure AD API do Graph está em 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, consulte Cenários de autenticação para o Microsoft Entra ID.

5. Selecione Registrar para adicionar seu novo aplicativo.

   Ao selecionar Registrar, você concorda com as Políticas da Plataforma Microsoft.

6. No painel de aplicativos do seu aplicativo:

   1. Tome nota do valor da ID do aplicativo (cliente).

   2. Em seguida, no menu de navegação, selecione Permissões de API.

7. No painel de permissões da API :

   1. Selecione Adicionar uma permissão e, na guia APIs da Microsoft , selecione o bloco Microsoft Graph .

   2. Selecione a opção Permissões do aplicativo para mostrar todas as permissões disponíveis e, em seguida, selecione o tipo de permissão que seu aplicativo requer.

   3. 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, confira Escopos de permissão do Intune. Para saber mais sobre outros escopos de permissão da 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 esta permissão de API para conceder acesso à API do Intune data warehouse do 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 do Microsoft Intune. Essa permissão de API é usada por parceiros de Controle de Acesso à Rede. Para obter mais informações, consulte Integração do Controle de Acesso à 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 parceiros e sua atribuição de grupo do Microsoft Entra para o Microsoft Intune sem um usuário conectado. Ele é usado por parceiros de conformidade de dispositivos. Para obter mais informações, consulte Parceiros de conformidade de dispositivos terceiros.
• pfx_cert_provider – essa permissão de API é usada para enviar certificados PFX para Intune para um usuário específico. O Intune fornece o certificado a todos os dispositivos registrados pelo usuário. Para obter mais informações, consulte Powershell de importação de PFX.
• scep_challenge_provider – essa permissão de API é usada para enviar desafios SCEP a 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 Parceiro.
• update_device_attributes - Essa permissão de API é usada para enviar informações do dispositivo para Intune de parceiros de conformidade do dispositivo e defesa contra ameaças móveis. Para obter mais informações, confira Integração da Defesa contra Ameaças Móveis com o Intune e parceiros de conformidade de dispositivos de terceiros.
• update_device_health - Essa permissão de API é usada para enviar informações sobre a integridade do dispositivo e status ameaças para Intune de parceiros de defesa contra ameaças móveis. Para obter mais informações, consulte Integração da Defesa contra Ameaças Móveis com o Intune.

Se você for um parceiro interessado na integração com o Intune usando essas permissões de API, entre em contato com a equipe da Associação de Segurança Inteligente da Microsoft para obter informações.

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

Neste ponto, você também pode:

• Opte por conceder permissão para todas as contas de locatário usarem 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ê é solicitado a conceder permissão ao aplicativo para executar as funções selecionadas.

• Disponibilize o aplicativo para usuários fora do seu 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 de aplicativos.

  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 a API do Graph, poderá encontrar um erro 503 Serviço Não Disponível. Recomendamos que você tente novamente com um tamanho de página menor, como 20 ou menos elementos.

Escopos de permissão do Intune

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

Os 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 da API do Intune.

Para saber mais:

• Autenticação do Microsoft Entra
• Escopos de permissão do aplicativo

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 conforme exibido no centro de administração do Microsoft Intune e a segunda coluna fornece o nome do escopo da permissão.

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

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

DeviceManagementApps.Read.All

• Habilitar a configuração de acesso: Ler aplicativos do Microsoft Intune

• Permite o acesso de leitura às seguintes propriedades e status da entidade:

  • Aplicativos cliente
  • Categorias de Aplicativos Móveis
  • Políticas de Proteção de Aplicativo
  • Configurações do aplicativo

DeviceManagementApps.ReadWrite.All

• Habilitar a configuração de acesso: ler e gravar aplicativos do Microsoft Intune

• Permite as mesmas operações que DeviceManagementApps.Read.All

• Também permite alterações nas seguintes entidades:

  • Aplicativos cliente
  • Categorias de Aplicativos Móveis
  • Políticas de Proteção de Aplicativo
  • Configurações do aplicativo

DeviceManagementConfiguration.Read.All

• Habilitar a configuração de acesso: ler a configuração e as políticas do dispositivo Microsoft Intune

• Permite o acesso de leitura às seguintes propriedades e status da entidade:

  • 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 configurações e políticas de dispositivos do Microsoft Intune

• 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 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 PC
  • Reiniciar
  • Excluir usuário do dispositivo compartilhado

DeviceManagementManagedDevices.Read.All

• Habilitar a configuração de acesso: Ler dispositivos Microsoft Intune

• Permite o acesso de leitura às seguintes propriedades e status da entidade:

  • Dispositivo gerenciado
  • Categoria do dispositivo
  • Aplicativo detectado
  • Ações remotas
  • Informações sobre malware

DeviceManagementManagedDevices.ReadWrite.All

• Habilitar a configuração de acesso: ler e gravar dispositivos Microsoft Intune

• 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 configurações do RBAC do Microsoft Intune

• Permite o acesso de leitura às seguintes propriedades e status da entidade:

  • Atribuições de Função
  • Definições de função
  • Operações de Recursos

DeviceManagementRBAC.ReadWrite.All

• Habilitar a configuração de acesso: Ler e gravar configurações de RBAC do Microsoft Intune

• 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

DeviceManagementScripts.Read.All

• Habilitar a configuração de acesso: Ler scripts do Microsoft Intune

• Os aplicativos podem exibir (ler) um script, especificamente:

  • Scripts do shell do dispositivo
  • Scripts de integridade do dispositivo
  • Scripts de conformidade do dispositivo
  • Scripts de Shell de Atributo Personalizado do Dispositivo
  • Scripts de Gerenciamento de Dispositivos

DeviceManagementScripts.ReadWrite.All

• Habilitar a configuração de acesso: ler e gravar scripts do Microsoft Intune
  Permite as mesmas operações que DeviceManagementScripts.Read.All

• Os aplicativos podem criar, atualizar ou excluir um script, especificamente:

  • Scripts do shell do dispositivo
  • Scripts de integridade do dispositivo
  • Scripts de conformidade do dispositivo
  • Scripts de Shell de Atributo Personalizado do Dispositivo
  • Scripts de Gerenciamento de Dispositivos

DeviceManagementServiceConfig.Read.All

• Habilitar a configuração de acesso: Ler a configuração do Microsoft Intune

• Permite o acesso de leitura às seguintes propriedades e status da entidade:

  • Registro do dispositivo
  • Certificado de Notificação por Push da Apple
  • Programa de Registro de Dispositivos Apple
  • Programa de Compra por Volume da Apple
  • Conector do Exchange
  • Termos e Condições
  • PKI de nuvem
  • Identidade Visual
  • Defesa contra Ameaças Móveis

DeviceManagementServiceConfig.ReadWrite.All

• Habilitar configuração de acesso: Ler e gravar configuração do Microsoft Intune

• Permite as mesmas operações que DeviceManagementServiceConfig.Read.All_

• Os aplicativos também podem configurar os seguintes recursos do Intune:

  • Registro do dispositivo
  • Certificado de Notificação por Push da Apple
  • Programa de Registro de Dispositivos Apple
  • Programa de Compra por Volume da Apple
  • Conector do Exchange
  • Termos e Condições
  • PKI de nuvem
  • Identidade Visual
  • Defesa contra Ameaças Móveis

Exemplos de autenticação do Microsoft Entra

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

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

Ao testar qualquer um dos exemplos, você pode receber erros de status HTTP 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 a API do Graph Microsoft e o escopo de DeviceManagementManagedDevices.Read.All permissão.

• Suas credenciais de locatário dão suporte a funções administrativas.

• O código é semelhante aos exemplos exibidos.

Autenticar o Microsoft Entra ID em C#

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

1. Inicie o Visual Studio e crie um novo projeto de aplicativo de console do Visual C# (.NET Framework).

2. Insira um nome para o seu projeto e forneça outros detalhes conforme desejado.

   

3. Use o Gerenciador de Soluções para adicionar o pacote Microsoft MSAL NuGet ao projeto:

   1. Clique com o botão direito do mouse no Gerenciador de Soluções.
   2. Escolha Gerenciar Pacotes NuGet ...>Procurar.
   3. Selecione Microsoft.Identity.Client e escolha Instalar.

4. Adicione as seguintes instruções à parte superior do Program.cs:

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

5. 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 para corresponder a um que tenha recebido pelo menos o escopo de application_IDDeviceManagementManagedDevices.Read.All permissão, conforme descrito anteriormente.

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

7. Atualize Main para chamar GetMyManagedDevices:

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

8. Compile e execute seu programa.

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

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 o Microsoft Entra ID usando o Microsoft Graph PowerShell

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

Ofereça suporte a vários locatários e parceiros

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

Para fazer isso:

1. Verifique se a conta do cliente existe no locatário de destino do Microsoft Entra.

2. Verifique se sua conta de locatário permite que os usuários registrem aplicativos (consulte Configurações do usuário).

3. Estabeleça uma relação entre cada locatário.

   Para fazer isso:

   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 a ser um convidado do seu locatário:

1. Escolha Adicionar um usuário convidado no painel de tarefas rápidas .

2. Insira o endereço de email do cliente e (opcionalmente) adicione uma mensagem personalizada para o convite.

3. Escolha Convidar.

Isso envia um convite para o usuário.

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

Quando a relação for estabelecida (ou seu convite tiver sido aceito), adicione a conta de usuário à função de 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 pelo menos um administrador de Serviços 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 do 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 no locatário do 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/";