Ten dokument określa mechanizm SASL XOAUTH2, którego można używać z poleceniami IMAP AUTHENTICATE
, POP AUTH
i SMTP AUTH
. Mechanizm ten umożliwia uwierzytelnianie na koncie Gmail użytkownika za pomocą tokenów dostępu OAuth 2.0.
Przy użyciu OAuth 2.0
Zacznij od zapoznania się z artykułem Korzystanie z protokołu OAuth 2.0 do uzyskiwania dostępu do interfejsów API Google. Ten dokument wyjaśnia, jak działa protokół OAuth 2.0 i jakie czynności należy wykonać, aby napisać klienta.
Możesz też przejrzeć przykładowy kod XOAUTH2, aby zobaczyć działające przykłady.
Zakresy OAuth 2.0
Zakres dostępu IMAP, POP i SMTP to https://mail.google.com/
. Jeśli prosisz aplikacji IMAP, POP lub SMTP o dostęp do pełnego zakresu poczty, musi ona być zgodna z zasadami dotyczącymi danych użytkownika związanymi z usługami interfejsu API Google.
- Aby aplikacja została zatwierdzona, musi wykazywać pełne wykorzystanie
https://mail.google.com/
. - Jeśli Twoja aplikacja nie wymaga
https://mail.google.com/
, przejdź do interfejsu Gmail API i użyj bardziej szczegółowych zakresów z ograniczeniami.
Przekazywanie dostępu w całej domenie dla użytkownika Google Workspace
Jeśli chcesz używać Google Workspace przekazywania dostępu w całej domenie za pomocą kont usługi do uzyskiwania dostępu do Google Workspace skrzynek pocztowych użytkowników przez IMAP, możesz zamiast tego autoryzować klienta za pomocą zakresuhttps://www.googleapis.com/auth/gmail.imap_admin
.
Przy autoryzacji tego zakresu połączenia IMAP działają inaczej:
- Wszystkie etykiety są wyświetlane przez IMAP, nawet jeśli w ustawieniach Gmaila użytkownicy wyłączyli dla danej etykiety opcję „Pokaż w kliencie IMAP”.
- Wszystkie wiadomości są wyświetlane przez IMAP, niezależnie od wartości ustawionej przez użytkownika w sekcji „Limity rozmiarów folderów” w ustawieniach Gmaila.
Mechanizm SASL XOAUTH2
Mechanizm XOAUTH2 pozwala klientom wysyłać do serwera tokeny dostępu OAuth 2.0. Protokół wykorzystuje zakodowane wartości przedstawione w kolejnych sekcjach.
Pierwsza odpowiedź klienta
Pierwsza odpowiedź klienta SASL XOAUTH2 ma taki format:
base64("user=" {User} "^Aauth=Bearer " {Access Token} "^A^A")
Użyj mechanizmu kodowania base64 zdefiniowanego w RFC 4648. ^A
to kombinacja Control+A (\001).
Na przykład przed zakodowaniem base64 początkowa odpowiedź klienta może wyglądać tak:
user=someuser@example.com^Aauth=Bearer ya29.vF9dft4qmTc2Nvb3RlckBhdHRhdmlzdGEuY29tCg^A^A
Po zakodowaniu base64 wygląda to tak (aby zwiększyć przejrzystość tekstu, wstawiono podziały wierszy):
dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==
Odpowiedź na błąd
Wstępna odpowiedź klienta powodująca błąd powoduje, że serwer wysyła wyzwanie zawierające komunikat o błędzie w formacie:
base64({JSON-Body})
JSON-Body zawiera 3 wartości: status
, schemes
i scope
. Na przykład:
eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K
Po zdekodowaniu base64 wygląda to w taki sposób:
{
"status":"401",
"schemes":"bearer",
"scope":"https://mail.google.com/"
}
Protokół SASL wymaga od klientów wysyłania pustej odpowiedzi na to wyzwanie.
Wymiana protokołów IMAP
W tej sekcji wyjaśniono, jak używać SASL XOAUTH2 z serwerem IMAP Gmaila.
Pierwsza odpowiedź klienta
Aby zalogować się za pomocą mechanizmu SASL XOAUTH2, klient wywołuje polecenie AUTHENTICATE
z parametrem mechanizmu XOAUTH2
i początkową odpowiedzią klienta w sposób opisany powyżej. Na przykład:
[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...]
Co warto wiedzieć na temat wymiany protokołów IMAP:
- Polecenie IMAP
AUTHENTICATE
jest opisane w dokumencie RFC 3501. - Funkcja SASL-IR pozwala na wysłanie początkowej odpowiedzi klienta w pierwszym wierszu polecenia
AUTHENTICATE
, dzięki czemu do uwierzytelnienia wymagana jest tylko jedna wizyta w obie strony. Dokument SASL-IR jest opisany w RFC 4959. - Funkcja AUTH=XOAUTH2 deklaruje, że serwer obsługuje mechanizm SASL zdefiniowany w tym dokumencie. Aby aktywować ten mechanizm, należy podać XOAUTH2 jako pierwszy argument polecenia
AUTHENTICATE
. - Podziały wierszy w poleceniach
AUTHENTICATE
iCAPABILITY
mają charakter przejrzysty i nie występują w rzeczywistych danych poleceń. Cały argument base64 powinien być jednym ciągłym ciągiem znaków bez osadzonych spacji, tak aby całe polecenieAUTHENTICATE
składało się z 1 wiersza tekstu.
Odpowiedź na błąd
Błędy uwierzytelniania są też zwracane przy użyciu polecenia IMAP AUTHENTICATE
:
[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
Co warto wiedzieć na temat wymiany protokołów IMAP:
- Klient wysyła pustą odpowiedź („\r\n”) na wyzwanie zawierające komunikat o błędzie.
Wymiana protokołów POP
Ta sekcja wyjaśnia, jak używać SASL XOAUTH2 z serwerem POP Gmaila.
Pierwsza odpowiedź klienta
Aby zalogować się za pomocą mechanizmu SASL XOAUTH2, klient wywołuje polecenie AUTH
z parametrem mechanizmu XOAUTH2
i początkową odpowiedzią klienta w sposób opisany powyżej. Na przykład:
[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYX
JlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0
Q2cBAQ==
S: +OK Welcome.
[connection continues...]
Co warto wiedzieć na temat wymiany protokołów POP:
- Polecenie POP
AUTH
jest opisane w dokumencie RFC 1734. - Podziały wierszy w poleceniu
AUTH
mają charakter przejrzysty i nie występują w rzeczywistych danych polecenia. Cały argument base64 powinien być jednym ciągłym ciągiem znaków bez osadzonych spacji, tak aby całe polecenieAUTH
składało się z 1 wiersza tekstu.
Odpowiedź na błąd
Błędy uwierzytelniania są też zwracane za pomocą polecenia POP AUTH
:
[connection begins]
C: AUTH XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlY
XJlciB5YTI5LnZGOWRmdDRxbVRjMk52YjNSbGNrQmhkSFJoZG1semRHRXVZMj
l0Q2cBAQ==
S: + eyJzdGF0dXMiOiI0MDAiLCJzY2hlbWVzIjoiQmVhcmVyIiwic2NvcGUi
OiJodHRwczovL21haWwuZ29vZ2xlLmNvbS8ifQ==
Wymiana protokołów SMTP
Ta sekcja wyjaśnia, jak używać SASL XOAUTH2 z serwerem SMTP Gmaila.
Pierwsza odpowiedź klienta
Aby zalogować się za pomocą mechanizmu XOAUTH2, klient wywołuje polecenie AUTH
z parametrem mechanizmu XOAUTH2
i wstępną odpowiedzią klienta w postaci utworzonej powyżej. Na przykład:
[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...]
Co warto wiedzieć na temat wymiany protokołów SMTP:
- Polecenie SMTP
AUTH
jest opisane w dokumencie RFC 4954. - Podziały wierszy w poleceniu
AUTH
mają charakter przejrzysty i nie występują w rzeczywistych danych polecenia. Cały argument base64 powinien być jednym ciągłym ciągiem znaków bez osadzonych spacji, tak aby całe polecenieAUTH
składało się z 1 wiersza tekstu.
Odpowiedź na błąd
Błędy uwierzytelniania są też zwracane za pomocą polecenia SMTP AUTH
:
[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...]
Co warto wiedzieć na temat wymiany protokołów SMTP:
- Klient wysyła pustą odpowiedź („\r\n”) na wyzwanie zawierające komunikat o błędzie.
Odniesienia
- OAUTH2: dostęp do interfejsów API Google za pomocą protokołu OAuth 2.0
- SMTP: RFC 2821: Simple Mail Transfer Protocol
- IMAP: RFC 3501: PROTOCOL DOSTĘPU W wiadomościach INTERNETOWYCH – WERSJA 4rev1
- POP: RFC 1081: Protokół pocztowy – wersja 3
- SASL: RFC 4422: SASL
- JSON: RFC 4627: typ nośnika aplikacji/json dla formatu JavaScript Object Notation
- BASE64: RFC 4648: kodowanie danych Base16, Base32 i Base64
- SASL-IR: RFC 4959: Rozszerzenie IMAP dla pierwszej odpowiedzi klienta SASL (Simple Authentication and Security Layer)
- SMTP-AUTH: RFC 4954: rozszerzenie usługi SMTP na potrzeby uwierzytelniania