Mechanizm OAuth 2.0

Ten dokument definiuje mechanizm SASL XOAUTH2 do użycia z poleceniami IMAPAUTHENTICATE, POPAUTH i SMTPAUTH. Ten mechanizm umożliwia korzystanie z tokenów dostępu OAuth 2.0 do uwierzytelniania na koncie Gmail użytkownika.

Korzystanie z protokołu OAuth 2.0

Najpierw zapoznaj się z artykułem Używanie protokołu OAuth 2.0 na potrzeby dostępu do interfejsów API Google. W tym dokumencie wyjaśniono, jak działa OAuth 2.0 i jakie czynności są wymagane do napisania klienta.

Możesz też przejrzeć przykładowy kod XOAUTH2, aby zapoznać się z działającymi przykładami.

Zakresy uprawnień OAuth 2.0

Zakres dostępu IMAP, POP i SMTP to https://mail.google.com/. Jeśli żądasz dostępu do pełnego zakresu poczty w aplikacji IMAP, POP lub SMTP, musi ona być zgodna z zasadami dotyczącymi danych użytkownika usług interfejsów API Google.

  • Aby uzyskać zatwierdzenie, aplikacja musi w pełni wykorzystywać https://mail.google.com/.
  • Jeśli Twoja aplikacja nie wymaga https://mail.google.com/, przejdź na interfejs Gmail API i użyj bardziej szczegółowych zakresów z ograniczeniami.

Przekazywanie dostępu w całej domenie Google Workspace

Jeśli chcesz korzystać z Google Workspace przekazywania dostępu w całej domenie za pomocą kont usługi do uzyskiwania dostępu Google Workspace do skrzynek pocztowych użytkowników przez IMAP, możesz zamiast tego autoryzować klienta za pomocą zakresu https://www.googleapis.com/auth/gmail.imap_admin.

Po uzyskaniu uprawnień o takim zakresie połączenia IMAP zachowują się inaczej:

  • Wszystkie etykiety są wyświetlane za pomocą IMAP, nawet jeśli użytkownicy wyłączyli opcję „Pokaż w kliencie IMAP” w ustawieniach Gmaila.
  • Wszystkie wiadomości są wyświetlane za pomocą IMAP niezależnie od tego, co użytkownik ustawił w sekcji „Limity rozmiaru folderów” w ustawieniach Gmaila.

Mechanizm SASL XOAUTH2

Mechanizm XOAUTH2 umożliwia klientom wysyłanie na serwer tokenów dostępu OAuth 2. Protokół używa zakodowanych wartości pokazanych w następnych sekcjach.

Początkowa odpowiedź klienta

Początkowa odpowiedź klienta SASL XOAUTH2 ma następujący format:

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

Użyj mechanizmu kodowania base64 zdefiniowanego w RFC 4648. ^A oznacza kombinację klawiszy Ctrl + A (\001).

Na przykład przed kodowaniem base64 wstępna odpowiedź klienta może wyglądać tak:

user=someuser@example.com^Aauth=Bearer ya29.vF9dft4qmTc2Nvb3RlckBhdHRhdmlzdGEuY29tCg^A^A

Po zakodowaniu w formacie Base64 wygląda to tak (przerwy w wierszach zostały wstawione w celach przejrzystości):

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

Odpowiedź na błąd

Początkowa odpowiedź klienta, która powoduje błąd, powoduje wysłanie przez serwer wyzwania zawierającego komunikat o błędzie w takim 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 (dla przejrzystości):

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

Protokół SASL wymaga od klientów wysłania pustej odpowiedzi na to wyzwanie.

Wymiana protokołów IMAP

W tej sekcji opisaliśmy, jak używać protokołu SASL XOAUTH2 z serwerem IMAP Gmaila.

Pierwsza odpowiedź klienta

Aby zalogować się za pomocą mechanizmu SASL XOAUTH2, klient wywołuje polecenie AUTHENTICATE z parametrem mechanism o wartości XOAUTH2 oraz początkową odpowiedź klienta skonstruowaną w opisany powyżej sposób. 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...]

Istotne informacje dotyczące wymiany protokołów IMAP:

  • Polecenie IMAP AUTHENTICATE jest opisane w RFC 3501.
  • Funkcja SASL-IR umożliwia wysłanie początkowej odpowiedzi klienta w pierwszym wierszu polecenia AUTHENTICATE, dzięki czemu do uwierzytelniania wystarczy tylko jedna wymiana danych. Protokół SASL-IR jest opisany w dokumencie RFC 4959.
  • Możliwość AUTH=XOAUTH2 deklaruje, że serwer obsługuje mechanizm SASL zdefiniowany w tym dokumencie. Mechanizm ten jest aktywowany przez podanie XOAUTH2 jako pierwszego argumentu polecenia AUTHENTICATE.
  • Przecinki w poleceniach AUTHENTICATE i CAPABILITY służą tylko dla ułatwienia i nie będą widoczne w danych poleceń. Cały argument base64 powinien być ciągłym ciągiem znaków bez wbudowanych odstępów, tak aby całe polecenie AUTHENTICATE składało się z jednego wiersza tekstu.

Odpowiedź na błąd

Niepowodzenia uwierzytelniania są również zwracane za pomocą 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

Ważne informacje o protokole IMAP:

  • Klient wysyła pustą odpowiedź („\r\n”) na zadanie zawierające komunikat o błędzie.

Wymiana protokołów POP

W tej sekcji opisaliśmy, jak używać protokołu SASL XOAUTH2 z serwerem POP Gmaila.

Początkowa odpowiedź klienta

Aby zalogować się za pomocą mechanizmu SASL XOAUTH2, klient wywołuje polecenie AUTH z parametrem mechanism o wartości XOAUTH2 oraz początkową odpowiedź klienta skonstruowaną w opisany powyżej sposób. Na przykład:

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

Co warto wiedzieć o wymianie protokołów POP:

  • Polecenie POP AUTH jest opisane w RFC 1734.
  • Przecinki w komandach AUTH służą tylko do ułatwienia czytania. Nie będą one widoczne w danych rzeczywistego polecenia. Cały argument base64 powinien być ciągłym ciągiem znaków bez wbudowanych odstępów, tak aby całe polecenie AUTH składało się z jednego wiersza tekstu.

Odpowiedź na błąd

Błędy uwierzytelniania są również zwracane za pomocą polecenia POP AUTH:

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

Wymiana protokołu SMTP

Z tej sekcji dowiesz się, jak używać SASL XOAUTH2 z serwerem SMTP Gmaila.

Początkowa odpowiedź klienta

Aby zalogować się za pomocą mechanizmu OAUTH2, klient wywołuje polecenie AUTH z parametrem mechanism o wartości XOAUTH2 i początkową odpowiedź klienta skonstruowaną w powyższy sposób. 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ć o wymianie protokołów SMTP:

  • Polecenie SMTP AUTH zostało opisane w dokumencie RFC 4954.
  • Przecinki w komandach AUTH służą tylko do ułatwienia czytania. Nie będą one widoczne w danych poleceń. Cały argument base64 powinien być ciągłym ciągiem znaków bez wbudowanych odstępów, tak aby całe polecenie AUTH składało się z jednego 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...]

Informacje o wymianie danych w protokole SMTP:

  • Klient wysyła pustą odpowiedź ("\r\n") na wyzwanie zawierające komunikat o błędzie.

Pliki referencyjne