Freigeben über


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

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 Outlook.com Benutzer verfügbar.

Wenn Sie nicht mit dem OAuth 2.0-Protokoll vertraut sind, lesen Sie die Übersicht über das OAuth 2.0-Protokoll auf Microsoft Identity Platform. 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 eine Verbindung mit IMAP-, POP- oder SMTP-Protokollen für den Zugriff auf Exchange Online in Office 365 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 sein.

Befolgen Sie die Anweisungen unter Registrieren einer Anwendung bei 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

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

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.

Alternativ können Sie den Zuweisungsflow für OAuth2-Clientanmeldeinformationen verwenden, um ein Zugriffstoken abzurufen, anstatt den OAuth2-Autorisierungscodeflow oder den OAuth2-Autorisierungserteilungsflow zu verwenden.

Authentifizieren von Verbindungsanforderungen

Sie können eine Verbindung mit Office 365-E-Mail-Servern mithilfe der IMAP- und POP-E-Mail-Einstellungen für Office 365 initiieren.

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 meine Organisation 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 im Microsoft Entra Admin Center verwenden, um dem Administrator die Zustimmung zu erteilen, und Sie müssen nicht den Ansatz der 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 Unternehmensanwendungsinstanz Ihrer Entra AD-Anwendung 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 von 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 in 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