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

Ссылки