Механизм OAuth 2.0

В этом документе определяется механизм SASL XOAUTH2 для использования с командами IMAP AUTHENTICATE , POP AUTH и SMTP AUTH . Этот механизм позволяет использовать токены доступа OAuth 2.0 для аутентификации в учётной записи Gmail пользователя.

Использование OAuth 2.0

Начните с изучения документа «Использование OAuth 2.0 для доступа к API Google» . В этом документе объясняется принцип работы OAuth 2.0 и шаги, необходимые для написания клиента.

Вы также можете просмотреть образец кода XOAUTH2 для просмотра рабочих примеров.

Области действия OAuth 2.0

Область доступа для протоколов IMAP, POP и SMTP — https://mail.google.com/ . Если вы запрашиваете доступ ко всем почтовым функциям для своего приложения IMAP, POP или SMTP, он должен соответствовать нашей Политике в отношении пользовательских данных Google API Services .

  • Чтобы получить одобрение, ваше приложение должно демонстрировать полное использование https://mail.google.com/ .
  • Если вашему приложению не требуется https://mail.google.com/ , перейдите на API Gmail и используйте более детальные ограниченные области действия .

Делегирование на уровне домена для Google Workspace

Если вы собираетесь использовать делегирование на уровне домена Google Workspace с использованием учетных записей служб для доступа к почтовым ящикам пользователей Google Workspace через IMAP, вы можете авторизовать своего клиента, используя область действия https://www.googleapis.com/auth/gmail.imap_admin .

При авторизации с этой областью действия IMAP-подключений ведут себя по-другому:

  • Все ярлыки отображаются через IMAP, даже если пользователи отключили функцию «Показывать в IMAP» для ярлыка в настройках Gmail.
  • Все сообщения отображаются через IMAP, независимо от того, какие параметры пользователь установил в разделе «Ограничения размера папки» в настройках Gmail.

Механизм SASL XOAUTH2

Механизм XOAUTH2 позволяет клиентам отправлять на сервер токены доступа OAuth 2.0. Протокол использует закодированные значения, показанные в следующих разделах.

Первоначальный ответ клиента

Первоначальный ответ клиента SASL XOAUTH2 имеет следующий формат:

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

Используйте механизм кодирования base64, определенный в RFC 4648. ^A представляет Control+A (\001).

Например, до кодирования base64 первоначальный ответ клиента может выглядеть так:

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

После кодирования в base64 это будет выглядеть так (разрывы строк добавлены для ясности):

dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB5YTI5LnZGOWRmdDRxbVRjMk52
YjNSbGNrQmhkSFJoZG1semRHRXVZMjl0Q2cBAQ==

Ошибка ответа

Первоначальный ответ клиента, вызывающий ошибку, приводит к тому, что сервер отправляет вызов, содержащий сообщение об ошибке в следующем формате:

base64({JSON-Body})

JSON-Body содержит три значения: status , schemes и scope . Например:

eyJzdGF0dXMiOiI0MDEiLCJzY2hlbWVzIjoiYmVhcmVyIG1hYyIsInNjb3BlIjoiaHR0cHM6Ly9t
YWlsLmdvb2dsZS5jb20vIn0K

После декодирования base64 это становится (отформатировано для ясности):

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

Протокол SASL требует от клиентов отправлять пустой ответ на этот вызов.

Обмен протоколом IMAP

В этом разделе объясняется, как использовать SASL XOAUTH2 с сервером Gmail IMAP.

Первоначальный ответ клиента

Для входа с использованием механизма SASL XOAUTH2 клиент вызывает команду AUTHENTICATE с параметром механизма XOAUTH2 и первоначальным ответом клиента, как показано выше. Например:

[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...]

Что следует отметить при обмене по протоколу IMAP:

  • Команда IMAP AUTHENTICATE описана в RFC 3501 .
  • Функция SASL-IR позволяет отправлять первоначальный ответ клиента в первой строке команды AUTHENTICATE , поэтому для аутентификации требуется только один цикл передачи данных. SASL-IR описан в RFC 4959 .
  • Возможность AUTH=XOAUTH2 объявляет, что сервер поддерживает механизм SASL, определенный в этом документе, и этот механизм активируется указанием XOAUTH2 в качестве первого аргумента команды AUTHENTICATE .
  • Переводы строк в командах AUTHENTICATE и CAPABILITY предназначены для ясности и не будут присутствовать в данных команды. Весь аргумент base64 должен быть одной непрерывной строкой без пробелов, чтобы вся команда AUTHENTICATE состояла из одной строки текста.

Ошибка ответа

Ошибки аутентификации также возвращаются с помощью команды 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

Что следует отметить при обмене по протоколу IMAP:

  • Клиент отправляет пустой ответ («\r\n») на вызов, содержащий сообщение об ошибке.

Обмен протоколом POP

В этом разделе объясняется, как использовать SASL XOAUTH2 с POP-сервером Gmail.

Первоначальный ответ клиента

Для входа с использованием механизма SASL XOAUTH2 клиент вызывает команду AUTH с параметром механизма XOAUTH2 и первоначальным ответом клиента, как показано выше. Например:

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

Что следует отметить при обмене по протоколу POP:

  • Команда POP AUTH описана в RFC 1734 .
  • Переводы строк в команде AUTH предназначены для ясности и не будут присутствовать в данных самой команды. Весь аргумент base64 должен быть одной непрерывной строкой без пробелов, чтобы вся команда AUTH состояла из одной строки текста.

Ошибка ответа

Ошибки аутентификации также возвращаются с помощью команды POP AUTH : 

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

Обмен протоколом SMTP

В этом разделе объясняется, как использовать SASL XOAUTH2 с SMTP-сервером Gmail.

Первоначальный ответ клиента

Для входа с использованием механизма XOAUTH2 клиент вызывает команду AUTH с параметром механизма XOAUTH2 и первоначальным ответом клиента, как показано выше. Например: 

[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...]

Что следует отметить при обмене по протоколу SMTP:

  • Команда SMTP AUTH описана в RFC 4954 .
  • Переводы строк в команде AUTH предназначены для ясности и не будут присутствовать в данных самой команды. Весь аргумент base64 должен быть одной непрерывной строкой без пробелов, чтобы вся команда AUTH состояла из одной строки текста.

Ошибка ответа

Ошибки аутентификации также возвращаются с помощью команды 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...]

Что следует отметить при обмене по протоколу SMTP:

  • Клиент отправляет пустой ответ («\r\n») на вызов, содержащий сообщение об ошибке.

Ссылки