OAuth 2.0 Авторизация¶
Авторизация пользователя начинается с того, что происходит перенаправление
пользователя на https://o2.mail.ru/login
для получения кода авторизации.
После чего либо описание ошибки, либо авторизационный код возвращается web-серверу
приложения в строке запроса на указанный redirect_uri. После получения
авторизационного кода, приложение может обменять его на токен доступа
access_token
и токен для обновления токена для доступа refresh_token
.
В качестве приложения можно использовать следующее:
client_id
: J34ZMt9oJv3jnx4KuSf2E5RQTxKmNbR5
client_secret
: dJyVVMrC2cPftztWdXHjukt2SY97SZMT
redirect_uri
: https://localhost
Получение кода авторизации¶
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 |
Локаль. |
Почтовый адрес. |
Ошибки авторизации¶
В случае неправильного заголовка авторизации возвращается 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"
}