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

Локаль.

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"
}