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. Dokument ten wyjaśnia, jak działa OAuth 2.0 i jak napisać 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 uprawnień https://mail.google.com/, przenieś ją do interfejsu API Gmaila i używaj bardziej szczegółowych zakresów ograniczonych.

Przekazywanie dostępu w całej domenie Google Workspace

Jeśli chcesz używać Google Workspace delegowania na całą domenę za pomocą kont usługi do uzyskiwania dostępu do Google Workspace pocztów użytkowników za pomocą 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 w ustawieniach Gmaila opcję „Pokaż w kliencie IMAP” dla danej etykiety.
  • 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.0. 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 dokumencie RFC 4648. ^A oznacza kombinację klawiszy Ctrl + A (\001).

Na przykład przed kodowaniem base64 początkowa 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 dekodowaniu w formacie base64 wygląda to tak (w formacie ułatwiającym odczytanie):

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

Protokół SASL wymaga, aby klienci wysyłali pustą odpowiedź na to wyzwanie.

Wymiana protokołu IMAP

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

Początkowa 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...]

Ważne informacje o protokole 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 potrzebna jest tylko 1 transmisja w obie strony. 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 w komendach 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 wyzwanie 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 zostało opisane w dokumentacji RFC 1734.
  • 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 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 taki sposób jak 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...]

Informacje o wymianie danych w protokole 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 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ą 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