OAuth 2.0-Mechanismus

In diesem Dokument wird der SASL XOAUTH2-Mechanismus für die Verwendung mit den Befehlen IMAPAUTHENTICATE, POPAUTH und SMTPAUTH definiert. Mit diesem Mechanismus können OAuth 2.0-Zugriffstokens verwendet werden, um sich beim Gmail-Konto eines Nutzers zu authentifizieren.

Verwenden von OAuth 2.0

Lesen Sie sich zuerst den Hilfeartikel Mit OAuth 2.0 auf Google APIs zugreifen durch. In diesem Dokument wird beschrieben, wie OAuth 2.0 funktioniert und welche Schritte zum Erstellen eines Clients erforderlich sind.

Im Beispielcode für XOAUTH2 finden Sie weitere Beispiele.

OAuth 2.0-Bereiche

Der Umfang des IMAP-, POP- und SMTP-Zugriffs ist https://mail.google.com/. Wenn Sie für Ihre IMAP-, POP- oder SMTP-App Zugriff auf den gesamten E-Mail-Bereich anfordern, muss sie unserer Nutzerdatenrichtlinie für Google API-Dienste entsprechen.

  • Damit Ihre App genehmigt werden kann, muss https://mail.google.com/ vollständig genutzt werden.
  • Wenn für Ihre App keine https://mail.google.com/ erforderlich ist, migrieren Sie zur Gmail API und verwenden Sie detailliertere eingeschränkte Bereiche.

Domainweite Delegierung für Google Workspace

Wenn Sie die Google Workspace domainweite Delegierung mit Dienstkonten verwenden möchten, um über IMAP auf die Postfächer von Google Workspace Nutzern zuzugreifen, können Sie Ihren Client stattdessen mit dem Umfang https://www.googleapis.com/auth/gmail.imap_admin autorisieren.

Bei einer Autorisierung mit diesem Umfang verhalten sich IMAP-Verbindungen anders:

  • Alle Labels werden über IMAP angezeigt, auch wenn Nutzer die Option „In IMAP anzeigen“ für das Label in den Gmail-Einstellungen deaktiviert haben.
  • Alle Nachrichten werden über IMAP angezeigt, unabhängig davon, was der Nutzer in den Gmail-Einstellungen unter „Größenbeschränkungen für Ordner“ festgelegt hat.

Der SASL XOAUTH2-Mechanismus

Mit dem XOAUTH2-Mechanismus können Clients OAuth 2.0-Zugriffstokens an den Server senden. Das Protokoll verwendet codierte Werte, die in den folgenden Abschnitten dargestellt sind.

Erste Antwort des Kunden

Die erste Clientantwort von SASL XOAUTH2 hat das folgende Format:

base64("user=" {User} "^Aauth=Bearer " {Access Token} "^A^A")

Verwenden Sie den Base64-Codierungsmechanismus, der in RFC 4648 definiert ist. ^A steht für „Strg + A“ (\001).

Vor der Base64-Codierung könnte die ursprüngliche 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 besseren Lesbarkeit eingefügt):

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

Fehlerantwort

Wenn eine erste Clientantwort zu einem Fehler führt, sendet der Server eine Herausforderung 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 sieht das so aus (zur besseren Verständlichkeit formatiert):

{
  "status":"401",
  "schemes":"bearer",
  "scope":"https://mail.google.com/"
}

Das SASL-Protokoll erfordert, dass Clients eine leere Antwort auf diese Herausforderung senden.

IMAP-Protokollaustausch

In diesem Abschnitt wird beschrieben, wie Sie SASL XOAUTH2 mit dem Gmail-IMAP-Server verwenden.

Erste Antwort des Kunden

Um sich mit dem SASL XOAUTH2-Mechanismus anzumelden, ruft der Client den Befehl AUTHENTICATE mit dem Mechanismusparameter XOAUTH2 und der oben erstellten ersten Clientantwort 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...]

Hinweise zum IMAP-Protokollaustausch:

  • Der IMAP-Befehl AUTHENTICATE ist in RFC 3501 dokumentiert.
  • Mit der SASL-IR-Funktion kann die erste Clientantwort in der ersten Zeile des Befehls AUTHENTICATE gesendet werden, sodass für die Authentifizierung nur ein Roundtrip 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 für den Befehl AUTHENTICATE angegeben wird.
  • Die Zeilenumbrüche in den AUTHENTICATE- und CAPABILITY-Befehlen dienen der besseren Verständlichkeit und sind in den tatsächlichen Befehlsdaten nicht enthalten. Das gesamte Base64-Argument sollte ein zusammenhängender String ohne eingebettete Leerzeichen sein, sodass der gesamte AUTHENTICATE-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

Hinweise zum IMAP-Protokollaustausch:

  • Der Client sendet eine leere Antwort („\r\n“) an die Herausforderung mit der Fehlermeldung.

POP Protocol Exchange

In diesem Abschnitt wird beschrieben, wie Sie SASL XOAUTH2 mit dem Gmail-POP-Server verwenden.

Erste Antwort des Kunden

Um sich mit dem SASL XOAUTH2-Mechanismus anzumelden, ruft der Client den Befehl AUTH mit dem Mechanismusparameter XOAUTH2 und der oben erstellten ersten Clientantwort auf. Beispiel:

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

Hinweise zum POP-Protokollaustausch:

  • Der POP AUTH-Befehl ist in RFC 1734 dokumentiert.
  • Die Zeilenumbrüche im AUTH-Befehl dienen der Übersichtlichkeit und sind in den tatsächlichen Befehlsdaten nicht vorhanden. Das gesamte Base64-Argument sollte ein zusammenhängender String ohne eingebettete Leerzeichen sein, sodass der gesamte AUTH-Befehl aus einer einzigen Textzeile besteht.

Fehlerantwort

Authentifizierungsfehler werden auch über den POP AUTH-Befehl zurückgegeben:

[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: + eyJzdGF0dXMiOiI0MDAiLCJzY2hlbWVzIjoiQmVhcmVyIiwic2NvcGUi
OiJodHRwczovL21haWwuZ29vZ2xlLmNvbS8ifQ==

SMTP Protocol Exchange

In diesem Abschnitt wird erläutert, wie Sie SASL XOAUTH2 mit dem Gmail-SMTP-Server verwenden.

Erste Antwort des Kunden

Um sich mit dem XOAUTH2-Mechanismus anzumelden, ruft der Client den Befehl AUTH mit dem Mechanismusparameter XOAUTH2 und der oben erstellten ersten Clientantwort auf. 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 in RFC 4954 dokumentiert.
  • Die Zeilenumbrüche im AUTH-Befehl dienen der Übersichtlichkeit und sind in den tatsächlichen Befehlsdaten nicht vorhanden. Das gesamte Base64-Argument sollte ein zusammenhängender String ohne eingebettete Leerzeichen sein, sodass der gesamte AUTH-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“) an die Herausforderung mit der Fehlermeldung.

Verweise