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 wird sowohl für Microsoft 365 (einschließlich Office im Web) als auch für Outlook.com-Benutzer unterstützt.

Wenn Sie mit dem OAuth 2.0-Protokoll nicht vertraut sind, lesen Sie zunächst das OAuth 2.0-Protokoll in Microsoft Identity Platform Übersicht. Weitere Informationen zu den Microsoft Authentication Libraries (MSAL), die das OAuth 2.0-Protokoll implementieren, um Benutzer zu authentifizieren und auf sichere APIs zuzugreifen, finden Sie in der MSAL-Übersicht.

Sie können den von Azure Active Directory (Azure AD) bereitgestellten OAuth-Authentifizierungsdienst verwenden, um Ihrer Anwendung das Herstellen einer 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 Azure AD.
  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 Azure Active Directory 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 das SASL-XOAUTH2-Format verwendet, um das Zugriffstoken zu codieren und zu übertragen. SASL XOAUTH2 codiert den Benutzernamen und das Zugriffstoken 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 dies in die folgende Zeichenfolge übersetzt. Beachten Sie, dass Zeilenumbrüche zur Lesbarkeit eingefügt werden.

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 die 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 Protokollen SMTP, POP und IMAP zu ermöglichen.

Hinweis

Derzeit unterstützt Exchange Online keinen SMTP-Oauth 2.0-Clientanmeldeinformationsfluss mit nicht interaktiver Anmeldung. Wir arbeiten daran, und es wird bis Ende 2023 verfügbar sein.

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

  1. Wählen Sie im Azure-Portal das Blatt API-Berechtigungen in der Verwaltungsansicht Ihrer Azure AD-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 die SMTP-, POP- oder IMAP-Anwendungsberechtigungen den Berechtigungen Ihrer AAD-Anwendung hinzugefügt haben.

Für den Zugriff auf Exchange-Postfächer über POP oder IMAP muss Ihre AAD-Anwendung die Zustimmung des Mandantenadministrators für jeden Mandanten einholen. Weitere Informationen finden Sie unter Zustimmungsprozess für Mandantenadministratoren.

Wenn Ihr ISV/Partner die Azure AD-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. Es folgt ein Beispiel für die OAuth 2.0-Autorisierungsanforderungs-URL:

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 . Es folgt ein Beispiel für die OAuth 2.0-Autorisierungsanforderungs-URL:

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 einfach fortfahren und die Anwendungskonfigurationsseite im Azure AD Admin Center verwenden, um dem Administrator die Zustimmung zu erteilen, ohne die Autorisierungsanforderungs-URL approch zu verwenden.

Bild

Registrieren von Dienstprinzipalen in Exchange

Sobald Ihre Azure AD-Anwendung von einem Mandantenadministrator zugestimmt wurde, muss der Mandantenadministrator den Dienstprinzipal Ihrer AAD-Anwendung in Exchange über Exchange Online PowerShell registrieren. Dies 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 ausreichende Berechtigungen in Exchange Online verfügt, um den Vorgang auszuführen.

Im Folgenden finden Sie ein Beispiel für die Registrierung des Dienstprinzipals einer Azure AD-Anwendung in Exchange:

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

Der Mandantenadministrator kann die oben referenzierten Dienstprinzipalbezeichner in der Unternehmensanwendung Ihrer AAD-Anwendung instance auf dem Mandanten finden. Sie finden die Liste der Unternehmensanwendungsinstanzen auf dem Mandanten auf dem Blatt Unternehmensanwendungen in der Azure Active Directory-Ansicht 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. Dies ist nicht die Objekt-ID aus der Ü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. Dies erfolgt mit dem Add-MailboxPermission Cmdlet.

Im Folgenden finden Sie ein Beispiel dafür, 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 während 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 Azure AD-Cmdelts verwendet, sodass Sie das Azure AD PowerShell-Modul installieren müssen, sofern noch nicht geschehen. Weitere Informationen finden Sie unter Installieren von Azure Active Directory PowerShell für Graph.

$AADServicePrincipalDetails = Get-AzureADServicePrincipal -SearchString YourAppName

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

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

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

Ihre Azure AD-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 wie zuvor beschrieben als Token verwendet werden, um SMTP-, POP- und IMAP-Verbindungen über das SASL-XOAUTH2-Format zu authentifizieren.

Siehe auch