Authentifizieren einer IMAP-, POP- oder SMTP-Verbindung mithilfe von OAuth

  • Artikel

Erfahren Sie, wie Sie die OAuth-Authentifizierung verwenden, um eine Verbindung mit IMAP-, POP- oder SMTP-Protokollen herzustellen und auf E-Mail-Daten für Office 365 Benutzer zuzugreifen.

OAuth2-Unterstützung für IMAP-, POP- und SMTP-Protokolle wie unten beschrieben ist sowohl für Microsoft 365 (einschließlich Office im Web) als auch für Outlook.com Benutzer verfügbar.

Wichtig

In dieser Dokumentation wird der veraltete Outlook-REST-API-Bereich verwendet. Neue Anwendungen sollten stattdessen den Graph-REST-API-Endpunkt verwenden.

Wenn Sie mit dem OAuth 2.0-Protokoll nicht vertraut sind, finden Sie weitere Informationen unter OAuth 2.0-Protokoll unter Microsoft Identity Platform Übersicht. Weitere Informationen zu den Microsoft-Authentifizierungsbibliotheken (MSAL), die das OAuth 2.0-Protokoll implementieren, um Benutzer zu authentifizieren und auf sichere APIs zuzugreifen, finden Sie unter MSAL-Übersicht.

Sie können den von Microsoft Entra (Microsoft Entra) bereitgestellten OAuth-Authentifizierungsdienst verwenden, um Ihrer Anwendung den Zugriff auf Exchange Online in Office 365 mit IMAP-, POP- oder SMTP-Protokollen zu ermöglichen. Um OAuth mit Ihrer Anwendung zu verwenden, müssen Sie:

  1. Registrieren Sie Ihre Anwendung bei Microsoft Entra.
  2. Abrufen eines Zugriffstokens von einem Tokenserver.
  3. Authentifizieren Sie Verbindungsanforderungen mit einem Zugriffstoken.

Registrieren der App

Um OAuth verwenden zu können, muss eine Anwendung bei Microsoft Entra registriert werden.

Befolgen Sie die Anweisungen unter Registrieren einer Anwendung beim Microsoft Identity Platform, um eine neue Anwendung zu erstellen.

Abrufen eines Zugriffstokens

Sie können eine unserer MSAL-Clientbibliotheken verwenden, um ein Zugriffstoken aus Ihrer Clientanwendung abzurufen.

Alternativ können Sie einen geeigneten Flow aus der folgenden Liste auswählen und die entsprechenden Schritte ausführen, um die zugrunde liegenden Identity Platform-REST-APIs aufzurufen und ein Zugriffstoken abzurufen.

  1. OAuth2-Autorisierungscodeflow
  2. OAuth2-Geräteautorisierungsgenehmigungsflow
  3. Fluss zur Gewährung von OAuth2-Clientanmeldeinformationen

Stellen Sie sicher, dass Sie die vollständigen Bereiche angeben, einschließlich outlook-Ressourcen-URLs, wenn Sie Ihre Anwendung autorisieren und ein Zugriffstoken anfordern.

Protokoll Berechtigungsbereichszeichenfolge
IMAP https://outlook.office.com/IMAP.AccessAsUser.All
POP https://outlook.office.com/POP.AccessAsUser.All
SMTP AUTH https://outlook.office.com/SMTP.SendAsApp

Darüber hinaus können Sie offline_access Bereich anfordern. Wenn ein Benutzer den offline_access Bereich genehmigt, kann Ihre App Aktualisierungstoken vom Microsoft Identity Platform Tokenendpunkt empfangen. Aktualisierungstoken sind langlebig. Ihre App kann neue Zugriffstoken erhalten, wenn ältere ablaufen.

Authentifizieren von Verbindungsanforderungen

Sie können eine Verbindung mit Office 365-E-Mail-Servern initiieren, indem Sie die E-Mail-Einstellungen IMAP und POP für Office 365 verwenden.

SASL-XOAUTH2

Die OAuth-Integration erfordert, dass Ihre Anwendung sasl XOAUTH2 Format verwendet, um das Zugriffstoken zu codieren und zu übertragen. SASL XOAUTH2 codiert den Benutzernamen und das Zugriffstoken zusammen im folgenden Format:

base64("user=" + userName + "^Aauth=Bearer " + accessToken + "^A^A")

^A stellt ein Steuerelement + A (%x01) dar.

Das SASL-XOAUTH2 Format für den Zugriff test@contoso.onmicrosoft.com mit Zugriffstoken EwBAAl3BAAUFFpUAo7J3Ve0bjLBWZWCclRC3EoAA lautet beispielsweise:

base64("user=test@contoso.onmicrosoft.com^Aauth=Bearer EwBAAl3BAAUFFpUAo7J3Ve0bjLBWZWCclRC3EoAA^A^A")

Nach der Base64-Codierung wird dieses Format in die folgende Zeichenfolge übersetzt. Die Zeilenumbrüche werden zur Lesbarkeit eingefügt.

dXNlcj10ZXN0QGNvbnRvc28ub25taWNyb3NvZnQuY29tAWF1dGg9QmVhcmVy
IEV3QkFBbDNCQUFVRkZwVUFvN0ozVmUwYmpMQldaV0NjbFJDM0VvQUEBAQ==

SASL-XOAUTH2-Authentifizierung für freigegebene Postfächer in Office 365

Im Fall des Zugriffs auf freigegebene Postfächer mithilfe von OAuth muss eine Anwendung das Zugriffstoken im Namen eines Benutzers abrufen, aber das Feld userName in der SASL-XOAUTH2 codierten Zeichenfolge durch die E-Mail-Adresse des freigegebenen Postfachs ersetzen.

IMAP-Protokollaustausch

Um eine IMAP-Serververbindung zu authentifizieren, muss der Client mit einem AUTHENTICATE Befehl im folgenden Format antworten:

AUTHENTICATE XOAUTH2 <base64 string in XOAUTH2 format>

Beispiel für den Client-Server-Nachrichtenaustausch, der zu einer erfolgreichen Authentifizierung führt:

[connection begins]
C: C01 CAPABILITY
S: * CAPABILITY … AUTH=XOAUTH2
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==
S: A01 OK AUTHENTICATE completed.

Beispiel für den Client-Server-Nachrichtenaustausch, der zu einem Authentifizierungsfehler führt:

[connection begins]
S: * CAPABILITY … AUTH=XOAUTH2
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==
S: A01 NO AUTHENTICATE failed.

POP-Protokollaustausch

Um eine POP-Serververbindung zu authentifizieren, muss der Client mit einem AUTH Befehl antworten, der in zwei Zeilen im folgenden Format unterteilt ist:

AUTH XOAUTH2 
<base64 string in XOAUTH2 format>

Beispiel für den Client-Server-Nachrichtenaustausch, der zu einer erfolgreichen Authentifizierung führt:

[connection begins] 
C: AUTH XOAUTH2  
S: + 
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYX 
JlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0 
Q2cBAQ== 
S: +OK User successfully authenticated. 
[connection continues...]

Beispiel für den Client-Server-Nachrichtenaustausch, der zu einem Authentifizierungsfehler führt:

[connection begins] 
C: AUTH XOAUTH2  
S: + 
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY 
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj 
l0Q2cBAQ= 
S: -ERR Authentication failure: unknown user name or bad password.

SMTP-Protokollaustausch

Um eine SMTP-Serververbindung zu authentifizieren, muss der Client mit einem AUTH Befehl im folgenden Format antworten:

AUTH XOAUTH2 <base64 string in XOAUTH2 format>

Beispiel für den Client-Server-Nachrichtenaustausch, der zu einer erfolgreichen Authentifizierung führt:

[connection begins]
C: auth xoauth2
S: 334
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: 235 2.7.0 Authentication successful
[connection continues...]

Beispiel für den Client-Server-Nachrichtenaustausch, der zu einem Authentifizierungsfehler führt:

[connection begins]
C: auth xoauth2
S: 334
C: dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: 535 5.7.3 Authentication unsuccessful [SN2PR00CA0018.namprd00.prod.outlook.com]

Verwenden des Flusses zur Gewährung von Clientanmeldeinformationen zum Authentifizieren von SMTP-, IMAP- und POP-Verbindungen

Dienstprinzipale in Exchange werden verwendet, um Anwendungen den Zugriff auf Exchange-Postfächer über den Clientanmeldeinformationsfluss mit den SMTP-, POP- und IMAP-Protokollen zu ermöglichen.

Hinzufügen der POP-, IMAP- oder SMTP-Berechtigungen zu Ihrer Entra AD-Anwendung

  1. Wählen Sie im Azure-Portal das Blatt API-Berechtigungen in der Verwaltungsansicht Ihrer Microsoft Entra Anwendung aus.

  2. Wählen Sie Berechtigung hinzufügen aus.

  3. Wählen Sie die Registerkarte APIs aus, die mein organization verwendet, und suchen Sie nach "Office 365 Exchange Online".

  4. Klicken Sie auf Anwendungsberechtigungen.

  5. Wählen Sie für POP-Zugriff die OPTION POP aus. AccessAsApp-Berechtigung . Wählen Sie für DEN IMAP-Zugriff den IMAP-Befehl aus. AccessAsApp-Berechtigung . Wählen Sie für SMTP-Zugriff die OPTION SMTP aus. SendAsApp-Berechtigung .

    pop-imap-permission

  6. Nachdem Sie den Berechtigungstyp ausgewählt haben, wählen Sie Berechtigungen hinzufügen aus.

Sie sollten nun über die SMTP-, POP- oder IMAP-Anwendungsberechtigungen verfügen, die den Berechtigungen Ihrer Entra AD-Anwendung hinzugefügt werden.

Um über POP oder IMAP auf Exchange-Postfächer zugreifen zu können, muss Ihre Entra AD-Anwendung die Zustimmung des Mandantenadministrators für jeden Mandanten einholen. Weitere Informationen finden Sie unter Zustimmungsprozess für Mandantenadministratoren.

Wenn Ihr ISV/Partner die Microsoft Entra Anwendung mit der Option "Konten in einem beliebigen Organisationsverzeichnis" registriert hat, müssen Sie diese Anwendung hinzufügen und ihr mit den folgenden Schritten zustimmen, indem Sie die Autorisierungsanforderungs-URL nutzen.

POP- und IMAP-Leitfaden

In Ihrer OAuth 2.0-Mandantenautorisierungsanforderung sollte https://ps.outlook.com/.default der scope Abfrageparameter sowohl für den POP- als auch für den IMAP-Anwendungsbereich gelten. Die OAuth 2.0-Autorisierungsanforderungs-URL wird im folgenden Beispiel gezeigt:

https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&scope=https://ps.outlook.com/.default
SMTP-Leitfaden

In Ihrer OAuth 2.0-Mandantenautorisierungsanforderung sollte der scope Abfrageparameter nur für SMTP sein https://outlook.office365.com/.default . Die OAuth 2.0-Autorisierungsanforderungs-URL wird im folgenden Beispiel gezeigt:

https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&scope=https://outlook.office365.com/.default

Wenn Sie Ihre Anwendung in Ihrem eigenen Mandanten mit "Nur Konten in diesem Organisationsverzeichnis" registriert haben, können Sie fortfahren und die Anwendungskonfigurationsseite innerhalb des Microsoft Entra Admin Center verwenden, um dem Administrator die Zustimmung zu erteilen, und Sie müssen nicht den Ansatz für die Autorisierungsanforderungs-URL verwenden.

granting-consent-for-tenant

Registrieren von Dienstprinzipalen in Exchange

Sobald ein Mandantenadministrator Ihrer Microsoft Entra Anwendung zugestimmt hat, muss er den Dienstprinzipal Ihrer Entra AD-Anwendung über Exchange Online PowerShell in Exchange registrieren. Diese Registrierung wird durch das New-ServicePrincipal Cmdlet aktiviert.

Um das Cmdlet New-ServicePrincipal zu verwenden, installieren Sie ExchangeOnlineManagement, und stellen Sie eine Verbindung mit Ihrem Mandanten her, wie im folgenden Codeausschnitt gezeigt:

Install-Module -Name ExchangeOnlineManagement -allowprerelease
Import-module ExchangeOnlineManagement 
Connect-ExchangeOnline -Organization <tenantId>

Wenn nach dem Ausführen dieser Schritte weiterhin ein Fehler beim Ausführen des Cmdlets New-ServicePrincipal angezeigt wird, liegt dies wahrscheinlich daran, dass der Benutzer nicht über genügend Berechtigungen in Exchange Online verfügt, um den Vorgang auszuführen.

Die Registrierung des Dienstprinzipals einer Microsoft Entra Anwendung in Exchange wird im folgenden Beispiel gezeigt:

New-ServicePrincipal -AppId <APPLICATION_ID> -ObjectId <OBJECT_ID> [-Organization <ORGANIZATION_ID>]

Der Mandantenadministrator kann die oben referenzierten Dienstprinzipalbezeichner in der Unternehmensanwendung Ihrer Entra AD-Anwendung instance auf dem Mandanten finden. Sie finden die Liste der Unternehmensanwendungsinstanzen auf dem Mandanten auf dem Blatt Unternehmensanwendungen in der Ansicht Microsoft Entra im Azure-Portal.

Sie können den Bezeichner Ihres registrierten Dienstprinzipals mithilfe des Get-ServicePrincipal Cmdlets abrufen.

Get-ServicePrincipal | fl

Die OBJECT_ID ist die Objekt-ID auf der Seite Übersicht des Knotens Unternehmensanwendung (Azure-Portal) für die Anwendungsregistrierung. Es handelt sich nicht um die Objekt-ID auf der Seite Übersicht des Knotens App-Registrierungen. Die Verwendung der falschen Objekt-ID führt zu einem Authentifizierungsfehler.

Der Mandantenadministrator kann jetzt die spezifischen Postfächer im Mandanten hinzufügen, auf die Ihre Anwendung zugreifen kann. Diese Konfiguration erfolgt mit dem Add-MailboxPermission Cmdlet.

Das folgende Beispiel zeigt, wie Sie dem Dienstprinzipal Ihrer Anwendung Zugriff auf ein Postfach gewähren:

Add-MailboxPermission -Identity "john.smith@contoso.com" -User 
<SERVICE_PRINCIPAL_ID> -AccessRights FullAccess

Unterschiedliche IDs werden bei der Erstellung des Exchange-Dienstprinzipals und später auch beim Erteilen von Postfachberechtigungen verwendet. Das folgende Beispiel kann Ihnen helfen, die richtige ID für die verschiedenen Phasen zu verwenden. In diesem Beispiel werden Microsoft Entra-Cmdlets verwendet. Daher müssen Sie das Microsoft Entra PowerShell-Modul installieren, sofern noch nicht geschehen. Weitere Informationen finden Sie unter Installieren Microsoft Entra PowerShell für Graph.

$AADServicePrincipalDetails = Get-AzureADServicePrincipal -SearchString YourAppName

New-ServicePrincipal -AppId $AADServicePrincipalDetails.AppId -ObjectId $AADServicePrincipalDetails.ObjectId -DisplayName "EXO Serviceprincipal for EntraAD App $($AADServicePrincipalDetails.Displayname)"

$EXOServicePrincipal = Get-ServicePrincipal -Identity "EXO Serviceprincipal for EntraAD App YourAppName"

Add-MailboxPermission -Identity "john.smith@contoso.com" -User $EXOServicePrincipal.Identity -AccessRights FullAccess

Ihre Microsoft Entra-Anwendung kann jetzt über das SMTP-, POP- oder IMAP-Protokoll mithilfe des OAuth 2.0-Clientanmeldeinformations-Genehmigungsflows auf die zulässigen Postfächer zugreifen. Weitere Informationen finden Sie in den Anweisungen unter Berechtigungen und Zustimmung im Microsoft Identity Platform.

Sie müssen in der scope -Eigenschaft in der Textnutzlast für die Zugriffstokenanforderung verwendenhttps://outlook.office365.com/.default.

Die generierten Zugriffstoken können als Token verwendet werden, um SMTP-, POP- und IMAP-Verbindungen über SASL XOAUTH2 format zu authentifizieren, wie zuvor beschrieben.

Siehe auch