Freigeben über

Authentifizierung und Autorisierung für die Exchange Online Admin-API

Hinweis

Die in diesem Artikel beschriebenen Features befinden sich derzeit in der Vorschauphase, sind nicht in allen Organisationen verfügbar und können sich ändern.

In diesem Artikel werden die Authentifizierungs- und Autorisierungsanforderungen für die Verwendung von Endpunkten für die Exchange Online Admin-API behandelt.

Die Exchange Online Admin-API bietet eine REST-basierte Möglichkeit zum Ausführen bestimmter PowerShell-Cmdlets, die legacy-Szenarien für Exchange-Webdienste (EWS) ersetzen. Weitere Informationen finden Sie unter Übersicht über die Exchange Online Admin-API.

Für den Zugriff auf die Admin-API muss Ihre App ihre Identität einrichten, die richtigen Berechtigungen erhalten und bewährte Methoden für die sichere Tokenverarbeitung befolgen. Im Allgemeinen umfasst der Prozess die folgenden wichtigen Schritte:

  1. Registrieren einer App in Microsoft Entra ID

    Erstellen Sie eine App-Registrierung, um eine Identität für Ihre App einzurichten und Anmeldeinformationen (geheimer Clientschlüssel oder Zertifikat) zu konfigurieren. Mit dieser Registrierung kann Ihre App Token von Microsoft Entra ID anfordern.

  2. Zuweisen der erforderlichen API-Berechtigungen

    Fügen Sie ihrer App-Registrierung die erforderlichen OAuth-Bereiche hinzu:

    • Delegierter Flow: Exchange.ManageV2.
    • Nur-App-Flow: Exchange.ManageAsAppV2.

  3. Schritt 3: Zuweisen von RBAC-Berechtigungen

    Exchange Online verwendet die rollenbasierte Zugriffssteuerung (Role-Based Access Control, RBAC), um zu bestimmen, welche Endpunkte, Cmdlets und Objekte der Aufrufer verwalten kann. Weisen Sie dem Benutzer (für delegierten Zugriff) oder dem Dienstprinzipal der App (für nur App-Zugriff) die entsprechenden RBAC-Rollen zu.

  4. Schritt 4: Abrufen eines Zugriffstokens

    Verwenden Sie OAuth 2.0-Flows, um Token von Microsoft Entra ID abzurufen:

    • Delegierter Ablauf für den benutzerbasierten Zugriff.
    • Nur-App-Fluss für Dienst-zu-Dienst-Zugriff.

  5. Schritt 5: Verwenden des Zugriffstokens

Schritt 1: Registrieren einer App in Microsoft Entra ID

Um die Exchange Online Admin-API aufzurufen, müssen Sie Zuerst Ihre App in Microsoft Entra ID registrieren. Eine App ist wie ein Klassenobjekt. Ein Dienstprinzipal ist wie ein instance der -Klasse. Weitere Informationen finden Sie unter Anwendungs- und Dienstprinzipalobjekte in Microsoft Entra ID. Einen ausführlichen visuellen Ablauf zum Erstellen von Anwendungen in Microsoft Entra ID finden Sie unter https://aka.ms/azuread-app.

  1. Öffnen Sie die Microsoft Entra Admin Center unter https://entra.microsoft.com.

  2. Geben Sie im Suchfeld oben auf der Seite App-Registrierungen ein, und wählen Sie ihn aus den Ergebnissen aus.

    Screenshot der Microsoft Entra Admin Center mit eingegebener App-Reg im Suchfeld und ausgewähltem App-Registrierungen im Abschnitt Dienste auf der Seite.

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

    Screenshot: Seite

  4. Konfigurieren Sie auf der Seite Anwendung registrieren die Anwendungseinstellungen:

    • Name: Geben Sie einen beschreibenden Namen ein (z. B. Exchange Admin API-Client).
    • Unterstützte Kontotypen: Wählen Sie einen der folgenden Werte aus:
      • Single-organization-Apps: Wählen Sie Nur Konten in diesem Organisationsverzeichnis aus.
      • Mehrinstanzenfähige delegierte Szenarien: Wählen Sie Konten in einem beliebigen Organisationsverzeichnis aus.
    • Umleitungs-URI (optional): Für delegierten Flow erforderlich.
      • Plattform: Wählen Sie Web aus.
      • URI: Geben Sie die URL ein, https://localhost an die das Zugriffstoken gesendet wird (z. B. zu Testzwecken).

    Wenn Sie auf der Seite Anwendung registrieren fertig sind, wählen Sie Registrieren aus.

    Screenshot der Seite

Sie gelangen zur Seite Übersicht der App, die Sie registriert haben. Bleiben Sie für den nächsten Schritt auf der Seite.

Hinweis

Sie können keine Anmeldeinformationen für native Anwendungen erstellen, da sie nicht für automatisierte Dienst-zu-Dienst-Aufrufe verwendet werden können.

Schritt 2: Zuweisen der erforderlichen API-Berechtigungen

  1. Wählen Sie auf der Seite Übersicht der App, die Sie im vorherigen Schritt erstellt haben, im Abschnitt Verwaltendie Option API-Berechtigungen aus.

    Screenshot der Seite

  2. Wählen Sie auf der Seite API-Berechtigungen für die App die Option Berechtigung hinzufügen aus.

    Screenshot der Seite

  3. Wählen Sie im daraufhin geöffneten Flyout API-Berechtigungen anfordern die Registerkarte APIs aus, die mein organization verwendet, geben Sie Office 365 Exchange Online in das Suchfeld ein, und wählen Sie sie dann aus den Ergebnissen aus.

    Screenshot der Registerkarte

  4. Treffen Sie im Flyout Welche Arten von Berechtigungen sind für Ihre Anwendung erforderlich? eine der folgenden Optionen:

    • Nur-App-Flow: Wählen Sie Anwendungsberechtigungen aus, erweitern Sie Exchange, wählen Sie Exchange.ManageAsAppV2 und dann Berechtigungen hinzufügen aus.

      Screenshot: Welche Art von Berechtigungen erfordert Ihre Anwendung? Flyout, in dem die Werte für den reinen App-Flow ausgewählt sind.

    • Delegierter Flow: Wählen Sie Delegierte Berechtigungen aus, erweitern Sie Exchange, wählen Sie Exchange.ManageV2 und dann Berechtigungen hinzufügen aus.

      Screenshot: Welche Art von Berechtigungen erfordert Ihre Anwendung? Flyout mit ausgewählten Werten für delegierten Flow.

  5. Überprüfen Sie auf der Seite API-Berechtigungen , ob die Auswahlen aus dem vorherigen Schritt aufgeführt sind:

    • > Office 365 Exchange Online Exchange.ManageAsApp:
      • Typ: Anwendung
      • Admin Zustimmung erforderlich: Ja
    • > Office 365 Exchange Online Exchange.ManageV2:
      • Typ: Delegiert
      • Admin Zustimmung erforderlich: Ja

  6. Wählen Sie Administratoreinwilligung erteilen für aus, überprüfen Sie das Bestätigungsdialogfeld, und wählen Sie Ja aus.

    Screenshot der Ergebnisse der Auswahl von Administratoreinwilligung erteilen für

Schritt 3: Zuweisen von RBAC-Berechtigungen

Nachdem Sie Ihre App registriert und API-Berechtigungen erteilt haben, müssen Sie Exchange RBAC-Rollen konfigurieren. OAuth-Bereiche ermöglichen Ihrer App das Abrufen von Token, aber RBAC bestimmt, welche Cmdlets und Objekte der Aufrufer verwalten kann. Ohne die entsprechenden RBAC-Rollenzuweisungen schlagen selbst gültige Token mit dem folgenden Fehler fehl: 403 Verboten.

Führen Sie die Schritte in einem der folgenden Unterabschnitte basierend auf der Art Ihrer App aus.

Berechtigungen für delegierten Fluss (Benutzer)

In delegierten Szenarien muss dem Benutzer, in dessen Auftrag die App das Token abruft, die erforderlichen RBAC-Rollen in Exchange Online zugewiesen werden. Allgemeine Rollenbeispiele:

  • Empfängerverwaltung für Postfach- und Ordnervorgänge.
  • Organisationsverwaltung für Einstellungen auf organization Ebene.
  • Schreibgeschützte Organisationsverwaltung für schreibgeschützte Organisationsvorgänge.

Weisen Sie diese Rollen über das Exchange Admin Center oder Exchange Online PowerShell zu. Anweisungen hierzu finden Sie unter Verwalten von Rollengruppen in Exchange Online.

Berechtigungen für den reinen App-Flow

Für Reine-App-Szenarien muss der Dienstprinzipal, der Ihre App darstellt, über ausreichende Berechtigungen verfügen. Sie haben folgende Optionen:

  • Zuweisen Microsoft Entra Rollen (der Einfachheit halber empfohlen): Gewähren Sie der Unternehmensanwendung eine integrierte Microsoft Entra Rolle. Beispielsweise Exchange-Administrator für vollständige Exchange Online Berechtigungen:

    1. Wählen Sie im Microsoft Entra Admin Center unter https://entra.microsoft.comdie Option Rollen & Administratoren aus.
    2. Rollen und Administratoren | Wählen Sie auf der Seite Alle Rollen die Rolle Exchange-Administrator aus, indem Sie auf eine beliebige Stelle in der Zeile neben dem Kontrollkästchen neben der ersten Spalte klicken.
    3. Auf dem Exchange-Administrator | Auf der seite Zuweisungen , die geöffnet wird, wählen Sie Zuweisungen hinzufügen aus, wählen Sie Ihre App und dann Bestätigen aus.

  • Zuweisen integrierter oder benutzerdefinierter Exchange RBAC-Rollengruppen (geringste Rechte): Erstellen oder verwenden Sie vorhandene benutzerdefinierte Rollengruppen in Exchange Online, die nur die Cmdlets enthalten, die Ihre App benötigt, und fügen Sie diesen Gruppen den Dienstprinzipal hinzu. Dieser Ansatz vermeidet umfassende Berechtigungen und ist auf die Sicherheit mit den geringsten Rechten ausgerichtet. Weitere Informationen finden Sie unter Nur-App-Authentifizierung in Exchange Online PowerShell.

In der folgenden Tabelle ist die integrierte RBAC-Rolle aufgeführt, die für jeden Endpunkt erforderlich ist.

Endpunkt Erforderliche Exchange-Rollengruppe
/OrganizationConfig

/AcceptedDomain		 Organisationsverwaltung mit Leserechten
/Briefkasten

/MailboxFolderPermission

/DistributionGroupMember

/DynamicDistributionGroupMember		 Empfängerverwaltung

Für eine noch präzisere Steuerung sollten Sie benutzerdefinierte Rollengruppen verwenden, die nur die spezifischen Verwaltungsrollen (Cmdlet-Sätze) enthalten, die Ihre Anwendung benötigt. Dieser Ansatz folgt der Sicherheit mit den geringsten Rechten und verringert das Risiko im Vergleich zu breiten Rollen wie Exchange-Administrator oder globaler Administrator, die den für typische Admin API-Vorgänge erforderlichen Bereich überschreiten.

Schritt 4: Abrufen eines Zugriffstokens

Zum Aufrufen der Exchange Online Admin-API muss Ihre App ein OAuth 2.0-Zugriffstoken von Microsoft Entra ID abrufen. Wie bereits erwähnt, unterstützt Admin-API die folgenden Flows:

Verwenden Sie den /.default Bereich der Ressource beim Anfordern von Token (z. B https://outlook.office365.com/.default. ). Diese Methode weist Microsoft Entra ID an, ein Token auszustellen, das die Anwendungsberechtigungen (Rollen) enthält, die zuvor für diese Ressource gewährt wurden.

Autorisierungscodefluss (delegiert) mit Aktualisierungstoken

Verwenden Sie diesen Flow, wenn Sie den Benutzerkontext benötigen. Um ein Aktualisierungstoken zu erhalten, müssen Sie in den Autorisierungs- und Tokenanforderungen anfordern offline_access . Weitere Informationen finden Sie unter Aktualisieren von Token im Microsoft Identity Platform und Bereiche und Berechtigungen im Microsoft Identity Platform.

Der Benutzer muss die App autorisieren, um in ihrem Namen zu handeln. Die App leitet den Benutzer an den /authorize Endpunkt im Microsoft Identity Platform um. Über diesen Endpunkt meldet Microsoft Entra ID den Benutzer an und fordert seine Zustimmung für die von der App angeforderten Berechtigungen an. Nach der Zustimmung gibt Microsoft Entra ID einen Autorisierungscode an die App zurück. Die App kann diesen Code dann am /token Endpunkt des Microsoft Identity Platform für ein Zugriffstoken einlösen.

Das folgende Beispiel zeigt eine Anforderung an den /authorize Endpunkt. In der Anforderungs-URL rufen Sie den /authorize Endpunkt auf und geben die erforderlichen und empfohlenen Eigenschaften als Abfrageparameter an. Zum Beispiel:

GET https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/authorize
    ?client_id=<ClientID>
    &response_type=code
    &redirect_uri=<RedirectURI> # must exactly match the app registration
    &response_mode=query
    &scope=https://outlook.office365.com/.default offline_access
    &state=12345

Die Parameter werden in der folgenden Tabelle beschrieben:

Parameter Erforderlich Beschreibung
TenantID Erforderlich Die organization, in der Sie die Berechtigung anfordern. Der Wert kann die TenantID-GUID oder der Anzeigename sein.
client_id Erforderlich Die Client-ID, die der App vom Registrierungsportal zugewiesen wurde. Wird auch als appId bezeichnet.
response_type Erforderlich Muss den Wert code für den OAuth 2.0-Autorisierungscodefluss enthalten.
redirect_uri Empfohlen Der Umleitungs-URI der App im URL-codierten Format, bei dem Authentifizierungsantworten gesendet und von der App empfangen werden. Sie muss mit einer der Umleitungs-URIs übereinstimmen, die Sie im App-Registrierungsportal registriert haben.
Bereich Erforderlich Eine durch Leerzeichen getrennte Liste der Exchange Online Admin API-Berechtigungen, der der Benutzer zustimmen soll. Diese Berechtigungen können Ressourcenberechtigungen (https://outlook.office365.com/.default in diesem Szenario) und OIDC-Bereiche wie offline_accessenthalten, was angibt, dass die App ein Aktualisierungstoken für den langlebigen Zugriff auf Ressourcen benötigt.
response_mode Empfohlen Gibt die Methode an, um das resultierende Token zurück an die App zu senden. Gültige Werte sind query oder form_post.
state Empfohlen Ein in der Anforderung enthaltener Wert, der auch in der Tokenantwort zurückgegeben wird. Dabei kann es sich um eine Zeichenfolge mit beliebigem Inhalt handeln. In der Regel verwenden Sie einen zufälligen, eindeutigen Wert, um websiteübergreifende Anforderungsfälschungsangriffe zu verhindern. Diese Eigenschaft codiert auch Informationen zum Status des Benutzers in der App, bevor die Authentifizierungsanforderung aufgetreten ist, z. B. die Seite oder Ansicht, auf der er sich befand.

Schritt 2: Einlösen des Autorisierungscodes für Token

Die App verwendet den Autorisierungscode aus dem vorherigen Schritt, um ein Zugriffstoken anzufordern, indem eine POST-Anforderung an den /token Endpunkt gesendet wird.

POST https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<ClientID>
&client_secret=<ClientSecret>                  # confidential clients only
&grant_type=authorization_code
&code=<authorization_code>
&redirect_uri=<RedirectURI>
&scope=https://outlook.office365.com/.default offline_access

Die Parameter werden in der folgenden Tabelle beschrieben:

Parameter Erforderlich Beschreibung
TenantID Erforderlich Die organization, in der Sie die Berechtigung anfordern. Der Wert kann die TenantID-GUID oder der Anzeigename sein.
client_id Erforderlich Die Client-ID, die der App vom Registrierungsportal zugewiesen wurde. Wird auch als appId bezeichnet.
grant_type Erforderlich Der Wert muss für den Autorisierungscodefluss sein authorization_code .
Bereich Erforderlich Eine durch Leerzeichen getrennte Liste von Bereichen. Die Bereiche, die Ihre App-Anforderungen anfordern, müssen mit oder einer Teilmenge der in Schritt 1: Senden des Benutzers zur Anmeldung und Zustimmung angeforderten Bereiche übereinstimmen.
code Erforderlich Der Autorisierungscode, den Sie in Schritt 1: Senden des Benutzers zur Anmeldung und Zustimmung erhalten haben.
redirect_uri Erforderlich Derselbe Umleitungs-URI-Wert, den Sie zum Abrufen des Autorisierungscodes in Schritt 1: Senden des Benutzers zur Anmeldung und Zustimmung verwendet haben.
client_secret Für Web-Apps erforderlich Der geheime Clientschlüssel, den Sie im App-Registrierungsportal für Ihre App erstellt haben.

Eine erfolgreiche Antwort umfasst Folgendes:

Tipp

Speichern Sie den Wert TenantID (tid) aus den Tokenansprüchen. Sie benötigen sie, um Admin API-URLs und zukünftige Tokenanforderungen zu erstellen. Weitere Informationen finden Sie unter Microsoft Identity Platform App-Typen und Authentifizierungsflows.

Schritt 3: Automatisches Aktualisieren des Zugriffstokens (keine Benutzeraufforderung)

Zugriffstoken sind kurzlebig, und die App muss sie nach ihrem Ablauf aktualisieren, um weiterhin auf Ressourcen zugreifen zu können. Die App aktualisiert ein Zugriffstoken, indem eine weitere POST-Anforderung an den /token Endpunkt gesendet wird:

  • Geben Sie anstelle refresh_token des code im Anforderungstext an.
  • Geben Sie refresh_token anstelle von authorization_code als grant_type an.
POST https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<ClientID>
&client_secret=<ClientSecret>
&grant_type=refresh_token
&refresh_token=<refresh_token>
&scope=https://outlook.office365.com/.default offline_access

Die Parameter werden in der folgenden Tabelle beschrieben:

Parameter Erforderlich Beschreibung
TenantID Erforderlich Die organization, in der Sie die Berechtigung anfordern. Der Wert kann die TenantID-GUID oder der Anzeigename sein.
client_id Erforderlich Die Client-ID, die der App vom Registrierungsportal zugewiesen wurde. Wird auch als appId bezeichnet.
grant_type Erforderlich Der Wert muss sein refresh_token.
refresh_token Erforderlich Die refresh_token, die Ihre App während der Tokenanforderung in Schritt 2: Einlösen des Autorisierungscodes für Token erhalten hat.
Bereich Erforderlich Eine durch Leerzeichen getrennte Liste von Bereichen. Die Bereiche, die Ihre App-Anforderungen anfordern, müssen mit oder einer Teilmenge der Bereiche übereinstimmen, die in Schritt 2: Einlösen des Autorisierungscodes für Token angefordert wurden.
client_secret Für Web-Apps erforderlich Der geheime Clientschlüssel, den Sie im App-Registrierungsportal für Ihre App erstellt haben.

Eine erfolgreiche Antwort enthält die folgenden Ergebnisse:

  • Gibt einen neuen access_token und häufig eine neue refresh_token zurück, um die alte zu ersetzen.
  • Aktualisierungstoken dauern länger als Zugriffstoken. Der Standardwert beträgt etwa 90 Tage für vertrauliche Clients und 24 Stunden für SPA-Umleitungs-URIs. Die Token können jederzeit widerrufen werden. Führen Sie daher bei Bedarf eine erneute Authentifizierung durch. Weitere Informationen finden Sie unter Aktualisieren von Token im Microsoft Identity Platform.

Flow für Clientanmeldeinformationen (nur App)

Verwenden Sie diesen Flow für Dienst-zu-Dienst-Aufrufe ohne Benutzer. Fordern Sie nach der Zustimmung des Administrators zu Anwendungsberechtigungen (z. B Exchange.ManageAsAppV2. ) und dem Zuweisen der erforderlichen RBAC-Rollen ein Token mit den eigenen Anmeldeinformationen der App an. Es wird kein Aktualisierungstoken ausgegeben. Fordern Sie bei Bedarf neue Zugriffstoken an.

Um ein Zugriffstoken abzurufen, senden Sie eine POST-Anforderung an den /token Identity Platform-Endpunkt. In dieser Anforderung verwendet der Client den geheimen Clientschlüssel.

POST https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<ClientID>
&client_secret=<ClientSecret>                   # or client assertion (certificate)
&grant_type=client_credentials
&scope=https://outlook.office365.com/.default

Die Parameter werden in der folgenden Tabelle beschrieben:

Parameter Bedingung Beschreibung
TenantID Erforderlich Die organization, in der Sie die Berechtigung anfordern. Der Wert kann die TenantID-GUID oder der Anzeigename sein.
client_id Erforderlich Die Anwendungs-ID, die der App vom Registrierungsportal zugewiesen wurde.
Bereich Erforderlich Der App-ID-URI der Ressource mit dem .default Suffix. Für die Exchange Online Admin-API lautet https://outlook.office365.com/der ID-URI der Ressourcen-App, sodass der Bereichswert isthttps://outlook.office365.com/.default.

Dieser Wert informiert den Microsoft Identity Platform-Endpunkts, alle Berechtigungen auf App-Ebene einzuschließen, denen der Administrator zugestimmt hat, in das Zugriffstoken.
client_secret Erforderlich Der geheime Clientschlüssel, den Sie für Ihre App im App-Registrierungsportal generiert haben. Überprüfen Sie, ob der Wert URL-codiert ist.
grant_type Erforderlich Der Wert muss sein client_credentials.

Schritt 5: Verwenden des Zugriffstokens

Nachdem Sie ein Zugriffstoken wie in Schritt 4: Abrufen eines Zugriffstokens beschrieben erhalten haben, fügen Sie das Zugriffstoken für jeden nachfolgenden API-Aufruf in den Autorisierungsheader ein:

POST https://outlook.office365.com/adminapi/v2.0/<TenantID>/OrganizationConfig
Authorization: Bearer <access_token>
Content-Type: application/json

 { "CmdletInput": { "CmdletName": "Get-OrganizationConfig" } }

Verwenden der Microsoft Authentication Library (MSAL)

Dieser Artikel enthält die erforderlichen Protokolldetails, wenn Sie manuell ein Problem mit unformatierten HTTP-Anforderungen erstellen, um Token für geheime Clientschlüssel abzurufen. Verwenden Sie in Produktions-Apps eine integrierte oder unterstützte Authentifizierungsbibliothek, um Sicherheitstoken abzurufen und geschützte Web-APIs aufzurufen. Beispiel: Microsoft Authentication Library (MSAL).

Die MSAL und andere unterstützte Authentifizierungsbibliotheken vereinfachen den Prozess, indem sie Details verarbeiten, damit Sie sich auf die Funktionalität Ihrer App konzentrieren können. Zum Beispiel:

  • Validierung.
  • Cookieverarbeitung.
  • Tokenzwischenspeicherung.
  • Sichere Verbindungen.

Microsoft verwaltet eine große Auswahl an Codebeispielen, die unterstützte Authentifizierungsbibliotheken mit dem Microsoft Identity Platform veranschaulichen. Informationen zum Zugriff auf diese Codebeispiele finden Sie unter Microsoft Identity Platform Codebeispiele.

Beispiele zum Abrufen von Token mithilfe von Zertifikaten finden Sie unter Microsoft Identity Platform und den Flow für OAuth 2.0-Clientanmeldeinformationen.

  • Last updated on