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 und ersetzt damit ältere Exchange-Webdienstszenarien (Exchange Web Services, EWS). 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 feststellen, die richtigen Berechtigungen erhalten und bewährte Methoden für die sichere Tokenverarbeitung befolgen. Auf allgemeiner Ebene umfasst der Prozess die folgenden wichtigen Schritte:

  1. Registrieren einer App bei 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. Erforderliche API-Berechtigungen zuweisen

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

    • Delegierter Flow: Exchange.ManageV2.
    • App-only-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 reinen 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.
    • App-only flow for service-to-service.

  5. Schritt 5: Verwenden des Zugriffstokens

Schritt 1: Registrieren einer App bei Microsoft Entra ID

Um die Exchange Online Admin-API aufzurufen, müssen Sie Ihre App zunächst in Microsoft Entra ID registrieren. Eine App ist wie ein Klassenobjekt. Ein Dienstprinzipal ist wie eine 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 das Microsoft Entra Admin Center unter https://entra.microsoft.com.

  2. Geben Sie in das Suchfeld oben auf der Seite "App-Registrierungen" ein, und wählen Sie die App aus den Ergebnissen aus.

    Screenshot des Microsoft Entra Admin Center mit der in das Suchfeld eingegebenen App-Registrierung und den im Abschnitt

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

    Screenshot der 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.
      • Delegierte Szenarien für mehrere Mandanten: Wählen Sie Konten in einem beliebigen Organisationsverzeichnis aus.
    • Umleitungs-URI (optional): Erforderlich für den delegierten Fluss.
      • 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 Übersichtsseite 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 diese 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 Übersichtsseite der App, die Sie im vorherigen Schritt erstellt haben, API-Berechtigungen aus dem Abschnitt Verwalten aus.

    Screenshot der Übersichtsseite der App, die Sie im vorherigen Schritt registriert haben.

  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 von meiner organization verwendet werden, geben Sie Office 365 Exchange Online in das Suchfeld ein, und wählen Sie sie dann aus den Ergebnissen aus.

    Screenshot der Registerkarte

  4. Wählen Sie im Flyout Welche Berechtigungen benötigt Ihre Anwendung? eine der folgenden Optionen aus:

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

      Screenshot des Welche Berechtigungen benötigt Ihre Anwendung? Flyout mit den Werten für den App-only-Flow ausgewählt.

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

      Screenshot des Welche Berechtigungen benötigt Ihre Anwendung? Flyout mit den Werten für delegierten Flow ausgewählt.

  5. Überprüfen Sie auf der Seite "API-Berechtigungen ", ob die Auswahl aus dem vorherigen Schritt aufgelistet ist:

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

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

    Screenshot des Ergebnisses der Auswahl von

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 es Ihrer App, Token abzurufen, 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 Forbidden.

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

Berechtigungen für delegierten (Benutzer-)Flow

In delegierten Szenarien müssen dem Benutzer, in dessen Namen die App das Token erwirbt, die erforderlichen RBAC-Rollen in Exchange Online zugewiesen sein. Gängige Rollenbeispiele:

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

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

Berechtigungen für Nur-App-Flow

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

  • Zuweisen von Microsoft Entra-Rollen (der Einfachheit halber empfohlen): Gewähren Sie der Unternehmensanwendung eine integrierte Microsoft Entra-Rolle. Beispiel: 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. Auf der Seite Rollen und Administratoren | Wählen Sie auf der Seite "Alle Rollen" die Exchange-Administratorrolle aus, indem Sie auf eine beliebige Stelle in der Zeile außer dem Kontrollkästchen neben der ersten Spalte klicken.
    3. Auf der Seite Exchange-Administrator | Wählen Sie auf der sich öffnenden Aufgabenseite "Aufgaben hinzufügen" aus, wählen Sie Ihre App aus, und wählen Sie dann "Bestätigen" aus.

  • Zuweisen integrierter oder benutzerdefinierter Exchange RBAC-Rollengruppen (niedrigste 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 den Dienstprinzipal diesen Gruppen hinzu. Dieser Ansatz vermeidet weitreichende Berechtigungen und richtet sich nach der Sicherheit mit den geringsten Rechten. 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
/Postfach

/MailboxFolderPermission

/DistributionGroupMember

/DynamicDistributionGroupMember		 Empfängerverwaltung

Für eine noch präzisere Steuerung können 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 reduziert Risiken im Vergleich zu allgemeinen Rollen wie Exchange-Administrator oder Globaler Administrator, die über den für typische Admin-API-Vorgänge erforderlichen Umfang hinausgehen.

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 die 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 auszugeben, das die zuvor für diese Ressource gewährten Anwendungsberechtigungen (Rollen) enthält.

Autorisierungscodefluss (delegiert) mit Aktualisierungstoken

Verwenden Sie diesen Flow, wenn Sie 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 in der Microsoft Identity Platform und Bereiche und Berechtigungen in der Microsoft Identity Platform.

Der Benutzer muss die App autorisieren, in seinem Namen zu handeln. Die App leitet den Benutzer zum /authorize Endpunkt in der Microsoft Identity Platform um. Über diesen Endpunkt meldet Microsoft Entra ID den Benutzer an und fordert seine Zustimmung für die Berechtigungen an, die die App anfordert. Nach der Zustimmung gibt Microsoft Entra ID einen Autorisierungscode an die App zurück. Die App kann diesen Code dann am /token Endpunkt der 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, bei 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. Auch bekannt als appId.
response_type Erforderlich Muss den Wert code für OAuth 2.0 Autorisierungscodefluss enthalten.
redirect_uri Empfohlen Der Umleitungs-URI der App im URL-codierten Format, in dem Authentifizierungsantworten von der App gesendet und empfangen werden. Er muss mit einem der Umleitungs-URIs übereinstimmen, die Sie im App-Registrierungsportal registriert haben.
Bereich Erforderlich Eine durch Leerzeichen getrennte Liste der Exchange Online Admin API-Berechtigungen, denen der Benutzer zustimmen soll. Diese Berechtigungen können Ressourcenberechtigungen (https://outlook.office365.com/.default in diesem Szenario) und OIDC-Bereiche umfassen, z. B offline_access. , der angibt, dass die App ein Aktualisierungstoken für den langlebigen Zugriff auf Ressourcen benötigt.
response_mode Empfohlen Gibt die Methode zum Zurücksenden des resultierenden Tokens an die App an. Gültige Werte sind query or form_post.
state Empfohlen Ein in der Anforderung enthaltener Wert, der auch in der Tokenantwort zurückgegeben wird. Es kann sich um eine Zeichenfolge beliebigen Inhalts handeln. In der Regel verwenden Sie einen zufälligen, eindeutigen Wert, um Angriffe auf siteübergreifende Anforderungsfälschungen zu verhindern. Diese Eigenschaft codiert auch Informationen über den Zustand des Benutzers in der App vor der Authentifizierungsanforderung, 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 sie eine POST-Anforderung an den /token Endpunkt sendet.

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, bei 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. Auch bekannt als appId.
grant_type Erforderlich Der Wert muss für den Autorisierungscodefluss angegeben werden authorization_code .
Bereich Erforderlich Eine durch Leerzeichen getrennte Liste von Bereichen. Die Bereiche, die Ihre App anfordert, müssen den in Schritt 1 angeforderten Bereichen entsprechen oder eine Teilmenge dieser Bereiche sein.
code Erforderlich Der Autorisierungscode , den Sie in Schritt 1 erhalten haben: Senden Sie den Benutzer zur Anmeldung und Einwilligung.
redirect_uri Erforderlich Derselbe Umleitungs-URI-Wert, den Sie zum Abrufen des Autorisierungscodes in Schritt 1 verwendet haben: Benutzer zur Anmeldung und Zustimmung schicken.
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 TenantID-Wert (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 Authentifizierungsabläufe.

Schritt 3: Zugriffstoken im Hintergrund aktualisieren (keine Benutzeraufforderung)

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

  • Geben Sie die refresh_token anstelle der code im Anforderungstext ein.
  • Angeben refresh_token anstelle als authorization_code grant_type.
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, bei 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. Auch bekannt als appId.
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. Den Bereichen, die Ihre App anfordert, muss sie den Bereichen entsprechen, die in Schritt 2 angefordert wurden : Einlösen des Autorisierungscodes für Token.
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 die folgenden Ergebnisse:

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

Ablauf der Clientanmeldeinformationen (nur App)

Verwenden Sie diesen Flow für Dienst-zu-Dienst-Aufrufe ohne einen Benutzer. Nachdem der Administrator den Anwendungsberechtigungen (z. B Exchange.ManageAsAppV2. ) zugestimmt und die erforderlichen RBAC-Rollen zugewiesen hat, fordern Sie 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, bei 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 Die App-ID-URI der Ressource mit dem .default Suffix. Für die Exchange Online Admin-API lautet https://outlook.office365.com/die ID-URI der Ressourcen-App , sodass der Bereichswert isthttps://outlook.office365.com/.default.

Dieser Wert informiert den Microsoft Identity Platform-Endpunkt, alle Berechtigungen auf App-Ebene, denen der Administrator zugestimmt hat, in das Zugriffstoken aufzunehmen.
client_secret Erforderlich Der geheime Clientschlüssel, den Sie im App-Registrierungsportal für Ihre App 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, schließen Sie das Zugriffstoken in den Autorisierungsheader für jeden nachfolgenden API-Aufruf 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 zum manuellen Erstellen eines Problems unformatierte HTTP-Anforderungen zum Abrufen von Token für geheime Clientschlüssel. Verwenden Sie in Produktions-Apps eine integrierte oder unterstützte Authentifizierungsbibliothek, um Sicherheitstoken abzurufen und geschützte Web-APIs aufzurufen. Beispielsweise die Microsoft Authentication Library (MSAL).

Die MSAL und andere unterstützte Authentifizierungsbibliotheken vereinfachen den Prozess durch die Verarbeitung von Details, sodass Sie sich auf die Funktionalität Ihrer App konzentrieren können. Zum Beispiel:

  • Validierung.
  • Umgang mit Cookies.
  • Zwischenspeicherung von Token.
  • Sichere Verbindungen.

Microsoft verwaltet eine große Auswahl an Codebeispielen, die unterstützte Authentifizierungsbibliotheken mit der Microsoft Identity Platform demonstrieren. Um auf diese Codebeispiele zuzugreifen, siehe Microsoft Identity Platform Codebeispiele.

Beispiele zum Abrufen von Token mithilfe von Zertifikaten finden Sie unter Microsoft Identity Platform und der OAuth 2.0 Client Credential Flow.

  • Zuletzt aktualisiert um