Chamar o Microsoft Graph por um Provedor de Soluções na NuvemCall Microsoft Graph from a Cloud Solution Provider application

Observação: Este tópico se aplica somente a desenvolvedores de aplicativos do Provedor de Soluções na Nuvem (CSP) da Microsoft. O programa Provedor de Soluções na Nuvem (CSP) da Microsoft permite que os parceiros da Microsoft revendam e gerenciem os serviços online da Microsoft para os clientes.Note: This topic applies only to Microsoft Cloud Solution Provider (CSP) application developers. The Microsoft Cloud Solution Provider (CSP) program enables Microsoft’s partners to resell and manage Microsoft Online services to customers.

Este tópico descreve como habilitar o acesso do aplicativo aos dados do cliente gerenciados por parceiros através do Microsoft Graph usando o fluxo de concessão do código de autorização ou o fluxo de credenciais do cliente de serviços.This topic describes how to enable application access to partner-managed customer data via Microsoft Graph using either the authorization code grant flow or the service to service client credentials flow.

Importante: Chamar o Microsoft Graph a partir de um aplicativo CSP só é compatível com recursos de diretório (como usuário, grupo, dispositivo, organização) e recursos do Intune.Important: Calling Microsoft Graph from a CSP application is only supported for directory resources (such as user, group,device, organization) and Intune resources.

O que é um aplicativo gerenciado por parceirosWhat is a partner-managed application

O programa CSP permite que os parceiros da Microsoft revendam e gerenciem os Serviços Online da Microsoft (como o Microsoft 365, Microsoft Azure e CRM Online) para os clientes. O gerenciamento do atendimento ao cliente é feito por meio de Privilégios de Administrador Delegados e isso permite que os usuários de parceiros designados (conhecidos como agentes) acessem e configurem os ambientes de seus clientes.The CSP program enables Microsoft’s partners to resell and manage Microsoft Online Services (such as Microsoft 365, Microsoft Azure, and CRM Online) to customers. Management of customer services is done through Delegated Admin Privileges, which enables designated partner users (known as agents) to access and configure their customers’ environments.

Além disso, como desenvolvedor do parceiro, você pode criar um aplicativo gerenciado por parceiros para gerenciar os serviços da Microsoft de seus clientes. Os aplicativos gerenciados por parceiros são frequentemente chamados de aplicativos pré-consentidos porque todos os seus clientes são automaticamente pré-autorizados a utilizar os aplicativos gerenciados por parceiros. Isso significa que, quando um usuário de um dos locatários do 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 os Privilégios de Administrador Delegados para que os agentes do parceiro também possam obter acesso privilegiado aos clientes através do aplicativo gerenciado por parceiros.Additionally, as a partner developer, you can build a partner-managed app to manage your customers' Microsoft services. Partner-managed apps are often called pre-consented apps because all your customers are automatically pre-consented for your partner-managed apps. This means when a user from one of your customer tenants uses one of your partner-managed apps, the user can use it without being prompted to give consent. Partner-managed apps also inherit Delegated Admin Privileges, so your partner agents can also get privileged access to your customers through your partner-managed application.

Como configurar um aplicativo gerenciado por parceirosHow to set-up a partner-managed application

Um aplicativo é exibido como gerenciado por parceiros quando recebe permissões elevadas para acessar dados de seus clientes.An application is viewed as partner-managed when it is granted elevated permissions to access your customers' data.

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.Note: Partner-managed apps can only be configured on Partner tenants, and in order to manage customer tenant resources, partner-managed apps must be configured as multi-tenant applications.

Registrar e configurar um aplicativo de vários locatáriosRegister and configure a multi-tenant app

As etapas iniciais exigidas aqui seguem quase as mesmas etapas usadas para registrar e configurar um aplicativo multilocatário:The initial steps required here follow most of the same steps used to register and configure a multi-tenant application:

  1. Registre seu aplicativo no Locatário do parceiro usando o Portal do Azure. Para funcionar como um aplicativo gerenciado por parceiros, o aplicativo deve ser configurado como um aplicativo multilocatário. Além disso, se o aplicativo for implantado e vendido em diversas regiões geográficas, você precisará registrar seu aplicativo em cada uma dessas regiões conforme descrito aqui.Register your application in your Partner tenant using the Azure Portal. To function as a partner-managed app, an application must be configured as a multi-tenant app. Additionally, if your app is deployed and sold in multiple geographic regions you will need to register your app in each of those regions as described here.
  2. Configure seu aplicativo multilocatário, novamente através do Portal do Azure, com as permissões exigidas necessárias usando uma abordagem menos privilegiada.Configure your multi-tenant app, again through the Azure Portal, with the required permissions it needs using a least privileged approach.

Por fim, conceda ao aplicativo gerenciado por parceiros as permissões configuradas para todos os seus clientes. Você pode fazer isso adicionando o servicePrincipal que representa o aplicativo no grupo Adminagents do locatário do Parceiro usando o Powershell do Azure AD V2. Você pode baixar e instalar o PowerShell do Azure AD V2 aqui. Siga estas etapas para localizar o grupo Adminagents, o servicePrincipal e adicioná-lo ao grupo.Finally grant your partner-managed app those configured permissions for all your customers. You can do this by adding the servicePrincipal that represents the app to the Adminagents group in your Partner tenant, using Azure AD powershell V2. You can download and install Azure AD PowerShell V2 from here. Follow these steps to find the Adminagents group, the servicePrincipal and add it to the group.

  1. Abra uma sessão do PowerShell e conecte-se ao locatário do parceiro digitando suas credenciais de administrador na janela de entrada.Open a PowerShell session and connect to your partner tenant by entering your admin credentials into the sign-in window.

    Connect-AzureAd
    
  2. Localize o grupo que representa os Adminagents.Find the group that represents the Adminagents.

    $group = Get-AzureADGroup -Filter "displayName eq 'Adminagents'"
    
  3. Encontrar a entidade de serviço que tenha a mesma appId do aplicativo.Find the service principal that has the same appId as your app.

    $sp = Get-AzureADServicePrincipal -Filter "appId eq '{yourAppsAppId}'"
    
  4. Por fim, adicione a entidade de serviço ao grupo Adminagents.Finally, add the service principal to the Adminagents group.

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

Fluxos de aquisição do tokenToken acquisition flows

Os fluxos de aquisição de tokens de aplicativos gerenciados por parceiros, ou seja, o fluxo de concessão do código de autorização e o fluxo de credenciais de cliente de serviço a serviço, são os mesmos dos aplicativos multilocatário normais.Token acquisition flows for partner-managed apps - authorization code grant flow and service-to-service client credentials flow - are the same as regular multi-tenant apps.

Além do acesso previamente consentido a todos os locatários do cliente, os aplicativos gerenciados por parceiros têm um recurso adicional. Esse recurso permite que os agentes usem seu aplicativo para acessar os dados de locatário de seus clientes (usando os privilégios de administrador delegados). Conceitualmente funciona da seguinte maneira:Apart from pre-consented access to all your customer tenants, partner-managed apps have one additional capability. It allows for your agents to use your app to access your customers' tenant data (using delegated admin privileges). Conceptually it works like this:

  1. Seu agente entra em seu aplicativo com suas credenciais de usuário emitidas no locatário do parceiro.Your agent signs in to your app with their user credentials issued from your partner tenant.
  2. O aplicativo solicita um token de acesso para o locatário do cliente gerenciado por parceiros pretendido.Your app requests an access token for the intended partner-managed customer tenant.
  3. O aplicativo usa o token de acesso para chamar o Microsoft Graph.Your app uses the access token to call Microsoft Graph.

Este é um fluxo de concessão de código de autorização padrão, exceto que seus agentes precisam se conectar usando suas contas do parceiro. Para ver como isso ficaria, imagine que o locatário de seu parceiro fosse parceiro.com (que é o locatário principal de seus agentes) e um de seus clientes fosse cliente.com:This is a standard authorization code grant flow, except that your agents must sign-in using their partner accounts. To see how this would look, imagine your partner tenant is partner.com (which is the home tenant for your agents) and one of your customers is customer.com:

  1. Adquira um código de autorização: Seu aplicativo faz uma solicitação para o ponto de extremidade /authorize e precisa usar um locatário de cliente em nosso exemplo customer.com, para o locatário de destino. Seus agentes ainda se conectariam com a conta username@partner.com.Acquire an authorization code: Your app makes a request to the /authorize endpoint and must use a customer tenant, in our example customer.com, for the target tenant. Your agents would still sign-in with their username@partner.com account.

    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:Acquire an access token using the authorization code: Your app must use a customer tenant as the target tenant, in our example customer.com, when making the request to the token endpoint:

    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:Now you have an access token, call Microsoft Graph, putting the access token in the HTTP authorization header:

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

Registre seu aplicativo nas regiões para as quais você oferece suporteRegister your app in the regions you support

Atualmente, o contrato de cliente do CSP encontra-se 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 na qual venderá. 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 dos locatários de parceiros regionais deve manter seu próprio conjunto de aplicativos gerenciados por parceiros para gerenciar clientes dentro da mesma região. Isso pode exigir uma lógica adicional no aplicativo (antes de entrar) para obter o nome de usuário de entrada de seus clientes para decidir qual a identidade de aplicativos gerenciados por parceiros específica da região usar para atender o usuário.CSP customer engagement is currently limited to a single region. Partner-managed applications carry the same limitation. This means you must have a separate tenant for each region you sell in. For example, if your partner-managed app is registered in a tenant in the US but your customer is in the EU – the partner-managed app will not work. Each of your regional partner tenants must maintain their own set of partner-managed apps to manage customers within the same region. This might require additional logic in your app (prior to sign-in) to get your customers' sign-in username to decide which region-specific partner-managed app identity to use, to serve the user.

Chamar o Microsoft Graph imediatamente após a criação do clienteCalling Microsoft Graph immediately after customer creation

Quando você cria um novo cliente usando a API do Partner Center, é criado um novo locatário do cliente. Além disso, uma relação de parceiro também é criada, que torna você o parceiro de registro deste novo locatário do cliente. Essa relação de parceiro pode levar até 3 minutos para ser propagada para o novo locatário do cliente. Se seu aplicativo chamar o Microsoft Graph logo após a criação, é provável que seu aplicativo receba um erro de acesso negado. Um atraso semelhante poderá ocorrer quando um cliente existente aceitar o convite. Isso ocorre porque o consentimento prévio depende da relação de parceiro estar presente no locatário do cliente.When you create a new customer using the Partner Center API, a new customer tenant gets created. Additionally, a partner relationship also gets created, which makes you the partner of record for this new customer tenant. This partner relationship can take up to 3 minutes to propagate to the new customer tenant. If your app calls Microsoft Graph straight after creation, your app will likely receive an access denied error. A similar delay may be experienced when an existing customer accepts your invitation. This is because pre-consent relies on the partner relationship being present in the customer tenant.

Para evitar esse problema, recomendamos que seu aplicativo de parceiro aguarde três minutos após a criação do cliente antes de chamar o Azure AD para obter um token (para chamar o Microsoft Graph).To avoid this problem, we recommend that your partner app should wait three minutes after customer creation before calling Azure AD to acquire a token (to call Microsoft Graph). Isso deve abranger a maioria dos casos.This should cover most cases. No entanto, se após esperar três minutos ainda receber um erro de autorização, aguarde mais 60 segundos e tente novamente.However, if after waiting three minutes you still receive an authorization error, please wait an additional 60 seconds and try again.

Observação: Na repetição, você deve adquirir um novo token de acesso do Azure AD antes de chamar o Microsoft Graph. Não adiantará chamar o Microsoft Graph com o token de acesso que você já tem porque o token de acesso serve para uma hora e não conterá as declarações de permissão pré-autorizadas.Note: On the retry, you must acquire a new access token from Azure AD, before calling Microsoft Graph. Calling Microsoft Graph with the access token you already have will not work, because the access token is good for an hour and won’t contain the pre-consented permission claims.