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

Artigo
11/19/2024

O Microsoft API do Graph agora suporta Microsoft Intune com APIs e funções de permissão específicas. O Microsoft API do Graph utiliza Microsoft Entra ID para autenticação e controlo de acesso.
O acesso às APIs 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 aceder ao inquilino 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 ao Microsoft API do Graph e funções de permissão relevantes.
Descreve as funções de permissão da API Intune.
Fornece Intune exemplos de autenticação de API 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> Microsoft Entra ID >M365 Microsoft Entra ID > Registros de aplicativo.
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
  
  Azure AD API do Graph está na fase de reforma. 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 Microsoft Entra ID.
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 de Intune específicos, veja âmbitos de permissão Intune. Para saber mais sobre outros âmbitos de permissão API do Graph, 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 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 de Microsoft Intune. Para obter mais informações, consulte Utilizar o Microsoft Intune Data Warehouse.

APIs de solução de parceiros

As seguintes permissões Intune API 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 de Microsoft Intune. Esta permissão de API é utilizada por parceiros de Controle de Acesso de rede. Para obter mais informações, veja Integração de Controle de Acesso de rede com Intune.
manage_partner_compliance_policy – esta permissão de API é utilizada para gerir políticas de conformidade de parceiros com Microsoft Intune. Esta permissão de API permite que a aplicação envie políticas de conformidade de parceiros e a respetiva atribuição de grupo Microsoft Entra para 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 Intune para um utilizador específico. 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 do SCEP para 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 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 Mobile Threat Defense integration with Intune and Third party device compliance partners (Integração da Defesa Contra Ameaças para Dispositivos Móveis com parceiros de conformidade de dispositivos Intune e terceiros).
update_device_health – esta permissão de API é utilizada para enviar informações de status de status de ameaças e de estado de funcionamento do dispositivo para Intune 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 Intune).

Se for um parceiro interessado em integrar com Intune utilizar 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 API do Graph, poderá encontrar 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

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 Intune específicas e às respetivas propriedades. Esta secção resume os âmbitos de permissão para Intune funcionalidades da API.

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 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
Leitura e escrita Microsoft Intune Configuração e Políticas do Dispositivo	DeviceManagementConfiguration.ReadWrite.All
Leitura Microsoft Intune Configuração e Políticas de Dispositivos	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 tal como 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 Intune requerem acesso de administrador. Isto significa que precisa de credenciais correspondentes ao executar aplicações ou scripts que acedam Intune recursos da API.

DeviceManagementApps.Read.All

Definição Ativar Acesso: Ler aplicações Microsoft Intune
Permite o acesso de leitura às seguintes propriedades de entidade e status:
- 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 Microsoft Intune aplicações
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: leitura Microsoft Intune configuração e políticas do dispositivo
Permite o acesso de leitura às seguintes propriedades de entidade e status:
- Configuração do dispositivo
- Política de Conformidade do Dispositivo
- Mensagens de Notificação

DeviceManagementConfiguration.ReadWrite.All

Definição Ativar Acesso: leitura e escrita Microsoft Intune configuração e políticas do dispositivo
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: executar ações remotas com impacto no utilizador em dispositivos 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 Microsoft Intune dispositivos
Permite o acesso de leitura às seguintes propriedades de entidade e status:
- 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 Microsoft Intune dispositivos
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: leitura Microsoft Intune definições rbac
Permite o acesso de leitura às seguintes propriedades de entidade e status:
- Atribuições de Funções
- Definições de Função
- Operações de Recursos

DeviceManagementRBAC.ReadWrite.All

Definição Ativar Acesso: leitura e escrita Microsoft Intune definições RBAC
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: Leitura Microsoft Intune configuração
Permite o acesso de leitura às seguintes propriedades de entidade e status:
- 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
- PKI em nuvem
- Identidade Visual
- Defesa contra Ameaças Móveis

DeviceManagementServiceConfig.ReadWrite.All

Definição Ativar Acesso: leitura e escrita Microsoft Intune configuração
Permite as mesmas operações que DeviceManagementServiceConfig.Read.All_
As aplicações também podem configurar as seguintes funcionalidades de 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
- PKI em nuvem
- Identidade Visual
- Defesa contra Ameaças Móveis

Microsoft Entra exemplos de autenticação

Esta secção mostra como incorporar 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 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 isto acontecer, verifique se:

Atualizou o ID da aplicação para um autorizado a utilizar o API do Graph microsoft 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 Microsoft Entra ID em C#

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

Observação

Azure AD API do Graph está na fase de reforma. 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 Gerenciador de Soluções para adicionar o pacote NuGet microsoft MSAL ao projeto:
1. Clique com o botão direito do rato no Gerenciador 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 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 e os Intune exemplos do PowerShell.

Suportar vários inquilinos e parceiros

Se a sua organização suportar organizações com os seus próprios inquilinos 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 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 de Intune, tem de ser, pelo menos, um administrador do serviço Intune.

Também:

Utilize https://admin.microsoft.com para atribuir uma licença de Intune à sua conta de utilizador.
Atualize o código da aplicação para autenticar no domínio de inquilino 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