Этот документ определяет механизм 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, это должно соответствовать нашим Службам API Google: Политика пользовательских данных .
- Чтобы быть одобренным, ваше приложение должно полностью использовать
https://mail.google.com/
. - Если вашему приложению не требуется
https://mail.google.com/
, перейдите на Gmail API и используйте более детальные ограниченные области действия .
Делегирование всего домена для 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») на запрос, содержащий сообщение об ошибке.
Рекомендации
- OAUTH2: использование OAuth 2.0 для доступа к API Google
- SMTP: RFC 2821: простой протокол передачи почты.
- IMAP: RFC 3501: ПРОТОКОЛ ДОСТУПА К ИНТЕРНЕТ-СООБЩЕНИЯМ — ВЕРСИЯ 4rev1
- POP: RFC 1081: Протокол почтового отделения — версия 3
- SASL: RFC 4422: простой уровень аутентификации и безопасности (SASL).
- JSON: RFC 4627: Тип носителя application/json для обозначения объектов JavaScript.
- BASE64: RFC 4648: кодировки данных Base16, Base32 и Base64.
- SASL-IR: RFC 4959: Расширение IMAP для первоначального ответа клиента простой аутентификации и уровня безопасности (SASL).
- SMTP-AUTH: RFC 4954: Расширение службы SMTP для аутентификации.