Compartilhar via

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

  • Artigo

Nota: Este tópico aplica-se apenas aos programadores de aplicações do Fornecedor de Soluções Cloud da Microsoft (CSP). O programa Fornecedor de Soluções Cloud da Microsoft (CSP) permite aos parceiros da Microsoft revender e gerir serviços Microsoft Online aos clientes.

Este artigo descreve como ativar o acesso da aplicação a dados de clientes geridos por parceiros através do Microsoft Graph através do fluxo de concessão de código de autorização ou do fluxo de credenciais do cliente do serviço para o serviço.

Importante

Chamar o Microsoft Graph a partir de uma aplicação CSP só é suportado para recursos de diretório (como utilizador, grupo, dispositivo, organização) e recursos de Intune.

O que é um aplicativo gerenciado por parceiros

O programa CSP permite aos parceiros da Microsoft revender e gerir o Microsoft Online Services (como o Microsoft 365, o Microsoft Azure e o CRM Online) aos clientes. A gestão dos serviços ao cliente é feita através de Privilégios de Administração Delegados, que permite que os utilizadores parceiros designados (conhecidos como agentes) acedam e configurem os ambientes dos clientes.

Além disso, enquanto programador parceiro, pode criar uma aplicação gerida por parceiros para gerir os serviços Microsoft dos seus clientes. As aplicações geridas por parceiros são frequentemente denominadas aplicações pré-criadas porque todos os seus clientes são automaticamente pré-instalados para as suas aplicações geridas por parceiros. Isto significa que, quando um utilizador de um dos inquilinos do cliente utiliza uma das suas aplicações geridas pelo parceiro, o utilizador pode utilizá-la sem ser pedido que dê consentimento. As aplicações geridas 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 através da sua aplicação gerida 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.

Registar e configurar uma aplicação multi-inquilino

Os passos iniciais necessários seguem a maioria dos mesmos passos utilizados para registar e configurar uma aplicação multi-inquilino:

  1. Registe a sua aplicação no inquilino parceiro com o centro de administração do Microsoft Entra. Para funcionar como uma aplicação gerida por parceiros, uma aplicação tem de ser configurada como uma aplicação multi-inquilino. Além disso, se a sua aplicação for implementada e vendida em várias regiões geográficas, terá de registar a sua aplicação em cada uma dessas regiões, conforme descrito aqui.
  2. Configure a sua aplicação multi-inquilino, novamente através do centro de administração do Microsoft Entra, com as permissões necessárias para utilizar uma abordagem com menos privilégios.

Pré-configurar a sua aplicação para todos os seus clientes

Por fim, conceda à sua aplicação gerida pelo parceiro as permissões configuradas para todos os seus clientes. Pode fazê-lo ao adicionar o servicePrincipal que representa a aplicação ao grupo Adminagents no seu inquilino parceiro, com o Azure AD PowerShell V2 ou o Microsoft Graph PowerShell. Siga estes passos 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 tokens para aplicações geridas 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 as aplicações multi-inquilino normais.

Para além do acesso pré-consente a todos os inquilinos do cliente, as aplicações geridas por parceiros têm mais uma capacidade. Permite que os agentes utilizem a sua aplicação para aceder aos dados de inquilino dos seus clientes (utilizando privilégios de administrador delegados). Conceptualmente, funciona da seguinte forma:

  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.

Este é um fluxo de concessão de código de autorização padrão, exceto que os agentes têm de iniciar sessão com as respetivas contas de parceiro. Para ver o aspeto disto, imagine que o seu inquilino parceiro está partner.com (que é o inquilino principal dos seus agentes) e que um dos seus clientes está customer.com:

  1. Adquirir um código de autorização: A sua aplicação faz um pedido ao /authorize ponto final e tem de utilizar um inquilino do cliente, no nosso exemplo customer.com, para o inquilino de destino. Os agentes ainda iniciariam sessão com username@partner.com a conta.

    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, a cativação do cliente CSP está limitada a uma única região. As aplicações geridas por parceiros têm a mesma limitação. Isto significa que tem de ter um inquilino separado para cada região em que vende. Por exemplo, se a aplicação gerida pelo parceiro estiver registada num inquilino nos EUA, mas o cliente estiver na UE, a aplicação gerida pelo parceiro não funcionará. Cada um dos seus inquilinos parceiros regionais tem de manter o seu próprio conjunto de aplicações geridas por parceiros para gerir os clientes na mesma região. Isto pode exigir lógica adicional na sua aplicação (antes do início de sessão) para que o nome de utilizador de início de sessão dos seus clientes decida qual a identidade da aplicação gerida por parceiros específica da região a utilizar, para servir o utilizador.

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

Quando cria um novo cliente com a API do Centro de Parceiros, é criado um novo inquilino do cliente. Além disso, também é criada uma relação de parceiro, o que o torna o parceiro de registo deste novo inquilino do cliente. Esta relação de parceiro pode demorar até 3 minutos a ser propagada para o novo inquilino do cliente. Se a sua aplicação chamar o Microsoft Graph logo após a criação, é provável que a sua aplicação receba um erro de acesso negado. Pode ocorrer um atraso semelhante quando um cliente existente aceita o seu convite. Isto deve-se ao facto de o pré-requisito depender da relação de parceiro que está presente no inquilino do cliente.

Para evitar este problema, recomendamos que a aplicação parceira 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, após aguardar três minutos, continuar a receber um erro de autorização, aguarde mais 60 segundos e tente novamente.

Nota: Na repetição, tem de 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 já tem não irá funcionar, porque o token de acesso é válido durante uma hora e não conterá as afirmações de permissão pré-consentidas.