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

Observação: Este tópico se aplica somente a desenvolvedores de aplicativos CSP (Provedor de Soluções na Nuvem) da Microsoft. O programa Microsoft Cloud Solution Provider (CSP) permite que os parceiros da Microsoft revendam e gerenciem o Microsoft Online Services aos clientes.

Este artigo descreve como habilitar o acesso ao aplicativo aos dados do cliente gerenciados pelo parceiro 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 para serviço.

O que é um aplicativo gerenciado por parceiros

O programa CSP permite que os parceiros da Microsoft revendam e gerenciem o Microsoft Online Services (como Microsoft 365, Microsoft Azure e CRM Online) para clientes. O gerenciamento de atendimentos ao cliente é feito por meio de Privilégios de Administração Delegados, que permitem que usuários parceiros designados (conhecidos como agentes) acessem e configurem os ambientes de seus clientes.

Além disso, como desenvolvedor parceiro, você pode criar um aplicativo gerenciado por parceiro para gerenciar os serviços Microsoft de seus clientes. Os aplicativos gerenciados por parceiros geralmente são chamados de aplicativos pré-consentidos porque todos os seus clientes são automaticamente pré-consentidos para seus aplicativos gerenciados por parceiros. Isso significa que quando um usuário de um dos locatários do cliente usa um dos aplicativos gerenciados pelo parceiro, 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 Delegada, para que seus agentes parceiros também possam obter acesso privilegiado a seus clientes por meio de seu aplicativo gerenciado por parceiros.

Como configurar um aplicativo gerenciado por parceiros

Um aplicativo é gerenciado por parceiro quando tem permissões elevadas para acessar dados do cliente.

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 parceiro 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 com privilégios mínimos.

Pré-autorize seu aplicativo para todos os seus clientes

Por fim, conceda ao seu aplicativo gerenciado pelo parceiro as 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 de parceiro, usando o Microsoft Entra PowerShell ou o Microsoft Graph PowerShell. Siga estas etapas para localizar o grupo Adminagents , o servicePrincipal e adicioná-lo ao grupo.

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 os aplicativos multilocatários regulares.

Além do acesso pré-consentido a todos os locatários do cliente, os aplicativos gerenciados por parceiros têm mais um recurso. Ele permite que seus agentes usem seu aplicativo para acessar os dados de locatário de seus clientes (usando privilégios de administrador delegado). 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 ficaria, imagine que seu locatário parceiro esteja partner.com (que é o locatário inicial de seus agentes) e um de seus clientes esteja 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

No momento, o envolvimento do cliente do CSP está limitado a uma única região. Os aplicativos gerenciados por parceiros têm a mesma limitação. Isso significa que você deve ter um locatário separado para cada região em que vender. Por exemplo, se o aplicativo gerenciado pelo parceiro estiver registrado em um locatário nos EUA, mas o cliente estiver na UE, o aplicativo gerenciado pelo parceiro 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 de entrar) para obter o nome de usuário de entrada de seus clientes para decidir qual identidade de aplicativo gerenciada por parceiro específica da região usar, para servir ao 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 de cliente é criado. Além disso, um relacionamento de parceiro também é criado, o que o torna o parceiro de registro para esse novo locatário do cliente. Essa relação de parceiro pode levar até três minutos para ser propagada para o novo locatário do cliente. Se o aplicativo chamar o Microsoft Graph logo após a criação, provavelmente receberá um erro de acesso negado. Um atraso semelhante pode ocorrer quando um cliente existente aceita seu convite. Isso ocorre porque o pré-consentimento depende da presença do relacionamento de parceiro 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 o 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.

Observação: Na 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 funciona, pois o token de acesso é válido por uma hora e não contém as declarações de permissão pré-consentidas.