OAuth 2.0 Авторизация¶

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

Получение кода авторизации¶

GET https://o2.mail.ru/login

Поля¶

Название	Значение	Описание
response_type	code	Тип получения доступа.
client_id		Уникальный идентификатор клиента.
redirect_uri		Адрес, на который сервер авторизации перенаправляет пользователя после успешной авторизации (посылает ответ). Должен в точности сопадать с тем, который был зарегистрирован (включая схему http или https, а также символ ‘/’ на правом конце). Чтобы зарегистрировать адрес, необходимо обратиться в службу поддержки.
scope	biz.api userinfo	Область действия токена. Допустимо указание нескольких scope через пробельный символ.
state	Любая строка	Сервер авторизации добавляет этот параметр с указанным значением к адресу redirect_uri, на который будет перенаправлен пользователь. Для предотвращения CSRF-атак необходимо сохранять случайное значение state в сессии или куке и проверять его при возврате на redirect_uri.

Пример¶

GET /login?client_id=test_client_id&response_type=code&scope=biz.api%20userinfo&redirect_uri=http://domain.net/&state=some_state HTTP/1.1
Host: o2.mail.ru
Content-Type: text/html

Ответ¶

Пользователь успешно прошел авторизацию

В случае успешного прохождения авторизации пользователь будет перенаправлен на адрес следующего вида:
{redirect_uri}?state={state}&code={authorization_code}
Пример
http://domain.net/?state=some_state&code=b42019a80b7d76b388b504cc4366e98425fcbd3e37363830
После нажатия на кнопку “отмена” пользователь будет перенаправлен на адрес следующего вида:
{redirect_uri}?error=access_denied&state={state}
Пример
http://domain.net/?error=access_denied&state=some_state
Поля

Название Описание

code Код авторизации, по которому может быть получен в дальнейшем токен для доступа. Время жизни кода авторизации 5 минут.

state Соответствует значению указанному в параметре state в запросе.
Ошибка при получении кода авторизации

См. Ошибки авторизации

Получение токена¶

POST https://o2.mail.ru/token

Поля¶

Название	Значение	Описание
grant_type	authorization_code	Тип получения токена.
code		Авторизационный код.
redirect_uri		Адрес, на который сервер авторизации перенаправляет пользователя после успешной авторизации. Должен совпадать с тем, который был указан при получении соответствующего кода авторизации (включая схему http или https, а также символ ‘/’ на правом конце).

Необходимо указать значения параметров client_id и client_secret в параметрах запроса или Authorization-заголовке (Базовая HTTP-авторизация).

Пример¶

curl -X POST "https://o2.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: o2.mail.ru
Authorization: Basic dGVzdF9jbGllbnRfaWQ6dGVzdF9jbGllbnRfc2VjcmV0
Content-Type: application/x-www-form-urlencoded

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

Ответ¶

Токен успешно получен

Поля

Пример
HTTP 200 OK

{
  "expires_in": 3600,
  "access_token": "6c3c7dcebeba73ba878439237b8cdc302031313737363830",
  "refresh_token": "b42019a80b7d76b388b504cc4366e98425fcbd3e37363830"
}
Ошибка при получении токена

См. Ошибки авторизации

Обновление токена¶

POST https://o2.mail.ru/token

Поля¶

Название	Значение	Описание
client_id		Уникальный идентификатор клиента.
grant_type	refresh_token	Тип получения токена доступа.
refresh_token		Токен для обновления “протухшего” токена доступа.

Пример¶

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

POST /token HTTP/1.1
Host: o2.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"
}
Ошибка при обновлении токена

См. Ошибки авторизации

При возращении ошибки token not found необходимо вновь запросить refresh_token.

Информация о пользователе по токену¶

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

Метод работает только для токенов, у которых есть scope userinfo.

Поля¶

Название	Описание
access_token	Токен для доступа.

Пример¶

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

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

Ответ¶

HTTP 200 OK

{
    "gender": "m",
    "name": "Алексей Иванов",
    "locale": "ru_RU",
    "first_name": "Алексей",
    "last_name": "Иванов"
    "email": "alex@ivanov.ru"
}

Поля¶

Название	Описание
gender	Пол. “m” - мужской, “f” - женский.
name	Имя и фамилия.
first_name	Имя.
last_name	Фамилия.
locale	Локаль.
email	Почтовый адрес.

Ошибки авторизации¶

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

Описание полей¶

Название	Описание
error	Символьный код ошибки.
error_code	Численный код ошибки.
error_description	Описание ошибки.

Описание ошибок¶

error_code	error
1	invalid client	Неверный клиент.
2	invalid request	Неверные параметры, неправильный токен и т.д.
6	token not found	Неправильный токен.

Пример¶

HTTP 200 OK

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