Что такое OAuth Mail

Важно!
С 1 июля 2025 года OAuth Mail работает только для продуктовых запросов.Если вы хотите подключить на ваш сайт или мобильное приложение кнопку входа с использованием аккаунта Mail, воспользуйтесь сервисом авторизации VK ID: создайте в нём приложение и в разделе Авторизация → Дополнительные способы входа выберите Авторизация через Mail.Преимущества такого подключения:

при интеграции единого SDK вы получаете сразу три способа авторизации — VK ID, OAuth Mail и OK;
SDK работает на протоколе OAuth 2.1 — это обеспечивает надёжную и безопасную авторизацию пользователей;
пользователи получают больше удобных и современных способов входа на ваш сайт или в мобильное приложение.

Если вы подключали OAuth-авторизацию Mail ранее, она будет работать.

OAuth Mail предоставляет возможность использовать API Mail, например для работы с почтой Mail или доступа к файлам в Облаке. Чтобы получить доступ к API Mail, выполните действия:

Создайте приложение и настройте его.
Получите код авторизации и обменяйте его на Access token.
Настройте работу с методами API Mail.

Используя API Mail, вы принимаете условия Оферты. Процесс работы с API Mail выглядит следующим образом:

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

OAuth Mail поддерживает конфигурацию OpenID Connect Discovery.

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

Получите конфигурацию OpenID.
Получите URL из поля authorization_endpoint и выполните GET-запрос.

Формат запроса

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

https://oauth.mail.ru/login?response_type=code
& client_id=<идентификатор приложения>
& [scope=<список доступов>]
& [prompt=<процесс прохождения авторизации>]
& redirect_uri=<адрес перенаправления>
& state=<произвольная строка состояния>
& code_challenge=<преобразованный code_verifier>
& code_challenge_method=<метод преобразования>

URL может динамически меняться в процессе работы системы. Для обеспечения безопасности и предотвращения CSRF-атак сохраните случайное значение state в сессии и проверьте его при возврате на redirect_uri. Иначе возможна атака по следующему сценарию: допустим, на вашем сайте можно привязывать аккаунты социальных сетей. Если злоумышленник получит код авторизации для своего аккаунта социальной сети и попросит другого человека пройти с ним авторизацию на вашем сайте, аккаунт злоумышленника будет успешно привязан и он сможет войти на сайт.

Параметр	Значение	Описание
client_id		ID созданного приложения
redirect_uri		Адрес, на который сервер авторизации перенаправляет пользователя после успешной авторизации. Должен в точности совпадать с тем адресом, который был указан в приложении, включая схему http или https и символ / в конце, например https://yourproject.ru/oauth/callback/
scope	openid email profile mail.imap	Запрашиваемые права приложения. Допустимо указание нескольких scope через пробел. Возможные значения: openid — позволяет запрашивать информацию о пользователе. Обязательный параметр, если не указать в запросе — будет ошибка 401; email — почта пользователя; profile — базовая информация о пользователе: фамилия, имя, пол, фото профиля, дата рождения; mail.imap — позволяет работать с протоколом IMAP. Для авторизации используется XOAUTH2. Это значение можно запрашивать только вместе с openid через пробел.
state	string	Длина должна быть 256 бит. Nonce, рекомендуем взять из криптостойкого генератора псевдослучайных последовательностей, например SecureRandom в Android. Сервер авторизации добавляет этот параметр с указанным значением к адресу redirect_uri, куда перенаправляется пользователь
code_challenge		Значение code_verifier, преобразованное с помощью code_challenge_method и закодированное в base64 RFC-7636 Code Challenge. code_verifier представляет собой случайно сгенерированную строку, состоящую из символов: a-z, A-Z, 0-9, _, -, длиной от 43 до 128 символов. code_challenge применяется при использовании расширения PKCE для защиты передаваемых данных. Генерируется приложением для последующей проверки, что запрос токена поступает от того же приложения, которое запросило авторизацию
code_challenge_method		Метод преобразования code_verifier в code_challenge. Принимает значение S256
prompt		Опциональный параметр. Позволяет изменить способ прохождения авторизации. Возможные значения: пустое значение или отсутствие параметра — форма входа появляется, если пользователь ещё не вошёл в Mail. Форма разрешения доступов отображается, если ранее пользователь ещё не разрешал доступ к данным; none — процесс авторизации без взаимодействия с пользователем. Чтобы такая авторизация прошла успешно, должны быть соблюдены условия: Пользователь уже вошёл в Mail. Пользователь ранее уже предоставлял сервису доступ к своим данным. Если пользователь не вошёл в Mail, то отобразится ошибка login_required. Если пользователь ещё не разрешал доступ к данным, то появится ошибка interaction_required; login — процесс всегда стартует с аутентификации пользователя, даже если он уже вошёл в Mail; consent — всегда отображается форма запроса разрешений доступов, даже если пользователь давал их ранее. По умолчанию используется пустое значение

В результате пользователь успешно проходит авторизацию или при получении кода авторизации возникает ошибка. Пользователь успешно прошел авторизацию В этом случае пользователь перенаправляется на адрес вида:

Формат ответа

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

GET https://<адрес перенаправления>?state=<произвольная строка состояния>&code=<код подтверждения>

Параметр	Описание
code	Временный код со сроком жизни 5 минут, полученный после авторизации. По этому коду в дальнейшем можно запросить токен доступа access_token
state	Соответствует значению, которое указано в параметре state запроса

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

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

Получите конфигурацию OpenID.
Получите URL из поля token_endpoint и выполните POST-запрос с сервера вашего сайта.

Формат запроса

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

curl -X POST --location "https://oauth.mail.ru/token" \ 
-H "Content-Type: application/x-www-form-urlencoded;" \ 
-d "grant_type=authorization_code&code=<код подтверждения authorization_code>&code_verifier=<параметр для защиты передаваемых данных>&redirect_uri=<адрес перенаправления>" \ 
-u "<client_id>:<client_secret>"

URL может динамически меняться в процессе работы системы.

Параметр	Значение	Описание
code		Авторизационный код
grant_type	authorization_code	Тип получения токена (только с сервера)
redirect_uri		Адрес, на который сервер авторизации перенаправляет пользователя после успешной авторизации. Должен в точности совпадать с тем адресом, который был указан в приложении, включая схему http или https и символ / в конце, например https://yourproject.ru/oauth/callback/
code_verifier		Параметр, который обеспечивает защиту передаваемых данных. Параметр применяется при PKCE. Случайно сгенерированная строка, новая на каждый запрос авторизации. Может состоять из следующих символов: a-z, A-Z, 0-9, _, -. Длина от 43 до 128 символов. На основании строки формируется code_challenge: сервер преобразует code_verifier методом code_challenge_method, полученным в запросе на отправку кода подтверждения, и сравнивает результат с code_challenge из того же запроса. Параметр обязателен для обмена кода на токен

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

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

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

// HTTP 200 OK
{
  "expires_in":3600,
  "access_token":"****",
  "refresh_token":"****"
}

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

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

Получите конфигурацию OpenID.
Получите URL из поля token_endpoint и выполните POST-запрос с сервера вашего сайта.

Формат запроса

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

curl -X POST --location "https://oauth.mail.ru/token" \ 
-H "Content-Type: application/x-www-form-urlencoded;" \ 
-d "grant_type=refresh_token&refresh_token=<refresh_token>&client_id=<идентификатор приложения>" \ 
-u "<client_id>:<client_secret>"

Параметр	Значение	Описание
client_id		ID созданного приложения
grant_type	refresh_token	Тип получения токена
refresh_token		Токен обновления, который можно использовать для получения нового токена доступа. Действителен 30 суток после последнего получения access_token. Если срок действия refresh_token истёк и вы хотите получить новый, получите новый код авторизации и новый Access token

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

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

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

// HTTP 200 OK
{
  "expires_in":3600,
  "access_token":"****",
  "refresh_token": "****"
}

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

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

Получите конфигурацию OpenID.
Получите URL из поля userinfo_endpoint и выполните POST-запрос с сервера вашего сайта.

Формат запроса

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

curl -X POST --location "https://oauth.mail.ru/api/v1/oidc/userinfo" \ 
-H "Authorization: Bearer <access_token>"

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

// HTTP 200 OK
{
  "sub": "...",
  "name": "Алексей Иванов",
  "given_name": "Алексей",
  "family_name": "Иванов",
  "nickname": "alex",
  "picture": "https://...",
  "gender": "male",
  "birthdate": "2006-01-02",
  "locale": "ru_RU",
  "email": "alex@ivanov.ru",
  "email_verified": true
}

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

Параметр	Описание
sub	Идентификатор учетной записи
name	Имя и фамилия
given_name	Имя
family_name	Фамилия
nickname	Псевдоним
picture	Аватар пользователя
gender	Пол. Возможные значения: male — мужской; female — женский.
locale	Язык и регион
email	Почтовый адрес
email_verified	Признак подтвержденной учетной записи. Возможные значения: true — учётная запись подтверждена; false — учётная запись не подтверждена.

Инспекция токена

Получите конфигурацию OpenID.
Получите URL из поля introspection_endpoint и выполните POST-запрос с сервера вашего сайта.

Формат запроса

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

curl -X POST --location "https://oauth.mail.ru/api/v1/oauth2/token/introspect" \ 
-H "Content-Type: application/x-www-form-urlencoded;" \ 
-d "token_type_hint=<тип инспектируемого токена>&token=<токен>" \ 
-u "<client_id>:<client_secret>"

Параметр	Описание
token_type_hint	Тип инспектируемого токена. Возможные значения: access_token refresh_token.
token	Инспектируемый токен

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

Параметр	Описание
active	Признак активности токена. Возможные значения: true — токен активен false — токен недействителен
scope	Список прав доступа, которые необходимы приложению. Значения в списке разделяются пробелами, например: email mail.imap . Если список не указан, то он будет взят из пришедшего Refresh token
client_id	ID созданного приложения
username	Email учетной записи
token_type	Тип токена — по умолчанию Bearer
exp	Cрок действия токена в секундах
iat	Время выдачи токена в формате Unix Timestamp
sub	Идентификатор учетной записи

Пример ответа для активного токена

// HTTP 200 OK

{
  "active": true,
  "scope": "userinfo",
  "client_id": "test_client_id",
  "username": "alex@ivanov.ru",
  "token_type": "Bearer",
  "exp": 3599,
  "iat": 1762846819,
  "sub": "..."
}

Пример ответа для недействительного токена

// HTTP 200 OK

{ "active": false }

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

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

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

{
   "error": "<ошибка с одним из значений ниже>",
   "error_description": "<описание ошибки. Передается в виде строки>",
}

Возможные значения

access_denied — у пользователя нет доступа к Mail: пользователь заблокирован или удален;
invalid_client — приложение с указанным client_id не найдено или заблокировано;
invalid_grant — Refresh token недействителен или срок его действия истёк;
invalid_request — в запросе не передан обязательный параметр, или не удалось его провалидировать;
invalid_scope — запрошенный scope недействителен, неизвестен или имеет неверный формат. Ошибка возникает, когда запрошенные права доступа не совпадают с теми, которые были указаны при при настройке приложения;
server_error — сервер авторизации столкнулся с непредвиденной ситуацией, из-за которой не получилось выполнить запрос. Этот код ошибки необходим, так как код состояния HTTP 500 Internal Server Error нельзя вернуть клиенту через перенаправление HTTP;
temporarily_unavailable — сервер авторизации в настоящее время перегружен и не может обработать запрос. Этот код ошибки необходим, так как код состояния HTTP 503 Service Unavailable нельзя вернуть клиенту через перенаправление HTTP;
unauthorized_client — клиент не имеет права обновлять токен;
unsupported_grant_type — неподдерживаемый grant_type;
unsupported_response_type — неподдерживаемый response_type;
unsupported_token_type — неподдерживаемый тип токена.

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

// HTTP 400 BadRequest

{
  "error": "invalid_request",
  "error_description": "The request is missing a required parameter,\nincludes an invalid parameter value, includes a parameter more than once, or is otherwise malformed"
}

Формат 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>