Como utilizar o Microsoft Entra ID para aceder às APIs do Intune no Microsoft Graph

Artigo
07/30/2024

A API do Microsoft Graph suporta agora o Microsoft Intune com APIs e funções de permissão específicas. A Microsoft Graph API utiliza o Microsoft Entra ID para autenticação e controlo 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 aceder ao inquilino do Microsoft Entra associado à aplicação.
- Permissões de função necessárias para dar suporte aos escopos de permissões do aplicativo.
O utilizador final a conceder permissão à aplicação para realizar tarefas de aplicações para o respetivo inquilino do Azure.

Este artigo:

Mostra como registar uma aplicação com acesso à Microsoft Graph API e funções de permissão relevantes.
Descreve as funções de permissão da API do Intune.
Fornece exemplos de autenticação da API do Intune para C# e PowerShell.
Descreve como suportar vários inquilinos.

Para saber mais, confira:

Registrar aplicativos para usar a API do Microsoft Graph

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

Inicie sessão no centro de administração do Microsoft Intune com as credenciais administrativas.

Conforme apropriado, você poderá usar:
- A conta do administrador de locatários.
- Uma conta de utilizador inquilino com a definição Utilizadores pode registar aplicações ativada.
Selecione Todos os serviços>M365 Microsoft Entra ID>Registos da AplicaçãoMicrosoft Entra ID>.
Escolha Novo registro para criar um aplicativo ou escolha um aplicativo existente. (Se escolher uma aplicação existente, ignore o passo seguinte.)
No painel Registar uma aplicação , especifique o seguinte:
- Um Nome para a aplicação (apresentado quando os utilizadores iniciam sessão).
- O tipo de conta Suportado.
- Um valor de URI de Redirecionamento . Este valor é a opção.
  
  Observação
  
  A Graph API do Azure AD está na fase de descontinuação. 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, veja Cenários de Autenticação para o ID do Microsoft Entra.
No painel da aplicação:
1. Tome nota do valor da ID do aplicativo (cliente).
2. Selecione Permissões de API.
No painel permissões da API, selecione Adicionar uma permissão>apIs> da MicrosoftMicrosoft Graph. Em seguida, selecione o tipo de permissões necessárias para a sua aplicação.

Escolha as funções necessárias para a sua aplicação ao colocar uma marca de verificação à esquerda dos nomes relevantes. Para saber mais sobre âmbitos de permissão específicos do Intune, veja Âmbitos de permissão do Intune. Para saber mais sobre outros âmbitos de permissão da Graph API, veja 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 criação de relatórios e armazém de dados

Quando adiciona uma aplicação através do centro de administração do Microsoft Entra, pode escolher as permissões da API do Intune com base nos requisitos da sua aplicação.

get_data_warehouse - Utilize esta permissão de API para conceder acesso à API do armazém de dados do Intune a partir do Microsoft Intune. Para obter mais informações, veja Utilizar o Armazém de Dados do Microsoft Intune.

APIs de solução de parceiros

As seguintes permissões da API do Intune estão disponíveis ao adicionar uma aplicação através do centro de administração do Microsoft Entra:

get_device_compliance – esta permissão de API é utilizada para obter informações de estado e conformidade do dispositivo do Microsoft Intune. Esta permissão de API é utilizada por parceiros de Controlo de Acesso à Rede. Para obter mais informações, veja Integração do Controlo de Acesso à Rede com o Intune.
manage_partner_compliance_policy – esta permissão de API é utilizada para gerir políticas de conformidade de parceiros com o Microsoft Intune. Esta permissão de API permite que a aplicação envie políticas de conformidade de parceiros e a atribuição do grupo Microsoft Entra para o Microsoft Intune sem um utilizador com sessão iniciada. É utilizado por parceiros de conformidade de dispositivos. Para obter mais informações, veja Parceiros de conformidade de dispositivos de terceiros.
pfx_cert_provider – esta permissão de API é utilizada para enviar certificados PFX para o Intune para um utilizador específico. O Intune entrega o certificado a todos os dispositivos inscritos pelo utilizador. Para obter mais informações, veja PowerShell de Importação de PFX.
scep_challenge_provider – esta permissão de API é utilizada para enviar desafios de SCEP para o Intune para validação de pedidos de certificado. É utilizado por parceiros da Autoridade de Certificação. Para obter mais informações, veja Autoridade de Certificação de Parceiros.
update_device_attributes – esta permissão de API é utilizada para enviar informações do dispositivo para o Intune a partir de parceiros de conformidade de dispositivos e de defesa contra ameaças para dispositivos móveis. Para obter mais informações, veja Integração da Defesa Contra Ameaças para Dispositivos Móveis com o Intune e parceiros de conformidade de dispositivos de terceiros.
update_device_health – esta permissão de API é utilizada para enviar informações sobre o estado de funcionamento do dispositivo e o estado de ameaça para o Intune a partir de parceiros de defesa contra ameaças para dispositivos móveis. Para obter mais informações, veja Mobile Threat Defense integration with Intune (Integração da Defesa Contra Ameaças para Dispositivos Móveis com o Intune).

Se for um parceiro interessado em integrar com o Intune com estas permissões de API, contacte a equipa da Associação de Segurança Inteligente da Microsoft para obter informações.

Quando terminar, selecione Adicionar permissões para guardar as alterações.

Neste momento, também pode:

Opte por conceder permissão para que todas as contas de inquilino utilizem a aplicação sem fornecer credenciais.

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

Quando executa a aplicação pela primeira vez, é-lhe pedido que conceda permissão à aplicação para efetuar as funções selecionadas.
Disponibilize a aplicação a utilizadores fora do seu inquilino. (Normalmente, só é necessário para parceiros que suportem vários inquilinos/organizações.)

Para fazer isso:
1. Selecione Manifesto no painel da aplicação.
2. Altere o valor da availableToOtherTenants definição para true.
3. Salve suas alterações.

Listagem de aplicações

Se receber uma grande quantidade de dados ao pedir a listagem de aplicações ao utilizar a Graph API, poderá deparar-se com um erro 503 Serviço Indisponível. Recomendamos que tente novamente com um tamanho de página mais pequeno, como 20 ou menos elementos.

Âmbitos de permissão do Intune

O Microsoft Entra ID e o Microsoft Graph utilizam âmbitos de permissão para controlar o acesso aos recursos empresariais.

Os âmbitos de permissão (também denominados âmbitos OAuth) controlam o acesso a entidades específicas do Intune e às respetivas propriedades. Esta secção resume os âmbitos de permissão das funcionalidades da API do Intune.

Para saber mais:

Quando concede permissão ao Microsoft Graph, pode especificar os seguintes âmbitos para controlar o acesso às funcionalidades do Intune: a tabela seguinte resume os âmbitos de permissão da API do Intune. A primeira coluna mostra o nome da funcionalidade conforme apresentado no centro de administração do Microsoft Intune e a segunda coluna fornece o nome do âmbito da permissão.

Definição Ativar 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 escrever Políticas e Configuração de Dispositivos do Microsoft Intune	DeviceManagementConfiguration.ReadWrite.All
Leia Configuração e Políticas de Dispositivos do Microsoft Intune	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 definições conforme aparecem no centro de administração do Microsoft Intune. As secções seguintes descrevem os âmbitos por ordem alfabética.

Neste momento, todos os âmbitos de permissão do Intune necessitam de acesso de administrador. Isto significa que precisa de credenciais correspondentes ao executar aplicações ou scripts que acedem aos recursos da API do Intune.

DeviceManagementApps.Read.All

Definição Ativar Acesso : Ler aplicações do Microsoft Intune
Permite o acesso de leitura às seguintes propriedades e estado da entidade:
- Aplicações Cliente
- Categorias de Aplicações Móveis
- Políticas de Proteção de Aplicativo
- Configurações da Aplicação

DeviceManagementApps.ReadWrite.All

Definição Ativar Acesso : ler e escrever aplicações do Microsoft Intune
Permite as mesmas operações que DeviceManagementApps.Read.All
Também permite alterações às seguintes entidades:
- Aplicações Cliente
- Categorias de Aplicações Móveis
- Políticas de Proteção de Aplicativo
- Configurações da Aplicação

DeviceManagementConfiguration.Read.All

Definição Ativar Acesso : Ler políticas e configuração de dispositivos do Microsoft Intune
Permite o acesso de leitura às seguintes propriedades e estado da entidade:
- Configuração do dispositivo
- Política de Conformidade do Dispositivo
- Mensagens de Notificação

DeviceManagementConfiguration.ReadWrite.All

Definição Ativar Acesso : leitura e escrita de políticas e configuração de dispositivos do Microsoft Intune
Permite as mesmas operações que DeviceManagementConfiguration.Read.All
As aplicações também podem criar, atribuir, eliminar e alterar as seguintes entidades:
- Configuração do dispositivo
- Política de Conformidade do Dispositivo
- Mensagens de Notificação

DeviceManagementManagedDevices.PrivilegedOperations.All

Definição Ativar Acesso : efetuar ações remotas com impacto no utilizador em dispositivos do Microsoft Intune
Permite as seguintes ações remotas num dispositivo gerido:
- Desativar
- Revelar
- Repor/Recuperar Código de Acesso
- Bloqueio remoto
- Ativar/Desativar o Modo Perdido
- Limpar PC
- Reiniciar
- Eliminar Utilizador do Dispositivo Partilhado

DeviceManagementManagedDevices.Read.All

Definição Ativar Acesso : Ler dispositivos do Microsoft Intune
Permite o acesso de leitura às seguintes propriedades e estado da entidade:
- Dispositivo Gerido
- Categoria do Dispositivo
- Aplicação Detetada
- Ações remotas
- Informações sobre software maligno

DeviceManagementManagedDevices.ReadWrite.All

Definição Ativar Acesso : ler e escrever dispositivos do Microsoft Intune
Permite as mesmas operações que DeviceManagementManagedDevices.Read.All
As aplicações também podem criar, eliminar e alterar as seguintes entidades:
- Dispositivo Gerido
- 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

Definição Ativar Acesso : Ler as definições de RBAC do Microsoft Intune
Permite o acesso de leitura às seguintes propriedades e estado da entidade:
- Atribuições de Funções
- Definições de Função
- Operações de Recursos

DeviceManagementRBAC.ReadWrite.All

Definição Ativar Acesso : Ler e escrever as definições do RBAC do Microsoft Intune
Permite as mesmas operações que DeviceManagementRBAC.Read.All
As aplicações também podem criar, atribuir, eliminar e alterar as seguintes entidades:
- Atribuições de Funções
- Definições de Função

DeviceManagementServiceConfig.Read.All

Definição Ativar Acesso : Ler a configuração do Microsoft Intune
Permite o acesso de leitura às seguintes propriedades e estado da entidade:
- Inscrição de Dispositivos
- Certificado de Notificação Push da Apple
- Programa de Inscrição de Dispositivos Apple
- Apple Volume Purchase Program
- Exchange Connector
- Termos e Condições
- Cloud PKI
- Identidade Visual
- Defesa contra Ameaças Móveis

DeviceManagementServiceConfig.ReadWrite.All

Definição Ativar Acesso : Leitura e escrita da configuração do Microsoft Intune
Permite as mesmas operações que DeviceManagementServiceConfig.Read.All_
As aplicações também podem configurar as seguintes funcionalidades do Intune:
- Inscrição de Dispositivos
- Certificado de Notificação Push da Apple
- Programa de Inscrição de Dispositivos Apple
- Apple Volume Purchase Program
- Exchange Connector
- Termos e Condições
- Cloud PKI
- Identidade Visual
- Defesa contra Ameaças Móveis

Exemplos de autenticação do Microsoft Entra

Esta secção mostra como incorporar o Microsoft Entra ID nos seus projetos C# e PowerShell.

Em cada exemplo, terá de especificar um ID de aplicação que tenha, pelo menos, o âmbito de DeviceManagementManagedDevices.Read.All permissão (abordado anteriormente).

Ao testar qualquer um dos exemplos, poderá receber erros de estado 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 isto acontecer, verifique se:

Atualizou o ID da aplicação para um autorizado a utilizar a Microsoft Graph API e o âmbito de DeviceManagementManagedDevices.Read.All permissão.
As suas credenciais de inquilino suportam funções administrativas.
O código é semelhante aos exemplos apresentados.

Autenticar o Microsoft Entra ID em C#

Este exemplo mostra como utilizar C# para obter uma lista de dispositivos associados à sua conta do Intune.

Observação

A Graph API do Azure AD está na fase de descontinuação. 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, em seguida, crie um novo projeto de aplicação de Consola do Visual C# (.NET Framework).
Introduza um nome para o projeto e forneça outros detalhes conforme pretendido.
Utilize o Explorador de Soluções para adicionar o pacote NuGet msAL da Microsoft ao projeto:
1. Clique com o botão direito do rato no Explorador de Soluções.
2. Selecione Gerir Pacotes NuGet...>Procurar.
3. Selecione Microsoft.Identity.Client e, em seguida, selecione 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, pelo menos, o DeviceManagementManagedDevices.Read.All âmbito de permissão concedido, conforme descrito anteriormente.

Adicione um método para obter 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");
}

Atualize Principal para chamar GetMyManagedDevices:

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

Compile e execute o programa.

Quando executar o programa pela primeira vez, deverá receber dois pedidos. O primeiro pede as suas credenciais e o segundo concede permissões para o managedDevices pedido.

Para referência, eis 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 com o Microsoft Graph PowerShell

Os scripts do PowerShell podem utilizar o módulo do PowerShell do Microsoft Graph para autenticação. Para saber mais, veja Microsoft Graph PowerShell and the Intune PowerShell examples (Exemplos do PowerShell do Intune).

Suportar vários inquilinos e parceiros

Se a sua organização suportar organizações com os seus próprios inquilinos do Microsoft Entra, poderá querer permitir que os seus clientes utilizem a sua aplicação com os respetivos inquilinos.

Para fazer isso:

Verifique se a conta de cliente existe no inquilino do Microsoft Entra de destino.
Verifique se a sua conta de inquilino permite que os utilizadores registem aplicações (veja Definições do utilizador).
Estabeleça uma relação entre cada inquilino.

Para tal, faça o seguinte:

a. Utilize o Centro de Parceiros da Microsoft para definir uma relação com o seu cliente e o respetivo endereço de e-mail.

b. Convide o utilizador para se tornar um convidado do seu inquilino.

Para convidar o utilizador para ser um convidado do seu inquilino:

Selecione Adicionar um utilizador convidado no painel Tarefas rápidas.
Introduza o endereço de e-mail do cliente e (opcionalmente) adicione uma mensagem personalizada para o convite.
Selecione Convidar.

Esta ação envia um convite ao utilizador.

O utilizador tem de escolher a ligação Introdução para aceitar o seu convite.

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

Lembre-se de adicionar o utilizador a outras funções, conforme necessário. Por exemplo, para permitir que o utilizador faça a gestão das definições do Intune, tem de ser um Administrador Global ou um administrador do Serviço do Intune.

Também:

Utilize https://admin.microsoft.com para atribuir uma licença do Intune à sua conta de utilizador.
Atualize o código da aplicação para autenticar no domínio de inquilino do Microsoft Entra do cliente, em vez do seu.

Por exemplo, suponha que o seu domínio de inquilino é contosopartner.onmicrosoft.com e que o domínio de inquilino do cliente é northwind.onmicrosoft.com, atualizaria o código para autenticar no inquilino do cliente.

Para fazê-lo numa aplicação C# com base no exemplo anterior, teria de alterar o valor da authority variável:
```
string authority = "https://login.microsoftonline.com/common/";
```
para
```
string authority = "https://login.microsoftonline.com/northwind.onmicrosoft.com/";
```

Partilhar via