Aufrufen von Microsoft Graph aus einer Anwendung eines Cloud-LösungsanbietersCall Microsoft Graph from a Cloud Solution Provider application

Hinweis: Dieses Thema gilt nur für Microsoft CSP-Anwendungsentwickler (Cloud-Lösungsanbieter). Das Programm Microsoft Cloud-Lösungsanbieter (CSP) ermöglicht es Microsoft-Partnern, Microsoft Onlinedienste an Kunden zu verkaufen und zu verwalten.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.

In diesem Thema wird beschrieben, wie Sie Anwendungszugriff auf partnerverwaltete Kundendaten über Microsoft Graph aktivieren, entweder mit dem Fluss zur Erteilung von Autorisierungscodes oder dem Fluss zur Gewährung von Clientanmeldeinformationen für Dienst-zu-Dienst-Aufrufe.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.

Wichtig: Das Aufrufen von Microsoft Graph aus einer CSP-Anwendung wird nur für Verzeichnisressourcen (z. B. user, group,device, organization) und Intune-Ressourcen unterstützt.Important: Calling Microsoft Graph from a CSP application is only supported for directory resources (such as user, group,device, organization) and Intune resources.

Was ist eine partnerverwaltete Anwendung?What is a partner-managed application

Das CSP-Programm ermöglicht es Microsoft-Partnern, Microsoft-Onlinedienste (z. B. Office 365, Microsoft Azure und CRM Online) an Kunden zu verkaufen und zu verwalten. Die Verwaltung von Kundendiensten erfolgt über delegierte Administratorberechtigungen, wodurch festgelegte Partnerbenutzer (als Agenten bezeichnet) auf die Umgebungen ihrer Kunden zugreifen und diese konfigurieren können.The CSP program enables Microsoft’s partners to resell and manage Microsoft Online Services (such as Office 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.

Darüber hinaus können Sie als Partnerentwickler eine partnerverwaltete App zum Verwalten der Microsoft-Dienste Ihrer Kunden erstellen. Partnerverwaltete Apps werden oft als vorab genehmigte Apps bezeichnet, da alle Ihre Kunden automatisch vorab für Ihre partnerverwalteten Apps genehmigt werden. Dies bedeutet Folgendes: Wenn ein Benutzer aus einem Ihrer Kundenmandanten eine Ihrer partnerverwalteten Apps verwendet, kann der Benutzer die App nutzen, ohne dass er zur Zustimmung aufgefordert wird. Partnerverwaltete Apps erben außerdem delegierte Administratorberechtigungen, sodass Ihre Partneragenten über Ihre partnerverwaltete Anwendung ebenfalls privilegierten Zugriff auf Ihre Kunden erhalten.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.

Einrichten einer partnerverwalteten AnwendungHow to set-up a partner-managed application

Eine Anwendung wird als partnerverwaltet betrachtet, wenn ihr erhöhte Rechte zum Zugreifen auf die Daten Ihrer Kunden gewährt werden.An application is viewed as partner-managed when it is granted elevated permissions to access your customers' data.

Hinweis: Partnerverwaltete Apps können nur auf Partnermandanten konfiguriert werden, und zum Verwalten von Ressourcen des Kundenmandanten müssen partnerverwaltete Apps als mehrinstanzenfähige Anwendungen konfiguriert werden.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.

Registrieren und Konfigurieren einer mehrinstanzenfähigen AppRegister and configure a multi-tenant app

Die ersten hier erforderlichen Schritte entsprechen weitgehend den Schritten zum Registrieren und Konfigurieren einer mehrinstanzenfähigen Anwendung:The initial steps required here follow most of the same steps used to register and configure a multi-tenant application:

  1. Registrieren Sie die Anwendung in Ihrem Partnermandanten über das Azure-Portal. Um als partnerverwaltete App ausgeführt werden zu können, muss eine Anwendung als mehrinstanzenfähige App konfiguriert werden. Falls Ihre App in mehreren geografische Regionen bereitgestellt und verkauft wird, müssen Sie Ihre App außerdem in jeder dieser Regionen registrieren, wie hier beschrieben.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. Konfigurieren Sie Ihre mehrinstanzenfähige App über das Azure-Portal mit den erforderlichen Berechtigungen; verwenden Sie einen Ansatz geringster Rechte.Configure your multi-tenant app, again through the Azure Portal, with the required permissions it needs using a least privileged approach.

Zum Schluss gewähren Sie Ihrer partnerverwalteten App diese konfigurierten Berechtigungen für alle Ihre Kunden. Hierzu können Sie den servicePrincipal, der die App darstellt, mithilfe von Azure AD PowerShell V2 zur Gruppe Adminagents in Ihrem Partnermandanten hinzufügen. Sie können Azure AD PowerShell V2 hier herunterladen und installieren. Führen Sie die folgenden Schritte aus, um die Gruppe Adminagents und den servicePrincipal zu suchen und ihn zur Gruppe hinzuzufügen.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. Öffnen Sie eine PowerShell-Sitzung und stellen Sie eine Verbindung mit Ihrem Partnermandanten her, indem Sie Ihre Administrator-Anmeldeinformationen in das Anmeldefenster eingeben.Open a PowerShell session and connect to your partner tenant by entering your admin credentials into the sign-in window.

    Connect-AzureAd
    
  2. Suchen Sie die Gruppe, die die Adminagents darstellt.Find the group that represents the Adminagents.

    $group = Get-AzureADGroup -Filter "displayName eq 'Adminagents'"
    
  3. Suchen Sie den Dienstprinzipal, der die gleiche appId hat wie Ihre App.Find the service principal that has the same appId as your app.

    $sp = Get-AzureADServicePrincipal -Filter "appId eq '{yourAppsAppId}'"
    
  4. Fügen Sie zum Schluss den Dienstprinzipal zur Gruppe Adminagents hinzu.Finally, add the service principal to the Adminagents group.

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

TokenerwerbsflüsseToken acquisition flows

Die Tokenerwerbsflüsse für partnerverwaltete Apps – Fluss zur Erteilung von Autorisierungscodes und Fluss zur Gewährung von Clientanmeldeinformationen für Dienst-zu-Dienst-Aufrufe – sind dieselben wie für normale mehrinstanzenfähige Apps.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.

Abgesehen vom vorab genehmigten Zugriff auf alle Ihre Kundenmandanten haben partnerverwaltete Apps eine zusätzliche Fähigkeit. Sie ermöglicht es Ihren Agenten, mit Ihrer App auf Mandantendaten Ihres Kunden zuzugreifen (mit delegierten Administratorrechten). Im Prinzip funktioniert es wie folgt: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. Der Agent meldet sich mit seinen Benutzeranmeldeinformationen, die von Ihrem Partnermandanten ausgestellt wurden, bei Ihrer App an.Your agent signs in to your app with their user credentials issued from your partner tenant.
  2. Die App fordert ein Zugriffstoken für den gewünschten partnerverwalteten Kundenmandanten an.Your app requests an access token for the intended partner-managed customer tenant.
  3. Die App ruft unter Verwendung des Zugriffstokens Microsoft Graph auf.Your app uses the access token to call Microsoft Graph.

Dies ist ein standardmäßiger Fluss zur Erteilung von Autorisierungscodes, mit der Ausnahme, dass Ihre Agenten sich mit ihren Partnerkonten anmelden müssen. Um anzuzeigen, wie dies aussieht, stellen Sie sich vor, Ihr Partnermandant ist partner.com (dies ist die Startmandant für Ihre Agenten) und einer Ihrer Kunden ist customer.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. Autorisierungscode erwerben: Die App sendet eine Anforderung an den Endpunkt /authorize und muss einen Kundenmandanten, in unserem Beispiel customer.com, als Mandantenziel verwenden. Ihre Agenten melden sich weiterhin mit ihrem username@partner.com-Konto an.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. Zugriffstoken mithilfe des Autorisierungscodes erwerben: Ihre App muss einen Kundenmandanten als Zielmandanten verwenden, in unserem Beispiel customer.com, wenn sie die Anforderung an den Endpunkt token sendet: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. Nachdem Sie jetzt über ein Zugriffstoken verfügen, rufen Sie Microsoft Graph auf, und fügen Sie das Zugriffstoken in den HTTP-Autorisierungsheader ein: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>
    

Registrieren Ihrer App in den von Ihnen unterstützten RegionenRegister your app in the regions you support

Die Kundenbeteiligung am CSP-Programm ist derzeit auf eine einzige Region beschränkt. Für partnerverwaltete Anwendungen gilt dieselbe Einschränkung. Dies bedeutet, dass Sie einen separaten Mandanten für jede Regionen benötigen, in der Sie verkaufen. Wenn Ihre partnerverwaltete App beispielsweise in einem Mandanten in den USA registriert ist, Ihr Kunde aber in der EU sitzt, funktioniert die partnerverwaltete App nicht. Jeder Ihrer regionalen Partnermandanten muss einen eigenen Satz partnerverwalteter Apps pflegen, um Kunden innerhalb der gleichen Region zu verwalten. Dies erfordert möglicherweise zusätzliche Logik in Ihrer App (vor der Anmeldung) zum Abrufen des Anmeldebenutzernamen Ihres Kunden, um zu entscheiden, welche regionsspezifische partnerverwaltete App-Identität für den Benutzer verwendet werden soll.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.

Aufrufen von Microsoft Graph sofort nach dem Erstellen des KundenCalling Microsoft Graph immediately after customer creation

Wenn Sie einen neuen Kunden mit der Partner Center-API erstellen, wird ein neuer Kundenmandant erstellt. Darüber hinaus wird eine Partnerbeziehung erstellt, wodurch Sie zum gespeicherten Partner dieses neuen Kundenmandanten werden. Es kann bis zu drei Minuten dauern, bis diese Partnerbeziehung an den neuen Kundenmandanten verteilt wird. Wenn Ihre App Microsoft Graph direkt nach der Erstellung aufruft, erhält die App wahrscheinlich die Fehlermeldung, dass der Zugriff verweigert wurde. Eine ähnliche Verzögerung kann eintreten, wenn ein bestehender Kunde Ihre Einladung akzeptiert. Dies liegt daran, dass die Vorabzustimmung davon abhängt, dass die Partnerbeziehung im Kundenmandanten vorhanden ist.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.

Um dieses Problem zu vermeiden, wird empfohlen, dass die Partner-App nach der Kundenerstellung drei Minuten warten sollte, bevor sie Azure AD zum Erwerb eines Tokens (für den Aufruf von Microsoft Graph) aufruft.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). Hiermit sollten die meisten Fälle abgedeckt sein.This should cover most cases. Wenn jedoch nach Verstreichen der Wartezeit von drei Minuten weiterhin ein Autorisierungsfehler ausgegeben wird, warten Sie weitere 60 Sekunden, und versuchen Sie es erneut.However, if after waiting three minutes you still receive an authorization error, please wait an additional 60 seconds and try again.

Hinweis: Bei der Wiederholung müssen Sie ein neues Zugriffstoken von Azure AD erwerben, bevor Sie Microsoft Graph aufrufen. Der Aufruf von Microsoft Graph mit dem bereits vorhandenen Zugriffstoken funktioniert nicht, da das Zugriffstoken nur eine Stunde lang gültig ist und die vorab genehmigten Berechtigungsansprüche nicht enthält.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.