Erste Schritte mit den Office 365-Verwaltungs-APIsGet started with Office 365 Management APIs

Wenn Sie eine Anwendung erstellen, die Zugriff auf gesicherte Dienste wie die Office 365-Management-APIs benötigt, müssen Sie dem Dienst mitteilen, dass Ihre Anwendung Zugriffsrechte hat.When you create an application that needs access to secured services like the Office 365 Management APIs, you need to provide a way to let the service know if your application has rights to access it. Die Office 365-Management-APIs verwenden Azure AD, um Authentifizierungsdienste bereitzustellen, mit denen Sie der Anwendung entsprechende Rechte für den Zugriff auf diese Dienste erteilen können.The Office 365 Management APIs use Azure AD to provide authentication services that you can use to grant rights for your application to access them.

Es gibt vier zentrale Schritte:There are four key steps:

  1. Registrieren Sie Ihre Anwendung in Azure AD.Register your application in Azure AD. Um Ihrer Anwendung den Zugriff auf die Office 365-Management-APIs zu ermöglichen, müssen Sie Ihre Anwendung bei Azure AD registrieren.To allow your application access to the Office 365 Management APIs, you need to register your application in Azure AD. Dadurch können Sie eine Identität für Ihre Anwendung einrichten und geben die Berechtigungsstufen angeben, die sie für den Zugriff auf die APIs benötigt.This allows you to establish an identity for your application and specify the permission levels it needs to access the APIs.

  2. Erhalten Sie die Genehmigung durch einen Office 365-Mandanten-Admin.Get Office 365 tenant admin consent. Ein Office 365-Mandanten-Admin muss eine Genehmigung erteilen, damit Ihre Anwendung auf mittels Office 365-Management-APIs auf Mandantendaten zugreifen kann.An Office 365 tenant admin must explicitly grant consent to allow your application to access their tenant data by means of the Office 365 Management APIs. Der Genehmigungsprozess ist eine browserbasierte Praxis, bei der sich der Mandantenadministrator in der Azure AD Genehmigung-Benutzeroberfläche anmelden und die von Ihrer Anwendung angeforderten Berechtigungen überprüfen muss und diese Anfrage gewährt oder verweigert.The consent process is a browser-based experience that requires the tenant admin to sign in to the Azure AD consent UI and review the access permissions that your application is requesting, and then either grant or deny the request. Nachdem die Genehmigung erteilt wurde, leitet die Benutzeroberfläche den Benutzer über einen Authentifizierungscode in der URL zurück zu Ihrer Anwendung.After consent is granted, the UI redirects the user back to your application with an authorization code in the URL. Ihre Anwendung führt einen Dienst-zu-Dienst-Anruf zu Azure AD durch, um diesen Autorisierungscode in ein Zugriffs-Token umzuwandeln, das Informationen über den Mandantenadministrator und Ihre Anwendung enthält.Your application makes a service-to-service call to Azure AD to exchange this authorization code for an access token, which contains information about both the tenant admin and your application. Die Mandanten-ID muss aus dem Zugriffstoken entnommen werden und für die zukünftige Nutzung aufbewahrt werden.The tenant ID must be extracted from the access token and stored for future use.

  3. Fordern Sie ein Zugriffstoken von Azure AD an.Request access tokens from Azure AD. Mit den in Azure Active Directory konfigurierten Anmeldeinformationen Ihrer Anwendung fordert Ihre Anwendung fortlaufend zusätzliche Zugriffstoken für einen genehmigten Mandanten an, ohne dass eine weitere Interaktion mit einem Mandantenadministrator benötigt wird.Using your application's credentials as configured in Azure AD, your application requests additional access tokens for a consented tenant on an ongoing basis, without the need for further tenant admin interaction. Diese Zugriffstoken werden als „nur App“-Token bezeichnet, da sie keine Informationen zum Mandantenadministrator beinhalten.These access tokens are called app-only tokens because they do not include information about the tenant admin.

  4. Rufen Sie die Office 365-Management-APIs auf.Call the Office 365 Management APIs. Die „nur App“-Zugriffstoken werden an die Office 365-Management-APIs übergeben, um Ihre Anwendung zu authentifizieren und zu autorisieren.The app-only access tokens are passed to the Office 365 Management APIs to authenticate and authorize your application.

Das folgende Diagramm zeigt die Abfolge von Genehmigungs- und Zugriffstoken-Anfragen.The following diagram shows the sequence of consent and access token requests.

Initialer Authorisierungsvorgang für Verwaltungs-APIs

Wichtig

Bevor Sie über die Office 365-Verwaltungsaktivitäts-API auf Daten zugreifen können, müssen Sie die einheitliche Überwachungsprotokollierung für Ihre Office 365-Organisation aktivieren.Before you can access data through the Office 365 Management Activity API, you must enable unified audit logging for your Office 365 organization. Dazu aktivieren Sie das Office 365-Überwachungsprotokoll.You do this by turning on the Office 365 audit log. Anweisungen hierzu finden Sie unter Aktivieren und Deaktivieren der Office 365-Überwachungsprotokollsuche.For instructions, see Turn Office 365 audit log search on or off.

Wenn Sie nur die Office 365-Dienstkommunikations-API verwenden, ist die Aktivierung der einheitlichen Überwachungsprotokollierung nicht nötig.Enabling unified audit logging isn't required if you're only using the Office 365 Service Communications API.

Registrieren Sie Ihre Anwendung in Azure AD.Register your application in Azure AD

Die Office 365-Management-APIs verwenden Azure AD zur sicheren Authentifizierung der Office 365-Mandantendaten.The Office 365 Management APIs use Azure AD to provide secure authentication to Office 365 tenant data. Für den Zugriff auf die Office 365-Management-APIs müssen Sie die Anwendung in Azure Active Directory registrieren, und als Teil der Konfiguration die Berechtigungsstufen, die Ihre Anwendung für den Zugriff auf die APIs benötigt, angeben.To access the Office 365 Management APIs, you need to register your app in Azure AD, and as part of the configuration, you will specify the permission levels your app needs to access the APIs.

VoraussetzungenPrerequisites

Wenn Sie die Anwendung in Azure AD registriert haben, benötigen Sie ein Abonnement für Office 365 und ein Abonnement für Azure, das mit Ihrem Office 365-Abonnement verknüpft ist.To register your app in Azure AD, you need a subscription to Office 365 and a subscription to Azure that has been associated with your Office 365 subscription. Für den Anfang können Sie Testabonnements sowohl für Office 365 als auch für Azure verwenden.You can use trial subscriptions to both Office 365 and Azure to get started. Weitere Informationen finden Sie unter Willkommen beim Office 365-Entwicklerprogramm.For more details, see Welcome to the Office 365 Developer Program.

Nutzen Sie das Azure-Verwaltungsportal, um Ihre Anwendung in Azure AD zu registrieren.Use the Azure Management Portal to register your application in Azure AD

Nachdem Sie einen Microsoft-Mandanten mit den entsprechenden Abonnements haben, können Sie Ihre Anwendung in Azure AD registrieren.After you have a Microsoft tenant with the proper subscriptions, you can register your application in Azure AD.

  1. Melden Sie sich im Azure-Verwaltungsportal an, und verwenden Sie dabei die Anmeldeinformationen Ihres Microsoft-Mandanten, der über das Office 365-Abonnement verfügt, das Sie verwenden möchten.Sign into the Azure management portal, using the credential of your Microsoft tenant that has the subscription to Office 365 you wish to use. Sie können auf das Azure-Verwaltungsportal auch über einen Link zugreifen, der im linken Navigationsbereich im Office Admin-Portal erscheint.You can also access the Azure Management Portal via a link that appears in the left navigation pane in the Office admin portal.

  2. Klicken Sie im linken Navigationsbereich auf Active Directory (1).In the left navigation panel, choose Active Directory (1). Stellen Sie sicher, dass die Registerkarte Verzeichnis (2) ausgewählt ist, und klicken Sie dann auf den Verzeichnisnamen (3).Make sure the Directory tab (2) is selected, and then select the directory name (3).

    Anmeldeseite für Office 365

  3. Wählen Sie auf der Verzeichnisseite Anwendungen.On the directory page, select Applications. Azure AD zeigt eine Liste der Anwendungen, die aktuell in Ihrem Mandanten installiert sind.Azure AD displays a list of the applications currently installed in your tenancy.

  4. Wählen Sie Hinzufügen aus.Choose Add.

    Verwaltungsseite für Office 365

  5. Wählen Sie Add an application my organization is developing aus.Select Add an application my organization is developing.

  6. Geben Sie den Namen Ihrer Anwendung ein, und geben Sie für den Typ WEB-ANWENDUNG UND/ODER WEB-API an.Enter the NAME of your application and specify the Type as WEB APPLICATION AND/OR WEB API.

  7. Geben Sie die entsprechenden Eigenschaften der App ein:Enter the appropriate App properties:

    • Anmelde-URL.SIGN-ON URL. Die URL, mit der Benutzer sich anmelden und Ihre Anwendung verwenden können.The URL where users can sign in and use your app. Sie können dies später bei Bedarf ändern.You can change this later as needed.

    • App-ID-URI.APP ID URI. Der URI, der als ein eindeutiger logischer Identifikator verwendet wird.The URI used as a unique logical identifier for your app. Der URI muss sich in einer überprüften benutzerdefinierten Domäne für einen externen Benutzer befinden, um Ihrer Anwendung Zugriff auf seine Daten in Windows Azure Active Directory zu gewähren.The URI must be in a verified custom domain for an external user to grant your app access to their data in Windows Azure AD. Wenn Ihr Microsoft-Mandant z. B. contoso.onmicrosoft.com ist, könnte die APP-ID URI https://app.contoso.onmicrosoft.com sein.For example, if your Microsoft tenant is contoso.onmicrosoft.com, the APP ID URI could be https://app.contoso.onmicrosoft.com.

  8. Die app ist jetzt mitIhre Anwendung ist jetzt für Azure AD registriert und wurde einer Client-ID zugewieden.Your app is now registered with Azure AD, and has been assigned a client ID. Es gibt jedoch weitere wichtige Aspekte Ihrer Anwendung, die konfiguriert werden müssen.However, there are several important aspects of your app left to configure.

Konfigurieren Sie Ihre Anwendungseigenschaften in Azure ADConfigure your application properties in Azure AD

Nachdem Ihre Anwendung registriert ist, gibt es mehrere wichtige Eigenschaften, die Sie angeben müssen, die bestimmen, wie Ihre Anwendung in Azure AD funktioniert und wie Mandantenadministratoren Ihrer Anwendung die Genehmigung für den Zugriff auf ihre Daten mittels den Office 365-Management-APIs erteilen.Now that your application is registered, there are several important properties you must specify that determine how your application functions within Azure AD and how tenant admins will grant consent to allow your application to access their data by using the Office 365 Management APIs.

Weitere Informationen zur Anwensungskonfiguration in Azure AD im Allgemeinen finden Sie unter Anwendungs-Objekteigenschaften.For more information about Azure AD application configuration in general, see Application Object Properties.

  1. CLIENT-ID.CLIENT ID. Dieser Wert wird von Azure AD automatisch generiert.This value is automatically generated by Azure AD. Ihre Anwendung wird diesen Wert beim Anfordern von Genehmigungen von Mandantenadministratoren und beim Anfordern von „Nur App“-Token aus Azure AD verwenden.Your application will use this value when requesting consent from tenant admins and when requesting app-only tokens from Azure AD.

  2. ANWENDUNG HAT MEHRERE MANDANTEN.APPLICATION IS MULTI-TENANT. Für diese Eigenschaft muss Ja ausgewählt werden, damit Mandantenadministratoren Ihrer Anwendung die Genehmigung erteilen können, mit den Office 365-Management-APIs auf ihre Daten zuzugreifen.This property must be set to YES to allow tenant admins to grant consent to your app to access their data by using the Office 365 Management APIs. Wenn für diese Eigenschaft Nein ausgewählt ist, kann Ihre Anwendung ausschließlich auf Daten Ihres eigenen Mandanten zugreifen.If this property is set to NO, your application will only be able to access your own tenant's data.

  3. ANTWORT-URL.REPLY URL. Dies ist die URL, zu der ein Mandantenadministrator weitergeleitet wird, nachdem er Ihrer Anwendung die Genehmigung für den Zugriff auf seine Daten mittels den Office 365 Management-APIs erteilt hat.This is the URL that a tenant admin will be redirected to after granting consent to allow your application to access their data by using the Office 365 Management APIs. Sie können bei Bedarf mehrere Antwort-URLs konfigurieren.You can configure multiple reply URLs as needed. Azure legt automatisch die erste so fest, dass sie mit der Anmelde-URL übereinstimmt, die Sie beim Erstellen der Anwendung angegeben haben, aber Sie können diesen Wert wenn nötig ändern.Azure automatically sets the first one to match the sign-on URL you specified when you created the application, but you can change this value as needed.

Wählen Sie unbedingt Speichern, nachdem Sie Änderungen an dieser Eigenschaften vorgenommen haben.Be sure to choose Save after making any changes to these properties.

Erstellen Sie einen neuen Schlüssel für Ihre AnwendungGenerate a new key for your application

Schlüssel werden auch als geheime Clientschlüssel bezeichnet und werden verwendet, ein Autorisierungscode gegen eine Zugriffstoken ausgetauscht wird.Keys, also known as client secrets, are used when exchanging an authorization code for an access token.

  1. Wählen Sie im Azure Verwaltungsportal Ihre Anwendung und wählen Sie konfigurieren im oberen Menü.In the Azure Management Portal, select your application and choose Configure in the top menu. Blättern Sie nach unten zu Schlüssel.Scroll down to keys.

  2. Wählen Sie die Gültigkeitsdauer Ihres Schlüssels, und wählen Sie Speichern.Select the duration for your key, and choose Save.

    Azure-Seite "Abonnieren"

  3. Azure zeigt den App-Schlüssel nur nach dem Speichern an.Azure displays the app secret only after saving it. Klicken Sie auf das Symbol Zwischenablage, um das Client-Geheimnis in die Zwischenablage zu kopieren.Select the Clipboard icon to copy the client secret to the Clipboard.

    Azure-Seite "Portal"

    Wichtig

    Azure zeigt das Client-Geheimnis nur zum Zeitpunkt der ersten Generierung an.Azure only displays the client secret at the time you initially generate it. Sie können nicht zu dieser Seite zurücknavigieren und den geheimen Clientschlüssel später abrufen.You cannot navigate back to this page and retrieve the client secret later.

Konfigurieren eines x. 509-Zertifikats, um Dienst-zu-Dienst-Aufrufe zu ermöglichenConfigure an X.509 certificate to enable service-to-service calls

Eine Anwendung, die im Hintergrund ausgeführt wird, wie ein Dämonprozess oder ein Dienst, kann Client-Anmeldeinformationen nutzen, um ein „Nur App“-Zugriffstoken anzufordern, ohne fortlaufend eine Genehmigung vom Mandantenadministrator anzufordern, nachdem eine erste Genehmigung erteilt wurde.An application that is running in the background, such as a daemon or service, can use client credentials to request app-only access tokens without repeatedly requesting consent from the tenant admin after initial consent is granted.

Weitere Informationen finden Sie unter Dienst-zu-Dienst-Anrufe mithilfe von Client-Anmeldeinformationen.For more information, see Service to Service Calls Using Client Credentials.

Sie müssen ein X.509-Zertifikat für Ihre Anwendung erstellen, das als Client-Anmeldedaten dient, wenn ein „Nur App“-Token von Azure AD angefordert wird.You must configure an X.509 certificate with your application to be used as client credentials when requesting app-only access tokens from Azure AD. Dieser Prozess besteht aus zwei Schritten:There are two steps to the process:

  • Abrufen eines X.509-Zertifikats.Obtain an X.509 certificate. Sie können ein selbstsigniertes Zertifikat oder ein von einer öffentlichen, vertrauenswürdigen Zertifizierungsstelle ausgestelltes Zertifikat verwenden..You can use a self-signed certificate or a certificate issued by publicly trusted certificate authority.

  • Ändern Sie Ihr Anwendungsmanifest, um den Fingerabdruck und den öffentlichen Schlüssel Ihres Zertifikats einzuschließen.Modify your application manifest to include the thumbprint and public key of your certificate.

Die folgenden Anweisungen zeigen Ihnen, wie Sie das Visual Studio oder das Windows SDK _Makecert_tool verwenden, um ein selbstsigniertes Zertifikat zu erstellen und den öffentlichen Schlüssel in eine base64-codierte Datei zu exportieren.The following instructions show you how to use the Visual Studio or Windows SDK makecert tool to generate a self-signed certificate and export the public key to a base64-encoded file.

  1. Führen Sie in der Befehlszeile Folgendes aus:From the command line, run the following:

     makecert -r -pe -n "CN=MyCompanyName MyAppName Cert" -b 03/15/2015 -e 03/15/2017 -ss my -len 2048
    

    Hinweis

    Wenn Sie das x. 509-Zertifikat generieren, stellen Sie sicher, dass die Länge des Schlüssels mindestens 2048 beträgt.When you are generating the X.509 certificate, make sure the key length is at least 2048. Kürzere Schlüssellängen werden nicht als gültige Schlüssel akzeptiert.Shorter key lengths are not accepted as valid keys.

  2. Öffnen Sie die Snap-In MMC-Zertifikate und verbinden Sie sich mit Ihrem Benutzerkonto.Open the Certificates MMC snap-in and connect to your user account.

  3. Suchen Sie das neue Zertifikat im Persönlichen Ordner und exportieren Sie den öffentlichen Schlüssel in eine base64-codierte Datei (z. B. mycompanyname.cer).Find the new certificate in the Personal folder and export the public key to a base64-encoded file (for example, mycompanyname.cer). Ihre Anwendung verwendet dieses Zertifikat zum Kommunizieren mit Azure AD. Stellen Sie daher sicher, dass Sie auch Zugriff auf den privat Schlüssel erhalten.Your application will use this certificate to communicate with Azure AD, so make sure you retain access to the private key as well.

    Hinweis

    Sie können Windows PowerShell verwenden, um den Fingerabdruck und den base64-codierten öffentlichen Schlüssel zu extrahieren.You can use Windows PowerShell to extract the thumbprint and base64-encoded public key. Andere Plattformen bieten ähnliche Tools zum Abrufen der Eigenschaften von Zertifikaten.Other platforms provide similar tools to retrieve properties of certificates.

  4. Geben Sie in der Windows PowerShell-Eingabeaufforderung Folgendes ein und führen Sie es aus:From the Windows PowerShell prompt, type and run the following:

     $cer = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2
     $cer.Import("mycer.cer")
     $bin = $cer.GetRawCertData()
     $base64Value = [System.Convert]::ToBase64String($bin)
     $bin = $cer.GetCertHash()
     $base64Thumbprint = [System.Convert]::ToBase64String($bin)
     $keyid = [System.Guid]::NewGuid().ToString()
    
  5. Speichern Sie die Werte für $base64Thumbprint, $base64Value, und $keyid, die verwendet werden, wenn Sie Ihr Anwendungsmanifest in den nächsten Schritten aktualisieren.Store the values for $base64Thumbprint, $base64Value, and $keyid to be used when you update your application manifest in the next set of steps.

    Mit den aus dem Zertifikat extrahierten Werten und der generierten Schlüssel-ID müssen Sie nun Ihr Anwendungsmanifest in Azure AD aktualisieren.Using the values extracted from the certificate and the generated key ID, you must now update your application manifest in Azure AD.

  6. Wählen Sie im Azure Verwaltungsportal Ihre Anwendung und wählen Sie konfigurieren im oberen Menü.In the Azure Management Portal, select your application and choose Configure in the top menu.

  7. Wählen Sie in der Befehlsleiste **Manifest verwalten **, und wählen Sie dann Manifest herunterladen.In the command bar, choose Manage manifest, and then choose Download Manifest.

    Anzeige des Kommandozeilenzertifikats

  8. Öffnen Sie das heruntergeladene Manifest zur Bearbeitung und ersetzen Sie die leere KeyCredentials -Eigenschaft durch die folgende JSON:Open the downloaded manifest for editing and replace the empty KeyCredentials property with the following JSON:

       "keyCredentials": [
         {
             "customKeyIdentifier" : "$base64Thumbprint_from_above",
             "keyId": "$keyid_from_above",
             "type": "AsymmetricX509Cert",
             "usage": "Verify",
             "value": "$base64Value_from_above"
         }
     ],
    

    Hinweis

    Die KeyCredentials-Eigenschaft ist eine Sammlung, die es ermöglicht, mehrere X.509-Zertifikate für Rollover-Szenarien hochzuladen oder Zertifikate für Kompromiss-Szenarien zu löschen.The KeyCredentials property is a collection, making it possible to upload multiple X.509 certificates for rollover scenarios or delete certificates for compromise scenarios.

  9. Speichern Sie Ihre Änderungen und laden Sie die aktualisierte App-Manifestdatei hoch, indem Sie auf Manifest verwalten in der Befehlsleiste klicken, Manifest hochladenwählen, zu Ihrer aktualisierten Manifestdatei navigieren und diese dann auswählen.Save your changes and upload the updated manifest by choosing Manage manifest in the command bar, choosing Upload manifest, browsing to your updated manifest file, and then selecting it.

Geben Sie die Berechtigungen, die Ihre Anwnedung benötigt, um auf die Office 365-Management-APIs zuzugreifen, an.Specify the permissions your app requires to access the Office 365 Management APIs

Schließlich müssen Sie genau angeben, welche Berechtigungen Ihre Anwendung für die Office 365 Management-APIs benötigt.Finally, you need to specify exactly what permissions your app requires of the Office 365 Management APIs. Zu diesem Zweck müssen Sie einen Zugriff auf die Office 365-Management-APIs zu Ihrer Anwendung hinzufügen und dann die Berechtigung(en) auswählen, die Sie benötigen.To do so, you add access to the Office 365 Management APIs to your app, and then you specify the permission(s) you need.

  1. Wählen Sie im Azure Verwaltungsportal Ihre Anwendung und wählen Sie konfigurieren im oberen Menü.In the Azure Management Portal, select your application, and choose Configure in the top menu. Scrollen Sie nach unten zu Berechtigungen für andere Anwendungen und wählen Sie Anwendung hinzufügen aus.Scroll down to permissions to other applications, and choose Add application.

    Azure AD-Seite

  2. Wählen Sie die Office 365-Management-APIs (1) so, dass sie in der ausgewählter Spalte (2) angezeigt werden, und wählen Sie dann das Häkchen unteren rechts (3), um Ihre Auswahl zu speichern und zurück zu Haupt-Konfigurationsseite Ihrer Anwendung zu gelangen.Select the Office 365 Management APIs (1) so that it appears in the Selected column (2), and then select the check mark in the lower right (3) to save your selection and return to the main configuration page for your application.

    Azure AD-Seite "Apps"

  3. Die Office-Management-APIs werden jetzt in der Liste der Anwendungen angezeigt, für die Ihre Anwendung Berechtigungen benötigt.The Office Management APIs now appear in the list of applications to which your application requires permissions. Wählen Sie sowohl unter Anwendungsberechtigungen als auch unter delegierte Berechtigungen die Berechtigungen aus, die Ihre Anwendung benötigt.Under both Application Permissions and Delegated Permissions, select the permissions your application requires. Weitere Informationen zu den einzelnen Berechtigungen finden Sie unter den jeweiligen API-Referenzen.Refer to the specific API reference for more details about each permission.

    Hinweis

    Vier Berechtigungen für Aktivitätsberichte und Informationen zu Bedrohungen werden derzeit nicht verwendet und werden zukünftig entfernt.There are currently four unused permissions related to activity reports and threat intelligence that will be removed in the future. Aktivieren Sie keine der folgenden Berechtigungen, da sie nicht erforderlich sind.Do not select any of these permissions because they are unnecessary.

    Dialogfeld "Eine Anwendung hinzufügen"

  4. Klicken Sie auf Speichern, um die Konfiguration zu speichern.Choose Save to save the configuration.

Nun, da Ihre Anwendung mit den Berechtigungen konfiguriert ist, die sie für die Verwendung der Office 365-Management APIs benötigt, muss ein Mandantenadministrator diese Berechtigungen ausdrücklich für Ihre Anwendung gewähren, damit Sie mittels der APIs auf dessen Mandantendaten zugreifen können.Now that your application is configured with the permissions it needs to use the Office 365 Management APIs, a tenant admin must explicitly grant your application these permissions in order to access their tenant's data by using the APIs. Um eine Genehmigung zu erteilen, muss sich der Mandantenadministrator in Azure AD anmelden. Dafür verwendet er die folgende eigens konstruierte URL, mittels derer er die von Ihrer Anwendung angefragten Berechtigungen einsehen kann.To grant consent, the tenant admin must sign in to Azure AD by using the following specially constructed URL, where they can review your application's requested permissions. Dieser Schritt ist nicht erforderlich, wenn Sie APIs verwenden, um auf Daten aus Ihrem eigenen Mandanten zuzugreifen.This step is not required when using the APIs to access data from your own tenant.

https://login.windows.net/common/oauth2/authorize?response_type=code&resource=https%3A%2F%2Fmanage.office.com&client_id={your_client_id}&redirect_uri={your_redirect_url }

Die Weiterleitungs-URL muss mit der Antwort-URL übereinstimmen oder ein untergeordneter Pfad einer der Antwort-URLs sein, die für Ihre Anwendung in Azure AD erstellt wurden.The redirect URL must match or be a sub-path under one of the Reply URLs configured for your application in Azure AD.

Beispiel:For example:

https://login.windows.net/common/oauth2/authorize?response_type=code&resource=https%3A%2F%2Fmanage.office.com&client_id=2d4d11a2-f814-46a7-890a-274a72a7309e&redirect_uri=http%3A%2F%2Fwww.mycompany.com%2Fmyapp%2F

Sie können die genehmigte URL testen, indem Sie diese in einen Browser kopieren und sich mit den Anmeldedaten eines Office 365-Admin für einen anderen Mandanten, als der, den Sie für die Registrierung der Anwendung verwendet haben, anmelden.You can test the consent URL by pasting it into a browser and signing in using the credentials of an Office 365 admin for a tenant other than the tenant that you used to register the application. Ihnen wird die Anfrage zur Berechtigungserteilung zur Nutzung der Office-Management-APIs für Ihre Anwendung angezeigt.You will see the request to grant your application permission to use the Office Management APIs.

Azure AD-Seite "App hinzugefügt"

Nachdem Sie Annehmen ausgewählt haben, werden Sie zu der angegebenen Seite weitergeleitet und die Abfrage-Zeichenfolge wird einen Code enthalten.After choosing Accept, you are redirected to the specified page, and there will be a code in the query string.

Beispiel:For example:

http://www.mycompany.com/myapp/?code=AAABAAAAvPM1KaPlrEqdFSB...

Ihre Anwendung verwendet diesen Autorisierungscode, um ein Zugriffstoken von Azure AD zu erhalten, aus dem die Mandanten-ID extrahiert werden kann.Your application uses this authorization code to obtain an access token from Azure AD, from which the tenant ID can be extracted. Nachdem Sie die Mandanten-ID extrahiert und gespeichert haben, können Sie nachfolgende Zugriffstoken beziehen, ohne dass eine Anmeldung als Mandantenadministrator notwendig ist.After you have extracted and stored the tenant ID, you can obtain subsequent access tokens without requiring the tenant admin to sign in.

Fordern Sie ein Zugriffstoken von Azure AD an.Request access tokens from Azure AD

Es gibt zwei Methoden, um Zugriffstoken von Azure AD anzufordern:There are two methods for requesting access tokens from Azure AD:

  • Der Genehmigungsprozess mit Autorisierungscode beinhaltet, dass eine Mandantenadministrator seine ausdrückliche Genehmigung erteilt, wodurch ein Autorisierungscode an Ihre Anwendung zurückgegeben wird.The Authorization Code Grant Flow involves a tenant admin granting explicit consent, which returns an authorization code to your application. Ihre Anwendung tauscht dann den Autorisierungscode gegen ein Zugriffstoken aus.Your application then exchanges the authorization code for an access token. Diese Methode ist erforderlich, um die erste Zustimmung dafür zu erhalten, die Ihre Anwendung benötigt, um mittels der API auf Mandantendaten zuzugreifen. Dieses erste Zugriffstoken ist erforderlich, um die Mandanten-ID zu erhalten und zu speichern.This method is required to obtain the initial consent that your application needs to access the tenant data by using the API, and this first access token is needed in order to obtain and store the tenant ID.

  • Die Genehmigungsprozess mit Client-Anmeldedaten ermöglicht es Ihrer Anwendung, nachfolgende Zugriffstoken anzufordern, wenn alte ihre Gültigkeit verlieren, ohne dass der Mandantenadministrator sich anmelden und seine ausdrückliche Zustimmung erteilen muss.The Client Credentials Grant Flow allows your application to request subsequent access tokens as old ones expire, without requiring the tenant admin to sign in and explicitly grant consent. Diese Methode muss für Anwendungen verwendet werden, die fortlaufend im Hintergrund ausgeführt werden, und APIs aufrufen, nachdem die erste Zustimmung durch den Mandantenadministrator erteilt wurde.This method must be used for applications that run continuously in the background calling the APIs once the initial tenant admin consent has been granted.

Zugriffstoken mithilfe des Autorisierungscodes anfordernRequest an access token using the authorization code

Nachdem ein Mandantenadministrator seine Zustimmung erteilt, erhält Ihre Anwendung einen Autorisierungscode als Abfrage-Zeichenfolgeparameter, wenn Azure AD den Mandantenadministrator an die angegebene URL weiterleitet.After a tenant admin grants consent, your application receives an authorization code as a query string parameter when Azure AD redirects the tenant admin to your designated URL.

http://www.mycompany.com/myapp/?code=AAABAAAAvPM1KaPlrEqdFSB...

Ihre Anwendung stelle einen HTTP REST POST an Azure AD, um den Autorisierungscode gegen ein Zugriffstoken auszutauschen.Your application makes an HTTP REST POST to Azure AD to exchange the authorization code for an access token. Da die Mandanten-ID noch nicht bekannt ist, wird der POST an den „herkömmlichen“ Endpunkt gestellt, bei dem die Mandanten-ID nicht in der URL enthalten ist:Because the tenant ID is not yet known, the POST will be to the "common" endpoint, which does not have the tenant ID embedded in the URL:

https://login.windows.net/common/oauth2/token

Der Inhalt des POST enthält Folgendes:The body of the POST contains the following:

resource=https%3A%2F%2Fmanage.office.com&client_id=a6099727-6b7b-482c-b509-1df309acc563 &redirect_uri= http%3A%2F%2Fwww.mycompany.com%2Fmyapp%2F &client_secret={your_client_key}&grant_type=authorization_code&code= AAABAAAAvPM1KaPlrEqdFSB...

BeispielanfrageSample request

POST https://login.windows.net/common/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: login.windows.net
Content-Length: 944

resource=https%3A%2F%2Fmanage.office.com&client_id=a6099727-6b7b-482c-b509-1df309acc563 &redirect_uri= http%3A%2F%2Fwww.mycompany.com%2Fmyapp%2F &client_secret={your_client_key}&grant_type=authorization_code&code=AAABAAAAvPM1KaPlrEqdFSB...

Der Inhalt der Antwort wird einige Eigenschaften enthalten, darunter das Zugriffstoken.The body of the response will include several properties, including the access token.

BeispielantwortSample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 3265

{"expires_in":"3599","token_type":"Bearer","scope":"ActivityFeed.Read ActivityReports.Read ServiceHealth.Read","expires_on":"1438290275","not_before":"1438286375","resource":"https://manage.office.com","access_token":"eyJ0eX...","refresh_token":"AAABAAA...","id_token":"eyJ0eXAi..."}

Das zurückgegebene Zugriffstoken ist ein JWT-Token und enthält Informationen über den Administrator, der seine Zustimmung erteilt hat, und die Anwendung, die Zugriff angefordert hat.The access token that is returned is a JWT token that includes information about both the admin that granted consent and the application requesting access. Es folgt ein Beispiel für ein uncodiertes Token.The following shows an example of an un-encoded token. Ihre Anwendung muss die Mandanten-ID „tid“ aus diesem Token extrahieren und diese speichern, damit sie verwendet werden kann, um weitere Zugriffstoken anzufordern, wenn vorhandene ihre Gültigkeit verlieren, ohne dass eine weitere Interaktion eines Administrators erforderlich ist.Your application must extract the tenant ID "tid" from this token and store it so that it can be used to request additional access tokens as they expire, without further admin interaction.

BeispieltokenSample token

{
  "aud": "https://manage.office.com",
  "iss": "https://sts.windows.net/41463f53-8812-40f4-890f-865bf6e35190/",
  "iat": 1427246416,
  "nbf": 1427246416,
  "exp": 1427250316,
  "ver": "1.0",
  "tid": "41463f53-8812-40f4-890f-865bf6e35190",
  "amr": [
    "pwd"
  ],
  "oid": "1cef1fdb-ff52-48c4-8e4e-dfb5ea83d357",
  "upn": "admin@contoso.onmicrosoft.com",
  "puid": "1003BFFD8EC47CA6",
  "sub": "7XpD5OWAXM1OWmKiVKh1FOkKXV4N3OSRol6mz1pxxhU",
  "given_name": "John",
  "family_name": "Doe",
  "name": "Contoso, Inc.",
  "unique_name": "admin@contoso.onmicrosoft.com",
  "appid": "a6099727-6b7b-482c-b509-1df309acc563",
  "appidacr": "1",
  "scp": "ActivityFeed.Read ServiceHealth.Read",
  "acr": "1"
}

Fordern Sie mit Client-Anmeldeinformationen ein Zugriffstoken anRequest an access token by using client credentials

Sobald die Mandanten-ID bekannt ist, kann Ihre Anwendung Dienst-zu-Dienst-Anrufe zu Azure AD durchführen, um weitere Zugriffstoken anzufordern, wenn vorhandene ihre Gültigkeit verlieren.After the tenant ID is known, your application can make service-to-service calls to Azure AD to request additional access tokens as they expire. Diese Token enthalten ausschließlich Informationen über die anfragende Anwendung und nicht über den Administrator, der die erste Zustimmung erteilt hat.These tokens include information only about the requesting application and not about the admin that originally granted consent. Dienst-zu-Dienst-Aufrufe erfordern, dass Ihre Anwendung ein X.509-Zertifikat verwendet, um Client Assertion in Form eines base64-codierten, SHA256-signierten JWT Bearer-Token zu erstellen.Service-to-service calls require that your application use an X.509 certificate to create client assertion in the form of a base64-encoded, SHA256 signed JWT bearer token.

Wenn Sie die Anwendung in .NET entwickeln, können Sie mithilfe der Azure Active Directory Authentication Library (ADAL) Client Assertions erstellen.When you are developing your application in .NET, you can use the Azure AD Authentication Library (ADAL) to create client assertions. Andere Entwicklungsplattformen sollten ähnliche Bibliotheken haben.Other development platforms should have similar libraries.

Ein nicht codiertes JWT-Token besteht aus einer Kopfzeile und einer Nutzlast, die die folgenden Eigenschaften haben.An un-encoded JWT token consists of a header and payload that have the following properties.

HEADER:

{
  "alg": "RS256",
  "x5t": "{thumbprint of your X.509 certificate used to sign the token",
}

PAYLOAD:

{
  "aud": "https://login.windows.net/{tenantid}/oauth2/token",
  "iss": "{your app client ID}",
  "sub": "{your app client ID}"
  "jti": "{random GUID}",
  "nbf": {epoch time, before which the token is not valid},
  "exp": {epoch time, after which the token is not valid},
}

Beispiel JWT-TokenSample JWT token

HEADER:

{
  "alg": "RS256",
  "x5t": "YyfshJC3rPQ-kpGo5dUaiY5t3iU",
}

PAYLOAD:

{
  "aud": "https://login.windows.net/41463f53-8812-40f4-890f-865bf6e35190/oauth2/token",
  "iss": "a6099727-6b7b-482c-b509-1df309acc563",
  "sub": "a6099727-6b7b-482c-b509-1df309acc563"
  "jti": "0ce254c4-81b1-4a2e-8436-9a8c3b49dfb9",
  "nbf": 1427248048,
  "exp": 1427248648,
}

Die Client Assertion wird dann an Azure AD übergeben als Teil eines Dienst-zu-Dienst-Anrufs, um ein Zugriffstoken anzufordern.The client assertion is then passed to Azure AD as part of a service-to-service call to request an access token. Bei Verwendung der Client-Anmeldeinformationen zur Anforderung eines Zugriffstoken verwenden Sie ein HTTP POST für einen mandantenspezifischen Endpunkt, wo die zuvor extrahierten und gespeicherte Mandanten-ID in der URL eingebettet ist.When using client credentials to request an access token, use an HTTP POST to a tenant-specific endpoint, where the previously extracted and stored tenant ID is embedded in the URL.

https://login.windows.net/{tenantid}/oauth2/token

Der Inhalt des POST enthält Folgendes:The body of the POST contains the following:

resource=https%3A%2F%2Fmanage.office.com&client_id={your_app_client_id}&grant_type=client_credentials&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion={encoded_signed_JWT_token}

BeispielanfrageSample request

POST https://login.windows.net/41463f53-8812-40f4-890f-865bf6e35190/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: login.windows.net
Content-Length: 994

resource=https%3A%2F%2Fmanage.office.com&client_id= a6099727-6b7b-482c-b509-1df309acc563&grant_type=client_credentials &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Ill5ZnNoSkMzclBRLWtwR281ZFVhaVk1dDNpVSJ9.eyJhdWQiOiJodHRwczpcL1wvbG9naW4ud2luZG93cy5uZXRcLzQxNDYzZjUzLTg4MTItNDBmNC04OTBmLTg2NWJmNmUzNTE5MFwvb2F1dGgyXC90b2tlbiIsImV4cCI6MTQyNzI0ODY0OCwiaXNzIjoiYTYwOTk3MjctNmI3Yi00ODJjLWI1MDktMWRmMzA5YWNjNTYzIiwianRpIjoiMGNlMjU0YzQtODFiMS00YTJlLTg0MzYtOWE4YzNiNDlkZmI5IiwibmJmIjoxNDI3MjQ4MDQ4LCJzdWIiOiJhNjA5OTcyNy02YjdiLTQ4MmMtYjUwOS0xZGYzMDlhY2M1NjMifQ.vfDrmCjiXgoj2JrTkwyOpr-NOeQTzlXQcGlKGNpLLe0oh4Zvjdcim5C7E0UbI3Z2yb9uKQdx9G7GeqS-gVc9kNV_XSSNP4wEQj3iYNKpf_JD2ikUVIWBkOg41BiTuknRJAYOMjiuBE2a6Wyk-vPCs_JMd7Sr-N3LiNZ-TjluuVzWHfok_HWz_wH8AzdoMF3S0HtrjNd9Ld5eI7MVMt4OTpRfh-Syofi7Ow0HN07nKT5FYeC_ThBpGiIoODnMQQtDA2tM7D3D6OlLQRgLfI8ir73PVXWL7V7Zj2RcOiooIeXx38dvuSwYreJYtdphmrDBZ2ehqtduzUZhaHL1iDvLlw

Die Antwort wird die gleiche sein wie zuvor, aber das Token wird nicht dieselben Eigenschaften haben, da es keine Eigenschaften des Administrators enthält, der die Zustimmung erteilt hat.The response will be the same as before, but the token will not have the same properties, because it does not contain properties of the admin that granted consent.

BeispielantwortSample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 1276

{"token_type":"Bearer","expires_in":"3599","expires_on":"1431659094","not_before":"1431655194","resource":"https://manage.office.com","access_token":"eyJ0eXAiOiJKV1QiL..."}

Beispiel für ZugriffstokenSample access token

{
  "aud": "https://manage.office.com",
  "iss": "https://sts.windows.net/41463f53-8812-40f4-890f-865bf6e35190/",
  "iat": 1431655194,
  "nbf": 1431655194,
  "exp": 1431659094,
  "ver": "1.0",
  "tid": "41463f53-8812-40f4-890f-865bf6e35190",
  "roles": [
    "ServiceHealth.Read",
    "ActivityFeed.Read"
  ],
  "oid": "67cb0334-e242-4783-8028-0f39132fb5ad",
  "sub": "67cb0334-e242-4783-8028-0f39132fb5ad",
  "idp": "https://sts.windows.net/41463f53-8812-40f4-890f-865bf6e35190/",
  "appid": "a6099727-6b7b-482c-b509-1df309acc563",
  "appidacr": "1"
}

Erstellen Sie Ihre AnwendungBuild your app

Nachdem Sie die Anwendung in Azure AD registriert und die erforderlichen Berechtigungen konfiguriert haben, können Sie Ihre Anwendung erstellt.Now that you have registered your app in Azure AD and configured it with the necessary permissions, you're ready to build your app. Folgend finden Sie einige der wichtigsten Aspekte, die beim Entwerfen und Erstellen Ihrer App zu berücksichtigen sind:The following are some of the key aspects to consider when designing and building your app:

  • Die Zustimmungsfunktionalität.The consent experience. Um die Zustimmung Ihrer Kunden zu erhalten, müssen Sie diese in einem Browser zur Azure AD-Webseite weiterleiten, indem Sie die speziell erstellte URL verwenden, die vorher hier beschrieben wurde. Sie müssen zudem über eine Webseite verfügen, zu der Azure AD den Administrator weiterleitet, wenn dieser seine Zustimmung erteilt hat.To obtain consent from your customers, you must direct them in a browser to the Azure AD website, using the specially constructed URL described previously, and you must have a website to which Azure AD will redirect the admin once they grant consent. Diese Webseite muss den Autorisierungscode aus der URL extrahieren und diesen verwenden, um ein Zugriffstoken anzufordern, von dem sie die Mandanten-ID erält.This website must extract the authorization code from the URL and use it to request an access token from which it can obtain the tenant ID.

  • Speichern Sie die Mandanten-ID in Ihrem System.Store the tenant ID in your system. Diese wird beim Anfordern des Zugriffstoken von Azure AD und beim Aufrufen der Office-Management-APIs benötigt.This will be needed when requesting access tokens from Azure AD and when calling the Office Management APIs.

  • Verwalten von Zugriffstoken.Managing access tokens. Sie benötigen eine Komponente, die nach Bedarf Zugriffstoken anfordert und verwaltet.You will need a component that requests and manages access tokens as needed. Wenn Ihre App in regelmäßigen Abständen die APIs aufruft, kann sie Token nach Bedarf anfordern. Wenn sie die APIs ständig zum Abrufen von Daten aufruft, kann sie Token in regelmäßigen Abständen (z. B. alle 45 Minuten) anfordern.If your app calls the APIs periodically, it can request tokens on demand, or if it calls the APIs continuously to retrieve data, it can request tokens at regular intervals (for example, every 45 minutes).

  • Implementieren eines Webhook-Listener je nach Bedarf der jeweiligen-API, die Sie verwenden.Implement a webhook listener as needed by the particular API you are using.

  • Abrufen und Speichern von Daten.Data retrieval and storage. Sie benötigen eine Komponente, die Daten für jeden Mandanten, abruft, entweder kontinuierlich oder als Reaktion auf Webhook-Benachrichtigungen, je nach der bestimmten-API, die Sie verwenden.You'll need a component that retrieves data for each tenant, either by using continuous polling or in response to webhook notifications, depending on the particular API you are using.