Механизм 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 .

  • Для одобрения ваше приложение должно демонстрировать полное использование 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 с IMAP-сервером Gmail.

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

Для входа в систему с использованием механизма 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") на запрос, содержащий сообщение об ошибке.

Ссылки