Como usar o Azure AD para acessar as APIs Intune no Microsoft Graph

  • Artigo
  • 13 minutos para o fim da leitura

O Microsoft API do Graph agora dá suporte Microsoft Intune apIs específicas e funções de permissão. A API do Microsoft Graph usa o Azure Active Directory (Azure AD) para autenticação e controle de acesso.
O acesso às APIs Intune no Microsoft Graph requer:

  • Uma ID de aplicativo com:

    • Permissão para chamar o Azure AD 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 Azure AD associado ao aplicativo.
    • Permissões de função necessárias para dar suporte aos escopos de permissões do aplicativo.

  • O usuário final para 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 ao Microsoft API do Graph funções de permissão relevantes.

  • Descreve as funções de permissão Intune API.

  • Fornece Intune de autenticação de API 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:

  1. Entre no Centro de administração do Microsoft Endpoint Manager 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.

  2. Selecione Todos os serviçosM365 > Azure Active Directory > Azure Active Directory > Registros de aplicativo.

    The App registrations menu command

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

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

  5. No painel do aplicativo:

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

    2. Selecione Permissões de API.

  6. No painel de permissões de API, escolha Adicionar um apIsMicrosoft > > permissionMicrosoft Graph. Em seguida, selecione o tipo de permissões que seu aplicativo requer.

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

    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ório

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

APIs de solução de parceiro

As seguintes Intune de API estão disponíveis ao adicionar um aplicativo por meio do Azure Active Directory de administração:

  • get_device_compliance - Essa permissão de API é usada para obter informações de conformidade e estado do dispositivo Microsoft Intune. Essa permissão de API é usada por parceiros de Controle de Acesso rede. Para obter mais informações, consulte Integração Controle de Acesso rede com Intune.
  • manage_partner_compliance_policy - Essa permissão de API é usada para gerenciar políticas de conformidade do parceiro com Microsoft Intune. Essa permissão de API permite que o aplicativo envie políticas de conformidade do parceiro e sua atribuição Azure AD grupo 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 do dispositivo de terceiros.
  • pfx_cert_provider - Essa permissão de API é usada para enviar certificados PFX para Intune para um usuário específico. 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 para Intune validação de solicitação de certificado. Ele é usado por parceiros da Autoridade de Certificação. Para obter mais informações, consulte a Autoridade de Certificação de Parceiros.
  • send_data_usage - Essa permissão de API é usada para disparar alterações de política para dispositivos com base nos limites de gerenciamento de despesas de telecomunicações. Ele é usado para integrações de parceiros de gerenciamento de despesas de telecomunicações. Para obter mais informações, consulte Gerenciamento de despesas de telecomunicações Intune.
  • 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, consulte a integração da Defesa contra Ameaças Móveis com Intune e parceiros de conformidade de dispositivo de terceiros.
  • update_device_health - Essa permissão de API é usada para enviar informações de status de ameaça e integridade do dispositivo para Intune de parceiros de defesa contra ameaças móveis. Para obter mais informações, consulte a integração da Defesa contra Ameaças Móveis com 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 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:

  • 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 permissão ao aplicativo para executar as funções selecionadas.

  • Dispobilize o aplicativo para usuários fora do seu locatário. (Normalmente, isso só é necessário para parceiros que dão suporte a vários locatários/organizações.)

    Para fazer isso:

    1. Escolha Manifesto no painel do aplicativo.

      The Edit manifest blade

    2. Altere o valor da configuração availableToOtherTenants para true.

    3. Salve suas alterações.

Intune escopos de permissão

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

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

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

Habilitar 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 políticas Microsoft Intune e configuração 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 como elas aparecem no Microsoft Endpoint Manager de administração. As seções a seguir descrevem os escopos em ordem alfabética.

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

DeviceManagementApps.Read.All

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

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

    • Aplicativos cliente
    • Categorias de aplicativo móvel
    • Políticas de Proteção de Aplicativo
    • Configurações de aplicativo

DeviceManagementApps.ReadWrite.All

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

  • 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 de aplicativo

DeviceManagementConfiguration.Read.All

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

  • Permite 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 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 configuração de acesso: executar ações remotas que afetam o usuário em Microsoft Intune dispositivos

  • Permite as seguintes ações remotas em um dispositivo gerenciado:

    • Desativar
    • Revelar
    • Redefinir/recuperar senha
    • Bloqueio remoto
    • Habilitar/desabilitar o modo perdido
    • Pc limpo
    • Reiniciar
    • Excluir Usuário do Dispositivo Compartilhado

DeviceManagementManagedDevices.Read.All

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

  • Permite 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 Microsoft Intune dispositivos

  • 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 configuração de acesso: Microsoft Intune configurações de RBAC de leitura

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

    • Atribuições de função
    • Definições de função
    • Operações de recurso

DeviceManagementRBAC.ReadWrite.All

  • Habilitar configuração de acesso: leitura e gravação Microsoft Intune configurações de 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 configuração de acesso: leitura Microsoft Intune configuração

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

    • Registro de dispositivo
    • Apple Push Notification Certificate
    • Programa de Registro de Dispositivos da Apple
    • Apple Volume Purchase Program
    • Exchange conector
    • Termos e Condições
    • Gerenciamento de Despesas de Telecomunicações
    • PKI de nuvem
    • Identidade Visual
    • Defesa contra Ameaças Móveis

DeviceManagementServiceConfig.ReadWrite.All

  • Habilitar configuração de acesso: leitura e gravação Microsoft Intune configuração

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

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

    • Registro de dispositivo
    • Apple Push Notification Certificate
    • Programa de Registro de Dispositivos da Apple
    • Apple Volume Purchase Program
    • Exchange conector
    • Termos e Condições
    • Gerenciamento de Despesas de Telecomunicações
    • PKI de nuvem
    • Identidade Visual
    • Defesa contra Ameaças Móveis

Azure AD de autenticação

Esta seção mostra como incorporar Azure AD em seus projetos do C# e do PowerShell.

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

Ao testar qualquer um dos exemplos, você pode receber erros de status HTTP 403 (Proibido) semelhantes ao seguinte:

{
  "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 pessoa autorizada a usar o microsoft API do Graph e o escopo DeviceManagementManagedDevices.Read.All de permissão.

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

  • Seu código é semelhante aos exemplos exibidos.

Autenticar Azure AD em C#

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

Observação

Azure Active Directory (Azure AD) autenticação (ADAL) e Azure AD API do Graph serão preteridos. 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 .

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

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

    Creating a C# console app project in Visual Studio

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

    1. Clique com o botão direito do mouse Gerenciador de Soluções.
    2. Escolha Gerenciar NuGet Pacotes... >Navegue.
    3. Selecione Microsoft.IdentityModel.Clients.ActiveDirectory e escolha Instalar.
    Selecting the Azure AD identity model module

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

    using Microsoft.IdentityModel.Clients.ActiveDirectory;
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 para application_ID corresponder a um que recebeu pelo menos o escopo DeviceManagementManagedDevices.Read.All de 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 o programa.

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

Para referência, este é o programa concluído:

using Microsoft.IdentityModel.Clients.ActiveDirectory;
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 Azure AD (PowerShell)

Os scripts do PowerShell podem usar o módulo do PowerShell do AzureAD para autenticação. Para saber mais, confira Azure Active Directory PowerShell versão 2 e os Intune do PowerShell.

Suporte a vários locatários e parceiros

Se sua organização der suporte a organizações com seus próprios Azure AD locatários, convém 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 Azure AD destino.

  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, qualquer um dos dois:

    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:

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

    Use Quick Tasks to add a guest user

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

    Inviting an external user as a guest

  3. Escolha Convidar.

Isso envia um convite para o usuário.

A sample guest invitation

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 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 Intune configurações, ele precisa ser um Administrador Global ou um administrador do Intune Service.

Também:

  • Use https://admin.microsoft.com para atribuir uma Intune à sua conta de usuário.

  • Atualize o código do aplicativo para autenticar no domínio Azure AD locatário do cliente, em vez do seu próprio.

    Por exemplo, suponha que contosopartner.onmicrosoft.com northwind.onmicrosoft.comseu domínio de locatário seja e o domínio de locatário do cliente seja, 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 variável authority :

    string authority = "https://login.microsoftonline.com/common/";

    para

    string authority = "https://login.microsoftonline.com/northwind.onmicrosoft.com/";