Erste Schritte mit den Office 365-Verwaltungs-APIs

  • Artikel

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. Die Office 365-Verwaltungs-APIs verwenden Microsoft Entra ID, um Authentifizierungsdienste bereitzustellen, die Sie verwenden können, um Ihrer Anwendung Rechte für den Zugriff darauf zu gewähren.

Es gibt vier zentrale Schritte:

  1. Registrieren Sie Ihre Anwendung in Microsoft Entra ID. Um Ihrer Anwendung Zugriff auf die Office 365 Management-APIs zu ermöglichen, müssen Sie Ihre Anwendung in Microsoft Entra ID registrieren. 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.

  2. Erhalten Sie die Genehmigung durch einen Office 365-Mandanten-Admin. Ein Office 365-Mandanten-Admin muss eine Genehmigung erteilen, damit Ihre Anwendung auf mittels Office 365-Management-APIs auf Mandantendaten zugreifen kann. Der Zustimmungsprozess ist eine browserbasierte Oberfläche, bei der sich der Mandantenadministrator bei der Microsoft Entra Zustimmungsbenutzeroberfläche anmeldet und die von der Anwendung angeforderten Zugriffsberechtigungen überprüft und die Anforderung dann entweder erteilt oder abgelehnt werden muss. Nachdem die Genehmigung erteilt wurde, leitet die Benutzeroberfläche den Benutzer über einen Authentifizierungscode in der URL zurück zu Ihrer Anwendung. Ihre Anwendung führt einen Dienst-zu-Dienst-Aufruf an Microsoft Entra ID aus, um diesen Autorisierungscode gegen ein Zugriffstoken auszutauschen, das Sowohl Informationen zum Mandantenadministrator als auch zu Ihrer Anwendung enthält. Die Mandanten-ID muss aus dem Zugriffstoken entnommen werden und für die zukünftige Nutzung aufbewahrt werden.

  3. Anfordern von Zugriffstoken von Microsoft Entra ID. Wenn Sie die Anmeldeinformationen Ihrer Anwendung gemäß der Konfiguration in Microsoft Entra ID verwendet, fordert Ihre Anwendung fortlaufend zusätzliche Zugriffstoken für einen einwilligungsfähigen Mandanten an, ohne dass eine weitere Mandantenadministratorinteraktion erforderlich ist. Diese Zugriffstoken werden als „nur App“-Token bezeichnet, da sie keine Informationen zum Mandantenadministrator beinhalten.

  4. Rufen Sie die Office 365-Management-APIs auf. Die „nur App“-Zugriffstoken werden an die Office 365-Management-APIs übergeben, um Ihre Anwendung zu authentifizieren und zu autorisieren.

Das folgende Diagramm zeigt die Abfolge von Genehmigungs- und Zugriffstoken-Anfragen.

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. Dazu aktivieren Sie das Office 365-Überwachungsprotokoll. Anweisungen hierzu finden Sie unter Aktivieren und Deaktivieren der Office 365-Überwachungsprotokollsuche.

Wenn Sie nur die Office 365-Dienstkommunikations-API verwenden, ist die Aktivierung der einheitlichen Überwachungsprotokollierung nicht nötig.

Registrieren Ihrer Anwendung in Microsoft Entra ID

Die Office 365-Verwaltungs-APIs verwenden Microsoft Entra ID, um eine sichere Authentifizierung für Office 365 Mandantendaten bereitzustellen. Für den Zugriff auf die Office 365-Verwaltungs-APIs müssen Sie Ihre App in Microsoft Entra ID registrieren. Im Rahmen der Konfiguration geben Sie die Berechtigungsstufen an, die Ihre App für den Zugriff auf die APIs benötigt.

Voraussetzungen

Um Ihre App in Microsoft Entra ID zu registrieren, benötigen Sie ein Abonnement für Office 365 und ein Azure-Abonnement, das Ihrem Office 365-Abonnement zugeordnet wurde. Für den Anfang können Sie Testabonnements sowohl für Office 365 als auch für Azure verwenden. Weitere Informationen finden Sie unter Willkommen beim Office 365-Entwicklerprogramm.

Registrieren Ihrer Anwendung im Azure-Portal in Microsoft Entra ID

Nachdem Sie über einen Microsoft-Mandanten mit den richtigen Abonnements verfügen, können Sie Ihre Anwendung in Microsoft Entra ID registrieren.

  1. Melden Sie sich im Azure-Portal an, und verwenden Sie dabei die Anmeldeinformationen Ihres Microsoft-Mandanten, der über das Office 365-Abonnement verfügt, das Sie verwenden möchten. Sie können auch über einen Link auf das Azure-Portal zugreifen, der im linken Navigationsbereich im Microsoft 365 Admin Center angezeigt wird.

  2. Wählen Sie im linken Navigationsbereich Microsoft Entra ID (1) aus.

    Hauptseite des Azure-Portals

  3. Wählen Sie auf der Seite Microsoft Entra IDApp-Registrierungen (2) und dann Neue Registrierung (3) aus.

    seite App-Registrierungen in Microsoft Entra ID

  4. Wählen Sie auf der Seite App-Registrierungen die Option Neue Registrierung aus.

    Es wird eine neue Seite angezeigt, auf der Sie die Registrierung Ihrer App starten können.

  5. Führen Sie auf der Seite Registrierung einer Anwendung folgende Schritte aus:

    App-Registrierungsprozess

    1. Benennen Sie Ihre App.

    2. Wählen Sie aus, wer die App verwenden und auf die API zugreifen kann.

    3. Geben Sie bei Bedarf eine Umleitungs-URL für die Benutzerumleitung nach der Authentifizierung an.

  6. Klicken Sie auf Registrieren, um die neue App zu registrieren.

Konfigurieren der Anwendungseigenschaften in Microsoft Entra ID

Nachdem Ihre Anwendung registriert wurde, müssen Sie mehrere wichtige Eigenschaften angeben, die bestimmen, wie Ihre Anwendung in Microsoft Entra ID funktioniert und wie Mandantenadministratoren die Zustimmung erteilen, damit Ihre Anwendung mithilfe der Office 365-Verwaltungs-APIs auf ihre Daten zugreifen kann.

Weitere Informationen zur Microsoft Entra Anwendungskonfiguration im Allgemeinen finden Sie unter Eigenschaften von Anwendungsobjekten.

  1. Client-ID. Dieser Wert wird automatisch von Microsoft Entra ID generiert. Ihre Anwendung verwendet diesen Wert, wenn Sie die Zustimmung von Mandantenadministratoren anfordern und nur App-Token von Microsoft Entra ID anfordern.

  2. Die Anwendung hat mehrere Mandanten. 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. Wenn für diese Eigenschaft Nein ausgewählt ist, kann Ihre Anwendung ausschließlich auf Daten Ihres eigenen Mandanten zugreifen.

  3. Antwort-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. Sie können bei Bedarf mehrere Antwort-URLs konfigurieren. 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.

Wählen Sie unbedingt Speichern, nachdem Sie Änderungen an dieser Eigenschaften vorgenommen haben.

Erstellen Sie einen neuen Schlüssel für Ihre Anwendung

Schlüssel, auch als geheime Clientschlüssel bezeichnet, werden verwendet, wenn ein Autorisierungscode gegen eine Zugriffstoken ausgetauscht wird.

  1. Wählen Sie auf der Seite Microsoft Entra ID im Azure-Portal App-Registrierungen und dann Ihre Anwendung aus.

    Auswahl der App, die Sie gerade registriert haben

  2. Nachdem die Seite für Ihre App angezeigt wurde, wählen Sie Zertifikate & Geheimnisse (1) im linken Bereich aus. Auf dieser Seite können Sie Zertifikate hochladen und neue geheime Clientschlüssel (2) erstellen.

    Die Seite „Zertifikate und Geheimnisse“ der App

  3. Auf der Seite Zertifikate und Geheimnisse (1) wählen Sie Neuer geheimer Clientschlüssel (2) aus, geben eine Beschreibung ein, wählen die Dauer für Ihren Schlüssel (3) aus, und wählen dann Hinzufügen (4) aus.

    Erstellen eines geheimen Clientschlüssels

  4. Nach dem Erstellen des geheimen Clientschlüssels wird der Wert unter geheimer Clientschlüssel (2) angezeigt. Klicken Sie auf das Symbol „Zwischenablage“ (3), um den Wert des geheimen Clientschlüssels in die Zwischenablage zu kopieren.

    Kopieren Sie den Wert des geheimen Clientschlüssels in die Zwischenablage, und speichern Sie ihn zur späteren Verwendung.

    Wichtig

    Azure zeigt den Wert des geheimen Clientschlüssels nur zum Zeitpunkt der ersten Generierung an. Sie können nicht zu dieser Seite zurückkehren und den Wert des geheimen Clientschlüssels später abrufen. Stellen Sie sicher, dass Sie ihn kopieren und an einem sicheren Ort speichern, damit Sie ihn später verwenden können.

Konfigurieren eines x. 509-Zertifikats, um Dienst-zu-Dienst-Aufrufe zu ermöglichen

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.

Weitere Informationen finden Sie unter Dienst-zu-Dienst-Anrufe mithilfe von Client-Anmeldeinformationen.

Sie müssen ein X.509-Zertifikat mit Ihrer Anwendung konfigurieren, das als Clientanmeldeinformationen verwendet wird, wenn Nur-App-Zugriffstoken von Microsoft Entra ID angefordert werden. Dieser Prozess besteht aus zwei Schritten:

  • Abrufen eines X.509-Zertifikats. Sie können ein selbstsigniertes Zertifikat oder ein von einer öffentlichen, vertrauenswürdigen Zertifizierungsstelle ausgestelltes Zertifikat verwenden..

  • Ändern Sie Ihr Anwendungsmanifest, um den Fingerabdruck und den öffentlichen Schlüssel Ihres Zertifikats einzuschließen.

Die folgenden Anweisungen zeigen Ihnen, wie Sie das Visual Studio oder das Windows SDK Makecerttool verwenden, um ein selbstsigniertes Zertifikat zu erstellen und den öffentlichen Schlüssel in eine base64-codierte Datei zu exportieren.

  1. Führen Sie in der Befehlszeile Folgendes aus:

     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. Kürzere Schlüssellängen werden nicht als gültige Schlüssel akzeptiert.

  2. Öffnen Sie die Snap-In MMC-Zertifikate und verbinden Sie sich mit Ihrem Benutzerkonto.

  3. Suchen Sie das neue Zertifikat im Ordner „Persönlich“, und exportieren Sie den öffentlichen Schlüssel in eine base64-codierte Datei (z. B. mycompanyname.cer). Ihre Anwendung verwendet dieses Zertifikat für die Kommunikation mit Microsoft Entra ID. Stellen Sie daher sicher, dass Sie auch auf den privaten Schlüssel zugreifen können.

    Hinweis

    Sie können Windows PowerShell verwenden, um den Fingerabdruck und den base64-codierten öffentlichen Schlüssel zu extrahieren. Andere Plattformen bieten ähnliche Tools zum Abrufen der Eigenschaften von Zertifikaten.

  4. Geben Sie an einer Windows PowerShell Eingabeaufforderung Folgendes ein, und führen Sie sie aus:

     $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.

    Mithilfe der aus dem Zertifikat extrahierten Werte und der generierten Schlüssel-ID müssen Sie nun Ihr Anwendungsmanifest in Microsoft Entra ID aktualisieren.

  6. Wechseln Sie im Azure-Portal zu App-Registrierungen>Alle Anwendungen, wählen Sie Ihre Anwendung und dann Manifest im linken Bereich aus.

  7. Wählen Sie in der oberen Navigationsleiste auf der Seite Manifest (1) die Option Download (2) aus.

    Herunterladen des Manifests zum Bearbeiten

  8. Öffnen Sie das heruntergeladene Manifest in einem Editor, und ersetzen Sie die leere Eigenschaft keyCredentials durch die folgende 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.

  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.

Geben Sie die Berechtigungen, die Ihre Anwnedung benötigt, um auf die Office 365-Management-APIs zuzugreifen, an.

Schließlich müssen Sie genau angeben, welche Berechtigungen Ihre Anwendung für die Office 365 Management-APIs benötigt. 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.

  1. Wechseln Sie im Azure-Portal zu App-Registrierungen>Alle Anwendungen, wählen Sie Ihre Anwendung und dann API-Berechtigungen (1) im linken Bereich aus. Klicken Sie auf Eine Berechtigung hinzufügen (2), um die Anforderungs-API-Berechtigung (3) anzuzeigen.

    API-Berechtigungen hinzufügen

  2. Wählen Sie auf der Registerkarte Microsoft-APIs die Option Office 365-Management-APIs (4) aus.

    Auswählen von Office 365-Management-APIs auf der Registerkarte „Microsoft-APIs“

  3. Wählen Sie auf der Flyoutseite die folgenden Berechtigungstypen (3) aus, die für Ihre App erforderlich sind, und klicken Sie dann auf Berechtigungen hinzufügen.

    Auswählen von Berechtigungstypen für Ihre App

    1. Delegierte Berechtigungen. Ermöglicht Ihrer Client-App das Ausführen von Vorgängen im Namen des angemeldeten Benutzers, z. B. das Lesen von E-Mails oder das Ändern des Benutzerprofils.

    2. Anwendungsberechtigungen. Berechtigungen, die es der Client-App ermöglichen, sich selbst ohne Benutzerinteraktion oder -zustimmung zu authentifizieren, z. B. eine App, die von Hintergrunddiensten oder Daemon-Apps verwendet wird.

  4. Office-Management-APIs werden jetzt in der Liste der Anwendungen angezeigt, für die Ihre App Berechtigungen benötigt. Wählen Sie bei Bedarf sowohl unter Anwendungsberechtigungen als auch unter Delegierte Berechtigungen die Berechtigungen aus, die Ihre Anwendung benötigt. Weitere Informationen zu den einzelnen Berechtigungen finden Sie unter den jeweiligen API-Referenzen.

    API-Berechtigungen für Ihre App

  5. Wählen Sie Administrator-Zustimmung für „Mandantenname“ gewähren aus, um den Berechtigungen zuzustimmen, die Ihrer App erteilt wurden.

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. Um die Zustimmung zu erteilen, muss sich der Mandantenadministrator mit der folgenden speziell erstellten URL bei Microsoft Entra ID anmelden, auf der er die angeforderten Berechtigungen Ihrer Anwendung überprüfen kann. Dieser Schritt ist nicht erforderlich, wenn Sie APIs verwenden, um auf Daten aus Ihrem eigenen Mandanten zuzugreifen.

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 Umleitungs-URL muss mit einem Unterpfad unter einer der Antwort-URLs übereinstimmen oder sein, die für Ihre Anwendung in Microsoft Entra ID konfiguriert wurden.

Beispiel:

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. Ihnen wird die Anfrage zur Berechtigungserteilung zur Nutzung der Office-Management-APIs für Ihre Anwendung angezeigt.

Seite „Berechtigungszustimmung“

Nachdem Sie Annehmen ausgewählt haben, werden Sie zu der angegebenen Seite weitergeleitet und die Abfrage-Zeichenfolge wird einen Code enthalten.

Beispiel:

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

Ihre Anwendung verwendet diesen Autorisierungscode, um ein Zugriffstoken von Microsoft Entra ID abzurufen, aus dem die Mandanten-ID extrahiert werden kann. Nachdem Sie die Mandanten-ID extrahiert und gespeichert haben, können Sie nachfolgende Zugriffstoken beziehen, ohne dass eine Anmeldung als Mandantenadministrator notwendig ist.

Anfordern von Zugriffstoken von Microsoft Entra ID

Es gibt zwei Methoden zum Anfordern von Zugriffstoken von Microsoft Entra ID:

  • Der Genehmigungsprozess mit Autorisierungscode beinhaltet, dass eine Mandantenadministrator seine ausdrückliche Genehmigung erteilt, wodurch ein Autorisierungscode an Ihre Anwendung zurückgegeben wird. Ihre Anwendung tauscht dann den Autorisierungscode gegen ein Zugriffstoken aus. 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.

  • 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. 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.

Zugriffstoken mithilfe des Autorisierungscodes anfordern

Nachdem ein Mandantenadministrator seine Zustimmung erteilt hat, empfängt Ihre Anwendung einen Autorisierungscode als Abfragezeichenfolgenparameter, wenn Microsoft Entra ID den Mandantenadministrator an die angegebene URL umleitet.

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

Ihre Anwendung erstellt einen HTTP-REST-POST an Microsoft Entra ID, um den Autorisierungscode gegen ein Zugriffstoken auszutauschen. 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:

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

Der Inhalt des POST enthält Folgendes:

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...

Beispielanfrage

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.

Beispielantwort

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. Es folgt ein Beispiel für ein uncodiertes 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.

Beispieltoken

{
  "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 an

Nachdem die Mandanten-ID bekannt ist, kann Ihre Anwendung Dienst-zu-Dienst-Aufrufe an Microsoft Entra ID senden, um nach Ablauf zusätzliche Zugriffstoken anzufordern. Diese Token enthalten ausschließlich Informationen über die anfragende Anwendung und nicht über den Administrator, der die erste Zustimmung erteilt hat. 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.

Wenn Sie Ihre Anwendung in .NET entwickeln, können Sie die Microsoft Authentication Library (MSAL) verwenden, um Clientassertionen zu erstellen. Andere Entwicklungsplattformen sollten ähnliche Bibliotheken haben.

Ein nicht codiertes JWT-Token besteht aus einer Kopfzeile und einer Nutzlast, die die folgenden Eigenschaften haben.

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-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 Clientassertion wird dann im Rahmen eines Dienst-zu-Dienst-Aufrufs zum Anfordern eines Zugriffstokens an Microsoft Entra ID übergeben. 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.

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

Der Inhalt des POST enthält Folgendes:

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}

Beispielanfrage

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.

Beispielantwort

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 Zugriffstoken

{
  "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 Anwendung

Nachdem Sie Ihre App in Microsoft Entra ID registriert und mit den erforderlichen Berechtigungen konfiguriert haben, können Sie Ihre App erstellen. Im Folgenden sind einige der wichtigsten Aspekte aufgeführt, die beim Entwerfen und Erstellen Ihrer App zu berücksichtigen sind.

  • Die Zustimmungsfunktionalität. Um die Zustimmung Ihrer Kunden einzuholen, müssen Sie sie in einem Browser auf die Microsoft Entra Website weiterleiten, indem Sie die zuvor beschriebene speziell erstellte URL verwenden. Außerdem müssen Sie über eine Website verfügen, auf die Microsoft Entra ID den Administrator umleiten, sobald sie ihre Zustimmung erteilt haben. Diese Webseite muss den Autorisierungscode aus der URL extrahieren und diesen verwenden, um ein Zugriffstoken anzufordern, von dem sie die Mandanten-ID erält.

  • Speichern Sie die Mandanten-ID in Ihrem System. Dies ist beim Anfordern von Zugriffstoken von Microsoft Entra ID und beim Aufrufen der Office-Verwaltungs-APIs erforderlich.

  • Verwalten von Zugriffstoken. Sie benötigen eine Komponente, die Zugriffstoken nach Bedarf anfordert und verwaltet. 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.

  • Implementieren Sie einen Webhooklistener. Je nach Bedarf für die jeweilige API, die Sie verwenden.

  • Abrufen und Speichern von Daten. 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.