Что такое OAuth Mail.ru

OAuth — открытый протокол, который позволяет безопасно авторизовать пользователя внешнего сервиса через Mail.ru и получить доступ к API Mail с сервера внешнего сайта или нативного приложения. OAuth-авторизация увеличивает конверсию случайных посетителей в постоянных, и ваша аудитория растет — любой пользователь Mail.ru потенциально может стать вашим клиентом. Технология основана на протоколе OAuth 2.0.

Как работает авторизация по OAuth

Чтобы подключить авторизацию OAuth Mail.ru:

Зарегистрируйтесь на Mail.ru.
Создайте приложение и настройте его.
Сконфигурируйте кнопку входа.
Вставьте готовый код кнопки на ваш сайт или в приложение.

Правила использования данных, получаемых для авторизации пользователя, смотрите в пользовательском соглашении. Если вы знакомы с технологией OAuth-авторизации и предпочитаете работать по API, процесс будет выглядеть следующим образом:

При авторизации пользователя идет его перенаправление на https://oauth.mail.ru/login для получения кода авторизации.
В строке запроса на указанный redirect_uri веб-серверу приложения возвращается авторизационный код или ошибка.
Когда авторизационный код получен, приложение может обменять его на токен доступа access_token или токен для обновления refresh_token.

Как получить код авторизации

GET https://oauth.mail.ru/login?client_id=XXXX&response_type=code&scope=userinfo&redirect_uri=http://domain.net&state=some_state Для обеспечения безопасности и предотвращения CSRF-атак сохраните случайное значение state в сессии и проверьте его при возврате на redirect_uri. Иначе возможна атака по следующему сценарию: допустим, на вашем сайте можно привязывать аккаунты социальных сетей. Если злоумышленник получит код авторизации для своего аккаунта социальной сети и попросит другого человека пройти с ним авторизацию на вашем сайте, аккаунт злоумышленника будет успешно привязан и он сможет войти на сайт с помощью кнопки входа через социальную сеть.

Параметр	Значение	Описание
client_id		ID приложения
redirect_uri		Адрес, на который сервер авторизации перенаправляет пользователя после успешной авторизации. Должен в точности совпадать с тем адресом, который был указан в приложении, включая схему http или https и символ / в конце, например https://yourproject.ru/oauth/callback/. Для приложений, которые не поддерживают стандартные HTTP-редиректы, доступны специальные схемы: urn:ietf:wg:oauth:2.0:oob и urn:ietf:wg:oauth:2.0:oob:auto. Их использование позволяет пользователю вручную скопировать авторизационный код. Про настройку кнопки входа или кнопки OneTap для входа в один клик читайте в подразделе Как сконфигурировать кнопку
scope	userinfo mail.imap	Запрашиваемые права приложения. Допустимо указание нескольких scope через пробел. Возможные значения: userinfo — позволяет запрашивать базовую информацию о пользователе mail.imap — позволяет работать с протоколом IMAP. Для авторизации используется XOAUTH2. Это значение можно запрашивать только вместе с userinfo через пробел
state	string	Длина должна быть 256 бит. Nonce, рекомендуем взять из криптостойкого генератора псевдослучайных последовательностей, например SecureRandom в Android. Сервер авторизации добавляет этот параметр с указанным значением к адресу redirect_uri, куда перенаправляется пользователь. Если redirect_uri ссылается на localhost, urn:ietf:wg:oauth:2.0:oob или urn:ietf:wg:oauth:2.0:oob:auto, например redirect_uri=http://localhost, тогда state передавать необязательно
prompt_force	«1»	Признак того, что у пользователя обязательно нужно запросить разрешение на доступ к аккаунту, даже если пользователь уже разрешил доступ этому приложению. Получив этот параметр, Mail.ru OAuth предлагает пользователю разрешить доступ приложению и выбрать аккаунт Mail.ru. Используйте параметр, например, если пользователь переключает аккаунты Mail.ru. Если параметр не передается, пользователю придется явно менять аккаунт на каком-нибудь сервисе Mail.ru или отзывать токен, выданный сайту. Параметр обрабатывается, если для него указано значение «1», иначе — игнорируется

В результате пользователь успешно проходит авторизацию или при получении кода авторизации возникает ошибка. Пользователь успешно прошел авторизацию В этом случае пользователь перенаправляется на адрес вида: {redirect_uri}?state={some_state}&code={authorization_code}

Параметр	Описание
code	Временный код со сроком жизни 5 минут, полученный после авторизации. По этому коду в дальнейшем можно запросить токен доступа access_token
state	Соответствует значению, которое указано в параметре state запроса. Если redirect_uri ссылается на localhost, urn:ietf:wg:oauth:2.0:oob или urn:ietf:wg:oauth:2.0:oob:auto, например redirect_uri=http://localhost, тогда state передавать необязательно

Ошибка при получении кода авторизации Смотрите подраздел Возможные ошибки.

Как получить Access token

Чтобы получить access_token, выполните POST-запрос с сервера вашего сайта: POST https://oauth.mail.ru/token

Параметр	Значение	Описание
code		Авторизационный код
grant_type	authorization_code	Тип получения токена (только с сервера)
redirect_uri		Адрес, на который сервер авторизации перенаправляет пользователя после успешной авторизации. Должен в точности совпадать с тем адресом, который был указан в приложении, включая схему http или https и символ / в конце, например https://yourproject.ru/oauth/callback/. Для приложений, которые не поддерживают стандартные HTTP-редиректы, доступны специальные схемы: urn:ietf:wg:oauth:2.0:oob и urn:ietf:wg:oauth:2.0:oob:auto. Их использование позволяет пользователю вручную скопировать авторизационный код

При этом необходима базовая HTTP-авторизация клиента — client_id и client_secret можно передавать в параметрах запроса вместо basic auth. Пример запроса

curl -X POST "https://oauth.mail.ru/token" -d "grant_type=authorization_code&code=
b42019a80b7d76b388b504cc4366e98425fcbd3e37363830&redirect_uri=
http://domain.net/" -u test_client_id:test_client_secret


POST /token HTTP/1.1
Host: oauth.mail.ru
Authorization: Basic dGVzdF9jbGllbnRfaWQ6dGVzdF9jbGllbnRfc2VjcmV0
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=b42019a80b7d76b388b504cc4366e98425fcbd3e37363830&redirect_uri=
http://domain.net/

В ответе от сервера приходит json, который содержит запрошенный access_token или информацию об ошибке. Токен успешно получен

Параметр	Описание
access_token	Токен доступа
refresh_token	Токен обновления, который можно использовать для получения нового токена доступа. Действителен 30 суток после последнего получения access_token
expires_in	Время действия токена доступа в секундах

Пример ответа

// HTTP 200 OK
{
	"expires_in":3600,
	"access_token":"6c3c7dcebeba73ba878439237b8cdc302031313737363830",
	"refresh_token":"b42019a80b7d76b388b504cc4366e98425fcbd3e37363830"
}

Ошибка при получении токена Смотрите подраздел Возможные ошибки.

Как обновить токен

Чтобы обновить токен, выполните POST-запрос: POST https://oauth.mail.ru/token

Параметр	Значение	Описание
client_id		ID приложения
grant_type	refresh_token	Тип получения токена
refresh_token		Токен для обновления просроченного токена доступа

Пример запроса

curl -X POST "https://oauth.mail.ru/token" -d "client_id=test_client_id&grant_type=refresh_token&refresh_token=
b42019a80b7d76b388b504cc4366e98425fcbd3e37363830"

POST /token HTTP/1.1
Host: oauth.mail.ru
Content-Type: application/x-www-form-urlencoded

client_id=test_client_id&grant_type=refresh_token&refresh_token=
b42019a80b7d76b388b504cc4366e98425fcbd3e37363830

В результате токен обновится или придет информация об ошибке. Токен успешно обновлен

Параметр	Описание
access_token	Токен доступа
expires_in	Время действия токена доступа в секундах

Пример ответа

// HTTP 200 OK
{
	"expires_in":3600,
	"access_token":"4ab90dfebeb475d6aff3702120e6fa4125fcbd3e37363830"
}

Ошибка при обновлении токена Смотрите подраздел Возможные ошибки.

Как получить информацию о пользователе по токену

GET https://oauth.mail.ru/userinfo

Параметр	Описание
access_token	Токен доступа

Пример запроса

curl "https://oauth.mail.ru/userinfo?access_token=8e41b7a475aa7691aeead06ef0db28f989fbab0c37363830"

	GET /userinfo?access_token=8e41b7a475aa7691aeead06ef0db28f989fbab0c37363830 HTTP/1.1
	Host: oauth.mail.ru

Пример ответа

// HTTP 200 OK
{
	"id": "...",
	"client_id": "...",
	"gender": "m",
	"name": "Алексей Иванов",
	"nickname": "alex",
	"locale": "ru_RU",
	"first_name": "Алексей",
	"last_name": "Иванов",
	"email": "alex@ivanov.ru",
	"image": "https://...."
}

Описание параметров ответа

Параметр	Описание
id	ID пользователя
client_id	ClientID приложенния
gender	Пол: m - мужской, f - женский
name	Имя и фамилия
nickname	Псевдоним
first_name	Имя
last_name	Фамилия
locale	Язык и регион
email	Почтовый адрес
birthday	Дата рождения
image	Аватар пользователя

Возможные ошибки

Если используется неправильный заголовок авторизации, то возвращается HTTP-статус 401, в остальных случаях — 200 или 500. Ответ имеет JSON-формат.

Ошибка	Код	Описание
invalid client	1	Не удалось найти указанное приложение
invalid request	2	Неверные параметры, некорректный токен и т.д.
invalid username or password	3	Неправильное имя пользователя или пароль. Возвращается только c grant_type=password
token not found	6	Токен не найден

Пример ошибки

// HTTP 200 OK
{
	"error":"invalid request",
	"error_code":2,
	"error_description":"Client has issued malformed or illegal request"
}

Формат XOAUTH2

Авторизация по oauth2 на imap.mail.ru

Для авторизации XOAUTH2 «запакуйте» токен:

$ perl -Mstrict -MMIME::Base64 -e 'print encode_base64("user=<email>\001auth=Bearer 0d5c0dfabf227a018483be5424febfe07957295437363a30\001\001");'
	dXNlcj1hbHRkZXZAbWFpbC5ydQFhdXRoPUJlYXJlciAwZDVjMGRmYWJmMmY3YTAxODQ4M2JlNTQyNGZlYmZlMDc5NTcyOTE0MzczNjM4MzAB

Из полученной строки Base64 уберите \n и используйте ее для авторизации по IMAP-протоколу:

. capability
	* CAPABILITY IMAP4rev1 ID XLIST UIDPLUS UNSELECT MOVE AUTH=PLAIN AUTH=XOAUTH2
	. OK CAPABILITY completed
	. authenticate xoauth2 dXNlcj1hbHRkZXZAbWFpbC5ydQFhdXRoPUJlYXJlciAwZDVjMGRmYWJmMmY3YTAxODQ4M2JlNTQyNGZlYmZlMDc5NTcyOTE0MzczNjM4MzAB
	* CAPABILITY IMAP4rev1 ID XLIST UIDPLUS UNSELECT MOVE
	. OK Authentication successful

В ответе могут прийти:

в CAPABILITY строка "AUTH=XOAUTH2" — это означает, что можно авторизоваться по токену. Тогда для авторизации используйте "authenticate xoauth2"
данные о внутренней ошибке, если сервер не смог разобрать формат пакета:

. authenticate xoauth2 YmxhaGJsYWhibGFo
	. NO Internal error

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

. authenticate xoauth2 dXNlcj10ZXN0QG1haWwucnUBYXV0aD1CZWFyZXIgNTkwNjljZGVjNTI5N2VmODg1YmMyODIwNWJjOTQwNmI3OTU3MjkxNDM3MzYzODMxAQ==
	. NO [AUTHENTICATIONFAILED] Authentication failed

Авторизация по oauth2 на smtp.mail.ru

Для авторизации XOAUTH2 «запакуйте» токен:

$ perl -Mstrict -MMIME::Base64 -e 'print encode_base64("user=<email>\001auth=Bearer 0d5c0dfabf227a018483be5424febfe07957295437363a30\001\001");'
	dXNlcj1hbHRkZXZAbWFpbC5ydQFhdXRoPUJlYXJlciAwZDVjMGRmYWJmMmY3YTAxODQ4M2JlNTQyNGZlYmZlMDc5NTcyOTE0MzczNjM4MzAB

Из полученной строки Base64 уберите \n и используйте ее для авторизации по SMTP-протоколу:

$ openssl s_client -connect smtp.mail.ru:465
	...
	220 smtp53.i.mail.ru ESMTP ready
	C: EHLO client.example.com
	S: 250-smtp53.i.mail.ru
	S: 250-SIZE 73400320
	S: 250-8BITMIME
	S: 250-PIPELINING
	S: 250 AUTH PLAIN LOGIN XOAUTH2
	C: AUTH XOAUTH2 dXNlcj1hbHRkZXZAbWFpbC5ydQFhdXRoPUJlYXJlciAwZDVjMGRmYWJmMmY3YTAxODQ4M2JlNTQyNGZlYmZlMDc5NTcyOTE0MzczNjM4MzAB
	S: 235 Authentication succeeded

В ответе могут прийти:

в EHLO строка "AUTH XOAUTH2" — это означает, что можно авторизоваться по токену. Тогда для авторизации используйте "AUTH XOAUTH2"
данные о внутренней ошибке, если сервер не смог разобрать формат пакета:

C: AUTH XOAUTH2 dXNlc
	S: 501 Invalid base64 data
	или
	S: 500 5.5.1 Invalid command

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

C: AUTH XOAUTH2 dXNlcj08ZW1haWw+XDAwMWF1dGg9QmVhcmVyIDxhY2Nlc3NfdG9rZW4+XDAwMVww111111111111MDE=
	S: 535 Incorrect authentication data: auth failed for <email>

О подключении SDK для разных платформ читайте в статьях Авторизация для Web, Авторизация для iOS, Авторизация для Android.