Chamar o Microsoft Graph por um Provedor de Soluções na Nuvem

  • Artigo

Nota: Este tópico se aplica apenas aos desenvolvedores de aplicativos CSP (Provedor de Soluções na Nuvem) da Microsoft. O programa CSP (Microsoft Cloud Solution Provider) permite que os parceiros da Microsoft revendam e gerenciem serviços do Microsoft Online aos clientes.

Este artigo descreve como habilitar o acesso do aplicativo a dados de cliente gerenciados por parceiros por meio do Microsoft Graph usando o fluxo de concessão de código de autorização ou o fluxo de credenciais do cliente de serviço.

Importante

Chamar o Microsoft Graph de um aplicativo CSP só tem suporte para recursos de diretório (como usuário, grupo, dispositivo, organização) e recursos de Intune.

O que é um aplicativo gerenciado por parceiros

O programa CSP permite que os parceiros da Microsoft revendam e gerenciem serviços Microsoft Online (como Microsoft 365, Microsoft Azure e CRM Online) aos clientes. O gerenciamento de serviços ao cliente é feito por meio do Delegated Administração Privileges, que permite que usuários parceiros designados (conhecidos como agentes) acessem e configurem os ambientes de seus clientes.

Além disso, como desenvolvedor de parceiros, você pode criar um aplicativo gerenciado por parceiros para gerenciar os serviços microsoft de seus clientes. Aplicativos gerenciados por parceiros geralmente são chamados de aplicativos preconsentidos porque todos os seus clientes são automaticamente pré-requisitos para seus aplicativos gerenciados por parceiros. Isso significa que quando um usuário de um de seus locatários de cliente usa um de seus aplicativos gerenciados por parceiros, o usuário pode usá-lo sem ser solicitado a dar consentimento. Os aplicativos gerenciados por parceiros também herdam privilégios de Administração delegados, para que os agentes parceiros também possam obter acesso privilegiado aos seus clientes por meio do aplicativo gerenciado pelo parceiro.

Como configurar um aplicativo gerenciado por parceiros

Um aplicativo é exibido como gerenciado por parceiros quando recebe permissões elevadas para acessar dados de seus clientes.

Observação: Aplicativos gerenciados por parceiros podem somente ser configurados em locatários de Parceiro para gerenciar recursos de locatário do cliente, aplicativos gerenciados por parceiros devem ser configurados como locatários de vários aplicativos.

Registrar e configurar um aplicativo multilocatário

As etapas iniciais necessárias aqui seguem a maioria das mesmas etapas usadas para registrar e configurar um aplicativo multilocatário:

  1. Registre seu aplicativo no locatário do Partner usando o centro de administração do Microsoft Entra. Para funcionar como um aplicativo gerenciado por parceiros, um aplicativo deve ser configurado como um aplicativo multilocatário. Além disso, se seu aplicativo for implantado e vendido em várias regiões geográficas, você precisará registrar seu aplicativo em cada uma dessas regiões, conforme descrito aqui.
  2. Configure seu aplicativo multilocatário novamente por meio do centro de administração do Microsoft Entra, com as permissões necessárias para usar uma abordagem menos privilegiada.

Pré-requisito do seu aplicativo para todos os seus clientes

Por fim, conceda ao seu aplicativo gerenciado pelo parceiro essas permissões configuradas para todos os seus clientes. Você pode fazer isso adicionando o servicePrincipal que representa o aplicativo ao grupo Adminagents em seu locatário partner, usando Azure AD PowerShell V2 ou Microsoft Graph PowerShell. Siga estas etapas para encontrar o grupo Adminagents , o servicePrincipal e adicioná-lo ao grupo.

Observação

Os módulos Azure AD e MSOnline PowerShell foram preteridos a partir de 30 de março de 2024. Para saber mais, leia a atualização sobre substituição. Após essa data, o suporte para esses módulos é limitado à assistência de migração para o SDK do Microsoft Graph PowerShell e correções de segurança. Os módulos preteridos continuarão funcionando até 30 de março de 2025.

Recomendamos migrar para o Microsoft Graph PowerShell para interagir com o Microsoft Entra ID (anteriormente Azure AD). Para obter respostas para perguntas de migração comuns, consulte as perguntas frequentes sobre migração. Observação: as versões 1.0.x do MSOnline podem sofrer interrupções após 30 de junho de 2024.

  1. Abra uma sessão do PowerShell e conecte-se ao locatário do parceiro digitando suas credenciais de administrador na janela de entrada.

    Connect-AzureAd

  2. Localize o grupo que representa os Adminagents.

    $group = Get-AzureADGroup -Filter "displayName eq 'Adminagents'"

  3. Encontrar a entidade de serviço que tenha a mesma appId do aplicativo.

    $sp = Get-AzureADServicePrincipal -Filter "appId eq '{yourAppsAppId}'"

  4. Por fim, adicione a entidade de serviço ao grupo Adminagents.

    Add-AzureADGroupMember -ObjectId $group.ObjectId -RefObjectId $sp.ObjectId

Fluxos de aquisição do token

Os fluxos de aquisição de token para aplicativos gerenciados por parceiros - fluxo de concessão de código de autorização e fluxo de credenciais de cliente serviço a serviço - são os mesmos que aplicativos multilocatários regulares.

Além do acesso preconsenciado a todos os locatários do cliente, os aplicativos gerenciados por parceiros têm mais uma funcionalidade. Ele permite que seus agentes usem seu aplicativo para acessar os dados de locatário de seus clientes (usando privilégios de administrador delegados). Conceitualmente, funciona assim:

  1. Seu agente entra em seu aplicativo com suas credenciais de usuário emitidas no locatário do parceiro.
  2. O aplicativo solicita um token de acesso para o locatário do cliente gerenciado por parceiros pretendido.
  3. O aplicativo usa o token de acesso para chamar o Microsoft Graph.

Esse é um fluxo de concessão de código de autorização padrão, exceto que seus agentes devem entrar usando suas contas de parceiro. Para ver como isso seria, imagine que seu locatário parceiro está partner.com (que é o locatário da casa para seus agentes) e um de seus clientes está customer.com:

  1. Adquira um código de autorização: Seu aplicativo faz uma solicitação para o /authorize ponto de extremidade e deve usar um locatário do cliente, em nosso exemplo customer.com, para o locatário de destino. Seus agentes ainda entrariam com a conta deles username@partner.com .

    GET https://login.microsoftonline.com/customer.com/oauth2/authorize

  2. Adquira um token de acesso usando o código de autorização: seu aplicativo deve usar um locatário do cliente como o locatário de destino — no nosso exemplo, customer.com — ao fazer a solicitação para o ponto de extremidade token:

    POST https://login.microsoftonline.com/customer.com/oauth2/token

  3. Agora que você tem um token de acesso, chame o Microsoft Graph colocando o token de acesso no cabeçalho de autorização HTTP:

    GET https://graph.microsoft.com/beta/users
Authorization: Bearer <token>

Registre seu aplicativo nas regiões para as quais você oferece suporte

Atualmente, o envolvimento do cliente CSP está limitado a uma única região. Aplicativos gerenciados por parceiros carregam a mesma limitação. Isso significa que você deve ter um locatário separado para cada região em que você vende. Por exemplo, se seu aplicativo gerenciado por parceiros estiver registrado em um locatário nos EUA, mas seu cliente estiver na UE , o aplicativo gerenciado por parceiros não funcionará. Cada um de seus locatários parceiros regionais deve manter seu próprio conjunto de aplicativos gerenciados por parceiros para gerenciar clientes na mesma região. Isso pode exigir lógica adicional em seu aplicativo (antes da entrada) para obter o nome de usuário de entrada de seus clientes para decidir qual identidade de aplicativo gerenciado por parceiros específica da região deve ser usada para servir o usuário.

Chamar o Microsoft Graph imediatamente após a criação do cliente

Quando você cria um novo cliente usando a API do Partner Center, um novo locatário do cliente é criado. Além disso, uma relação de parceiro também é criada, o que faz de você o parceiro de registro desse novo locatário do cliente. Essa relação de parceiro pode levar até 3 minutos para propagar para o novo locatário do cliente. Se seu aplicativo chamar o Microsoft Graph logo após a criação, seu aplicativo provavelmente receberá um erro negado de acesso. Um atraso semelhante pode ser experimentado quando um cliente existente aceita seu convite. Isso ocorre porque o pré-requisito depende da relação de parceiro estar presente no locatário do cliente.

Para evitar esse problema, recomendamos que seu aplicativo parceiro aguarde três minutos após a criação do cliente antes de chamar Microsoft Entra ID para adquirir um token (para chamar o Microsoft Graph). Isso deve abranger a maioria dos casos. No entanto, se depois de esperar três minutos você ainda receber um erro de autorização, aguarde mais 60 segundos e tente novamente.

Nota: Na nova tentativa, você deve adquirir um novo token de acesso do Microsoft Entra ID, antes de chamar o Microsoft Graph. Chamar o Microsoft Graph com o token de acesso que você já tem não funcionará, pois o token de acesso é bom por uma hora e não conterá as declarações de permissão pré-consentidas.