.. meta:: :description: OAuth-авторизация ===================== 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 в запросе. | +------------+--------------------------------------+ - Ошибка при получении кода авторизации См. :ref:`Auth_errors` Получение токена ================ :: 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/ Ответ ----- - Токен успешно получен **Поля** +---------------+-------------------------------------------------+ | Название | Описание | +===============+=================================================+ | access_token | Токен для доступа. | +---------------+-------------------------------------------------+ | refresh_token | Токен, который может быть использован для | | | получения нового access_token. Время жизни | | | токена 30 дней после последнего получения | | | access_token. | | | | | | Также токен может быть отозван пользователем | | | вручную, при смене им пароля или включении | | | двухфакторной аутентификации. | +---------------+-------------------------------------------------+ | expires_in | Оставшееся время жизни access_token в секундах. | +---------------+-------------------------------------------------+ **Пример** .. code-block:: javascript HTTP 200 OK { "expires_in": 3600, "access_token": "6c3c7dcebeba73ba878439237b8cdc302031313737363830", "refresh_token": "b42019a80b7d76b388b504cc4366e98425fcbd3e37363830" } - Ошибка при получении токена См. :ref:`Auth_errors` Обновление токена ================= :: 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 | Оставшееся время жизни токена в секундах. | +---------------+-------------------------------------------+ **Пример** .. code-block:: javascript HTTP 200 OK { "expires_in": 3600, "access_token": "4ab90dfebeb475d6aff3702120e6fa4125fcbd3e37363830" } - Ошибка при обновлении токена См. :ref:`Auth_errors` При возращении ошибки `token not found` необходимо вновь запросить ``refresh_token``. Информация о пользователе по токену =================================== :: GET https://o2.mail.ru/userinfo Метод работает только для токенов, у которых есть scope userinfo. Поля ---- +---------------+------------------------+ | Название | Описание | +===============+========================+ | access_token | Токен для доступа. | +---------------+------------------------+ Пример ------ .. code-block:: javascript curl "https://o2.mail.ru/userinfo?access_token=8e41b7a475aa7691aeead06ef0db28f989fbab0c37363830" GET /userinfo?access_token=8e41b7a475aa7691aeead06ef0db28f989fbab0c37363830 HTTP/1.1 Host: o2.mail.ru Ответ ----- .. code-block:: javascript 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 | Почтовый адрес. | +---------------+----------------------------------------+ .. _Auth_errors: Ошибки авторизации ================== В случае неправильного заголовка авторизации возвращается 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 | Неправильный токен. | +------------+------------------------------+-------------------------------------+ Пример ------ .. code-block:: javascript HTTP 200 OK { "error": "invalid request", "error_code": 2, "error_description": "Client has issued malformed or illegal request" }