In diesem Dokument wird der SASL-XOAUTH2-Mechanismus für die Verwendung mit IMAP definiert.
AUTHENTICATE
-, POP-AUTH
- und SMTP-AUTH
-Befehle. Dieser Mechanismus ermöglicht
OAuth 2.0-Zugriffstokens zur Authentifizierung im Gmail-Konto eines Nutzers verwenden.
Verwenden von OAuth 2.0
Machen Sie sich zuerst mit OAuth 2.0 für den Zugriff auf Google APIs verwenden vertraut. In diesem Dokument wird erläutert, wie OAuth 2.0 funktioniert und welche Schritte zum Schreiben eines Clients erforderlich sind.
Sie können auch den XOAUTH2-Beispielcode nach funktionierenden Beispielen durchsuchen.
OAuth 2.0-Bereiche
Der Bereich für den IMAP-, POP- und SMTP-Zugriff ist https://mail.google.com/
. Wenn Sie
Zugriff auf den gesamten E-Mail-Bereich für Ihre IMAP-, POP- oder SMTP-App anfordern
Sie muss der Nutzerdatenrichtlinie der Google API-Dienste entsprechen.
- Für eine Genehmigung muss deine App die vollständige Auslastung von
https://mail.google.com/
nachweisen. - Wenn deine App
https://mail.google.com/
nicht benötigt, migriere zu Gmail API und verwenden Sie detailliertere eingeschränkte Bereiche.
Domainweite Delegierung für Google Workspace
Wenn Sie vorhaben,
Google Workspace domainweite Delegierung
mit
Dienstkonten
für Zugriff auf Google Workspace die über IMAP zu verwalten,
können Sie Ihren Client mithilfe des Geltungsbereichs
https://www.googleapis.com/auth/gmail.imap_admin
.
Bei der Autorisierung mit diesem Bereich verhalten sich IMAP-Verbindungen anders:
- Alle Labels werden über IMAP angezeigt, auch wenn Nutzer die Option "In IMAP anzeigen" deaktiviert haben. für das Label in den Gmail-Einstellungen.
- Alle Nachrichten werden über IMAP angezeigt, unabhängig von den Einstellungen, die der Nutzer unter "Grenzen für die Ordnergröße" festgelegt hat. in den Gmail-Einstellungen.
Der SASL-XOAUTH2-Mechanismus
Mit dem XOAUTH2-Mechanismus können Clients Zugriffstokens für OAuth 2.0 an den Server senden. Im Protokoll werden codierte Werte verwendet, die in den folgenden Abschnitten gezeigt werden.
Erste Antwort des Kunden
Die erste SASL-XOAUTH2-Clientantwort hat das folgende Format:
base64("user=" {User} "^Aauth=Bearer " {Access Token} "^A^A")
Verwenden Sie den in RFC 4648 definierten base64-Codierungsmechanismus. ^A
steht für „Strg + A“ (\001).
Vor der base64-Codierung könnte die erste Clientantwort beispielsweise so aussehen:
user=someuser@example.com^Aauth=Bearer ya29.vF9dft4qmTc2Nvb3RlckBhdHRhdmlzdGEuY29tCg^A^A
Nach der base64-Codierung sieht das so aus (Zeilenumbrüche zur Verdeutlichung eingefügt):
dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==
Fehlerantwort
Eine erste Clientantwort, die einen Fehler verursacht, führt dazu, dass der Server eine Aufgabe mit einer Fehlermeldung im folgenden Format:
base64({JSON-Body})
JSON-Body enthält drei Werte: status
, schemes
und scope
. Beispiel:
eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K
Nach der base64-Decodierung wird dies (zur Übersichtlichkeit formatiert):
{
"status":"401",
"schemes":"bearer",
"scope":"https://mail.google.com/"
}
Gemäß dem SASL-Protokoll müssen Clients eine leere Antwort auf diese Abfrage senden.
IMAP-Protokollaustausch
In diesem Abschnitt wird erläutert, wie Sie SASL XOAUTH2 mit dem Gmail-IMAP-Server verwenden.
Erste Antwort des Kunden
Für die Anmeldung mit dem SASL XOAUTH2-Mechanismus ruft der Client den Befehl AUTHENTICATE
mit dem Mechanismusparameter XOAUTH2
und die ursprüngliche Clientantwort wie oben erstellt auf. Beispiel:
[connection begins]
C: C01 CAPABILITY
S: * CAPABILITY IMAP4rev1 UNSELECT IDLE NAMESPACE QUOTA XLIST
CHILDREN XYZZY SASL-IR AUTH=XOAUTH2 AUTH=XOAUTH
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvb
QFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG
1semRHRXVZMjl0Q2cBAQ==
S: A01 OK Success
[connection continues...]
Wichtige Hinweise zum IMAP-Protokollaustausch:
- Der IMAP-Befehl
AUTHENTICATE
ist unter RFC 3501 dokumentiert. - Die SASL-IR-Funktion ermöglicht das Senden der ersten Clientantwort in der ersten Zeile des
AUTHENTICATE
-Befehls, sodass nur ein Umlauf für die Authentifizierung erforderlich ist. SASL-IR ist in RFC 4959 dokumentiert. - Die Funktion AUTH=XOAUTH2 gibt an, dass der Server den in diesem Dokument definierten SASL-Mechanismus unterstützt. Dieser Mechanismus wird aktiviert, indem XOAUTH2 als erstes Argument im Befehl
AUTHENTICATE
angegeben wird. - Die Zeilenumbrüche in den Befehlen
AUTHENTICATE
undCAPABILITY
dienen der Übersichtlichkeit und sind in den eigentlichen Befehlsdaten nicht vorhanden. Das gesamte base64-Argument sollte ein fortlaufender String ohne eingebettetes Leerzeichen sein, sodass der gesamteAUTHENTICATE
-Befehl aus einer einzigen Textzeile besteht.
Fehlerantwort
Authentifizierungsfehler werden auch über den IMAP-Befehl AUTHENTICATE
zurückgegeben:
[connection begins]
S: * CAPABILITY IMAP4rev1 UNSELECT IDLE NAMESPACE QUOTA XLIST
CHILDREN XYZZY SASL-IR AUTH=XOAUTH2
S: C01 OK Completed
C: A01 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQ
FhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1s
emRHRXVZMjl0Q2cBAQ==
S: + eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb
3BlIjoiaHR0cHM6Ly9tYWlsLmdvb2dsZS5jb20vIn0K
C:
S: A01 NO SASL authentication failed
Wichtige Hinweise zum IMAP-Protokollaustausch:
- Der Client sendet eine leere Antwort („\r\n“) auf die Aufgabe, die die Fehlermeldung enthält.
POP-Protokollaustausch
In diesem Abschnitt wird erläutert, wie Sie SASL XOAUTH2 mit dem Gmail-POP-Server verwenden.
Erste Antwort des Kunden
Für die Anmeldung mit dem SASL-XOAUTH2-Mechanismus ruft der Client den Befehl AUTH
mit dem Mechanismusparameter XOAUTH2
und die ursprüngliche Clientantwort wie oben erstellt auf. Beispiel:
[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYX
JlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0
Q2cBAQ==
S: +OK Welcome.
[connection continues...]
Hinweise zum POP-Protokollaustausch:
- Der POP-Befehl
AUTH
ist in RFC 1734 dokumentiert. - Die Zeilenumbrüche im Befehl
AUTH
dienen der Übersichtlichkeit und sind in den eigentlichen Befehlsdaten nicht vorhanden. Das gesamte base64-Argument sollte ein fortlaufender String ohne eingebettetes Leerzeichen sein, sodass der gesamteAUTH
-Befehl aus einer einzigen Textzeile besteht.
Fehlerantwort
Authentifizierungsfehler werden auch über den POP-Befehl AUTH
zurückgegeben:
[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: + eyJzdGF0dXMiOiI0MDAiLCJzY2hlbWVzIjoiQmVhcmVyIiwic2NvcGUi
OiJodHRwczovL21haWwuZ29vZ2xlLmNvbS8ifQ==
SMTP-Protokollaustausch
In diesem Abschnitt wird erläutert, wie Sie SASL XOAUTH2 mit dem Gmail-SMTP-Server verwenden.
Erste Antwort des Kunden
Für die Anmeldung mit dem XOAUTH2-Mechanismus ruft der Client den Befehl AUTH
mit dem Mechanismusparameter XOAUTH2
und die ursprüngliche Clientantwort auf, wie oben dargestellt. Beispiel:
[connection begins]
S: 220 mx.google.com ESMTP 12sm2095603fks.9
C: EHLO sender.example.com
S: 250-mx.google.com at your service, [172.31.135.47]
S: 250-SIZE 35651584
S: 250-8BITMIME
S: 250-AUTH LOGIN PLAIN XOAUTH XOAUTH2
S: 250-ENHANCEDSTATUSCODES
S: 250 PIPELINING
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: 235 2.7.0 Accepted
[connection continues...]
Hinweise zum SMTP-Protokollaustausch:
- Der SMTP-Befehl
AUTH
ist unter RFC 4954 dokumentiert. - Die Zeilenumbrüche im Befehl
AUTH
dienen der Übersichtlichkeit und sind in den eigentlichen Befehlsdaten nicht vorhanden. Das gesamte base64-Argument sollte ein fortlaufender String ohne eingebettetes Leerzeichen sein, sodass der gesamteAUTH
-Befehl aus einer einzigen Textzeile besteht.
Fehlerantwort
Authentifizierungsfehler werden auch über den SMTP-Befehl AUTH
zurückgegeben:
[connection begins]
S: 220 mx.google.com ESMTP 12sm2095603fks.9
C: EHLO sender.example.com
S: 250-mx.google.com at your service, [172.31.135.47]
S: 250-SIZE 35651584
S: 250-8BITMIME
S: 250-AUTH LOGIN PLAIN XOAUTH XOAUTH2
S: 250-ENHANCEDSTATUSCODES
S: 250 PIPELINING
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJl
ciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cB
AQ==
S: 334 eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb
3BlIjoiaHR0cHM6Ly9tYWlsLmdvb2dsZS5jb20vIn0K
C:
S: 535-5.7.1 Username and Password not accepted. Learn more at
S: 535 5.7.1 https://support.google.com/mail/?p=BadCredentials hx9sm5317360pbc.68
[connection continues...]
Hinweise zum SMTP-Protokollaustausch:
- Der Client sendet eine leere Antwort („\r\n“) auf die Aufgabe, die die Fehlermeldung enthält.
Verweise
- OAUTH2: Mit OAuth 2.0 auf Google APIs zugreifen
- SMTP: RFC 2821 – Simple Mail Transfer Protocol
- IMAP: RFC 3501: ZUGRIFFSPROTOKOLL FÜR INTERNETNETZWERKE – VERSION 4rev1
- POP: RFC 1081: Post Office Protocol – Version 3
- SASL: RFC 4422: Simple Authentication and Security Layer (SASL)
- JSON: RFC 4627: The application/json Media Type for JavaScript Object Notation
- BASE64: RFC 4648: Base16-, Base32- und Base64-Datencodierungen
- SASL-IR: RFC 4959: IMAP Extension for Simple Authentication and Security Layer (SASL) Initial Client Response
- SMTP-AUTH: RFC 4954: SMTP Service Extension for Authentication