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

Ссылки