Update OAuth2 documentation article

2024-11-30 02:32:29 +05:30 · 2019-02-20 23:04:44 +03:00 · 2019-02-20 23:04:44 +03:00 · e7e832a9a8
commit e7e832a9a8
parent cfea09cdf0
1 changed files with 334 additions and 193 deletions
--- a/source/oauth.rst
+++ b/source/oauth.rst
@ -1,288 +1,429 @@
-oAuth авторизация
-----------------
+Авторизация по протоколу OAuth2
+-------------------------------

-На этой странице вы найдёте информацию о подключении oAuth авторизации для вашего сайта через сервис Ely.by.
-Это такой же способ авторизации, как и вход через Вконтакте, Twitter, Google, Facebook и другие.
-Вкупе с использованием нашей системы скинов на своём сервере это позволит увеличить количество игроков на сервере и на сайте сервера.
+На этой странице вы найдёте информацию о реализации авторизации по протоколу OAuth2 на вашем проекте через сервис
+Аккаунты Ely.by. Реализация этого протокола позволяет вашим пользователям производить авторизацию с использованием
+своего аккаунта Ely.by.

-Добавление приложения
-=====================
+Регистрация приложения
+======================

-Для начала вам необходимо создать новое приложение. Вы можете это сделать на `странице добавления приложения <http://ely.by/oauth/add>`_.
-Внимательно отнеситесь к заполняемым полям - они будут влиять на внешний вид страницы авторизации.
+Для начала вам необходимо `создать новое приложение <https://account.ely.by/dev/applications/new>`_. Выберите в качестве
+типа приложения **Веб-сайт**. В качестве *адреса переадресации* можно указать только домен, но для повышения
+безопасности лучше использовать полный путь переадресации. Примеры допустимых адресов:

-.. note:: Просмотреть уже зарегистрированные приложения можно на `небольшой странице <http://ely.by/oauth>`_, посвящённой oAuth авторизации
-          на основном сайте.
+* :samp:`http://site.com`
+* :samp:`http://site.com/oauth/ely`
+* :samp:`http://site.com/oauth.php?provider=ely`

-Описание:
-~~~~~~~~~
-
-:Название: Задаёт имя приложения, отображаемое на странице авторизации и в списке ваших приложений. **Обязательное поле**.
-
-:Описание: Отображается под назаванием приложения и позволяет пользователю убедится в том, что он авторизуется именно на желаемом ресурсе.
-
-:Адрес сайта: Позволяет задать обратную ссылку на ваш сайт.
-
-:Изображение: Ссылка на логотип или нечто иное, идентифицирующее ваш проект. Это поле не обязательно, но является крайне желательным для заполнения.
-
-Параметры авторизации:
-~~~~~~~~~~~~~~~~~~~~~~
-
-:Тип ответа: Задаёт дальнейшие действия сервиса oAuth авторизации после выполнения пользователем авторизации. 
-             На данным момент поддерживается только вариант "Получить код авторизации", что является форматом ответа для авторизации на сайтах.
-
-:Перенаправление: URL адрес, на который будет переадресован пользователь с данными, согласно выбранному *типу ответа*,
-                  после авторизации. **Обязательное поле**.
-
-Разрешения:
-~~~~~~~~~~~
-
-.. note:: Поскольку API для работы с Ely.by ещё не создано, вместе с получением токена доступа (access_token) вы получите и данные о пользователе.
-
-.. list-table:: Список доступных разрешений
-   :widths: 15 85
-   :header-rows: 1
-
-   * - Разрешение
-     - Описание
-   * - E-mail адрес
-     - Регистрационный e-mail адрес пользователя, подтверждённый им при регистрации.
+После успешного добавления приложения вы попадёте на страницу со списком всех ваших приложений. Кликнув по названию
+приложения вы увидите его идентификатор ``clientId`` и секрет ``clientSecret``. Они буду использоваться на
+следующих шагах.

 Инициализация авторизации
 =========================

-После того, как вы добавите приложение, получите ссылку на инициализацию авторизации и разместите её в любом удобном месте, например так:
+Для инициализации процесса авторизации вам необходимо перенаправить пользователя по следующему URL:
+
+.. code-block:: text
+
+   https://account.ely.by/oauth2/v1?client_id=<clientId>&redirect_uri=<redirectUri>&response_type=code&scope=<scopesList>
+
+.. list-table:: Допустимые параметры запроса
+   :widths: 1 1 98
+   :header-rows: 1
+
+   * - Параметр
+     - Пример значения
+     - Описание
+   * - *clientId*
+     - :samp:`ely`
+     - **Обязательное**. ClientId, полученный при регистрации
+   * - *redirect_uri*
+     - :samp:`http://site.com/oauth.php`
+     - **Обязательное**. Адрес обратной переадресации, совпадающий с адресом, указанным при регистрации приложения
+   * - *response_type*
+     - :samp:`code`
+     - **Обязательное**. Тип ответа. На данный момент поддерживается только ``code``.
+   * - *scope*
+     - :samp:`account_info account_email`
+     - **Обязательное**. Перечень разрешений, доступ к которым вы хотите получить, разделённые пробелом. Смотрите все
+       доступные права в `разделе ниже <#available-scopes>`_.
+   * - *state*
+     - :samp:`isfvubuysdboinsbdfvit`
+     - Случайно сгенерированная строка. Используется для увеличения безопасности в качестве идентификатора сессии. Будет
+       возвращена в неизменённом виде после завершения авторизации.
+   * - *description*
+     - :samp:`यो अनुप्रयोग विवरण`
+     - Если ваше приложение доступно на нескольких языках, то используя это поле вы можете переопределить стандартное
+       описание в соответствии с предпочтительным языком пользователя.
+   * - *prompt*
+     - :samp:`consent` или :samp:`select_account`
+     - Принудительно отобразить запрос прав (``consent``) или принудительно запросить выбор аккаунта
+       (``select_account``).
+   * - *login_hint*
+     - :samp:`erickskrauch` или :samp:`erickskrauch@ely.by`
+     - Если у пользователя есть несколько аккаунтов, то указав этот в этом параметре username или email пользователя вы
+       автоматически выберете аккаунт за него. Это полезно в случае повторного входа, когда токен истёк.
+
+.. _available_scopes:
+.. list-table:: Перечень доступных scopes
+   :widths: 1 99
+   :header-rows: 0
+
+   * - **account_info**
+     - Получение информации о пользователе.
+   * - **account_email**
+     - В ответе на запрос информации о пользователе будет также присутствовать его email.
+   * - **offline_access**
+     - Вместе с ``access_token`` вы также получите и ``refresh_token``. Смотрите подробнее
+       `соответствующем разделе <#refresh-token-grant>`_.
+   * - **minecraft_server_session**
+     - ``access_token`` можно будет использовать в качестве сессии для Minecraft.
+
+------------------------------------------------------------------------------------------------------------------------
+
+Сформировав ссылку, разместите её в вашем шаблоне:

 .. code-block:: html

   <a href="<ваша_ссылка>">Войти через Ely.by</a>

-По нажатию на ссылку, `если всё в порядке </oauth.html#auth-start>`_, пользователь попадёт на нашу страницу авторизации,
-где будут представлены данные вашего приложения, указанные при его регистрации.
+По нажатию на ссылку, пользователь попадёт на нашу страницу авторизации, откуда после он будет перенаправлен обратно
+по адресу, указанному в параметре ``redirect_uri``.

-После успешного завершения процедуры авторизации, пользователь будет перенаправлен на страницу **перенаправления после авторизации** (redirect_uri).
+Обратная переадресация выполняется в виде ``<redirect_uri>?code=<код авторизации>&state=<state>`` для успешной
+авторизации и ``<redirect_uri?error=<идентификатор ошибки>&error_message=<описание ошибки>`` для неудачной.

-Если пользователь откажется от авторизации, то вы можете обработать и это, согласно `следующему разделу </oauth.html#auth-finish>`_.
+Пример успешного и неудачного редиректов:

-Данные придут в следующем формате:
+.. code-block:: text

-.. code-block:: html
+   http://site.com/oauth/ely.php?code=dkpEEVtXBdIcgdQWak4SOPEpTJIvYa8KIq5cW9GJ&state=ajckasdcjasndckbsadc
+   http://site.com/oauth/ely.php?error=access_denied&error_message=The+resource+owner+or+authorization+server+denied+the+request.

-   <redirect_uri>?code=<код_авторизации>
-   
-Например это может выглядеть так:
-
-.. code-block:: http
-
-   http://someresource.by/oauth/ely.php?code=dkpEEVtXBdIcgdQWak4SOPEpTJIvYa8KIq5cW9GJ
-
-Где:
-
-.. list-table::
-   :widths: 15 85
-   :header-rows: 0
-
-   * - redirect_uri
-     - http://someresource.by/oauth/ely.php
-   * - код_авторизации
-     - dkpEEVtXBdIcgdQWak4SOPEpTJIvYa8KIq5cW9GJ
+.. _authorization-code-grant:

 Обмен кода на ключ
 ==================

-После получения кода авторизации, вам необходимо обменять его на ключ авторизации (access_key). Для этого вам необходимо выполнить POST запрос на url:
+После получения кода авторизации (``auth_code``), вам необходимо обменять его на ключ авторизации (``access_key``).
+Для этого необходимо выполнить POST запрос на URL:

-.. code-block:: http
+.. code-block:: text

-   http://oauth.ely.by/access-token
+   https://account.ely.by/api/oauth2/v1/token

-И передать туда параметры **client_id**, **client_secret**, **redirect_uri** и **grant_type**. Значения этих параметров
-вы можете найти на странице с информацией о вашем приложении.
+И передать туда следующие параметры:

-Пример реализации запроса на PHP:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. list-table::
+   :widths: 1 99
+   :header-rows: 0
+
+   * - ``client_id``
+     - ClientID, полученный при регистрации приложения.
+   * - ``client_secret``
+     - ClientSecret, полученный при регистрации приложения.
+   * - ``redirect_uri``
+     - Точный адрес, использованный для переадресации пользователя.
+   * - ``grant_type``
+     - В данном случае указывается ``authorization_code``.
+
+**Пример реализации обмена на PHP:**

 .. code-block:: php

   <?php
-   // В этой переменной будут храниться ваши параметры oAuth
-   $oauth_params = array(
-       'client_id' => 'BdBrINDm3CMXhrb6gaAeWqquyZmP2VUS9CLDU50M', // Публичный ключ
-       'client_secret' => 'Pk4uCtZw5WVlSUpvteJuTZkVqHXZ6aNtTaLPXa7X', // Секретный ключ
-       'redirect_uri' => 'http://someresource.by/oauth/some.php', // Редирект после авторизации
-       'grant_type' => 'authorization_code' // Просто нужно по протоколу. Не меняйте это значение
-   );
+   // В этой переменной будут храниться ваши параметры OAuth2
+   $oauthParams = [
+       'client_id' => 'ely', // Ваш ClientId, полученный при регистрации
+       'client_secret' => 'Pk4uCtZw5WVlSUpvteJuTZkVqHXZ6aNtTaLPXa7X', // Ваш ClientSecret, полученный при регистрации
+       'redirect_uri' => 'http://someresource.by/oauth/some.php', // Адрес, на который вы ожидаете получить пользователя обратно (текущий url)
+       'grant_type' => 'authorization_code',
+   ];
+
+   // Если возникла ошибка, то прерываем выполнение скрипта
+   if (isset($_GET['error'])) {
+       echo $_GET['error_message'];
+       return;
+   }

   // Выполняем код ниже только если пришёл код авторизации
   if (!is_null($_GET['code'])) {
-       $oauth_params['code'] = $_GET['code'];
+       $oauthParams['code'] = $_GET['code'];

       $curl = curl_init();
-       curl_setopt($curl, CURLOPT_URL, 'http://oauth.ely.by/access-token');
+       curl_setopt($curl, CURLOPT_URL, 'https://account.ely.by/api/oauth2/v1/token');
       curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
       curl_setopt($curl, CURLOPT_POST, true);
-       curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($oauth_params));
-       $out = json_decode(curl_exec($curl));
+       curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($oauthParams));
+       $out = json_decode(curl_exec($curl), true);
       curl_close($curl);
   }

-Пояснение по коду:
+Пояснение к коду:

-* Сначала мы объявляем переменную $oauth_params, в которую заносим значения, полученные после регистрации приложения.
+* Сначала мы объявляем переменную ``$oauthParams``, в которую заносим значения, полученные после регистрации приложения.

-* Затем проверяем, пришёл ли код. Если кода нет, то, вероятно, пользователь отклонил запрошенные права. Подробнее об ошибках.
+* Затем проверяем, не возникла-ли ошибка. В этом случае сразу же прерываем выполнение.

-* Инициализируем Curl для отправки запроса на форму обмена кода на токен: http://oauth.ely.by/access-token.
+* Формируем POST запрос к форме обмена ``code`` на ``access_token``, передавая необходимые поля.

-* Запрос должен быть выполнен как POST и в него должны быть переданы 5 параметров: client_id, client_secret, redirect_uri, grant_type и code.
-  Имена полей должны быть именно такими, порядок не важен.
+* Выполняем запрос, получаем ответ, переводим его из JSON в ассоциативный массив.

-* Выполняем запрос, получаем строку ответа от Ely и сразу же декодируем JSON строку.
+.. _authorization-code-grant-response:

-------------------
+Ответ сервера
+~~~~~~~~~~~~~

-Таким образом в переменной **$out** будет находиться информация об авторизации.
+В случае успешного запроса в теле ответа будет находиться результат обмена кода авторизации на ``access_token``.
+Данные являются JSON документом и могут быть легко интерпретированы средствами используемого языка программирования.

-Ответ от сервера
-================
-
-В случае успешного запроса, в теле ответа будет находиться результат обмена кода авторизации на токен доступа.
-Данные являются простым JSON объектом и могут быть прочитаны в большинстве языков программирования без привлечения сторонних библиотек.
-
-Ознакомьтесь со списком возможных ошибкок в `следующем разделе </oauth.html#access-token>`_.
-
-------------------
-
-После парсинга JSON строки вы получите следующие данные:
+Тело JSON документа содержит следующие поля:

 .. code-block:: javascript

   {
-       "access_token": "4qlktsEiwgspKEAotazem0APA99Ee7E6jNryVBrZ", /* Токен доступа */
+       "access_token": "4qlktsEiwgspKEAotazem0APA99Ee7E6jNryVBrZ",
+       "refresh_token": "m0APA99Ee7E6jNryVBrZ4qlktsEiwgspKEAotaze", // Представлен только в случае запроса с правами offline_access
       "token_type": "Bearer",
-       "expires": 1407528497, /* Unix-timestamp истечения токена доступа */
-       "expires_in": 86400, /* Количество секунд, на которое выдан токен */
-       "user_data": {
-           "id": "1", /* Уникальный id пользователя */
-           "nickname": "ErickSkrauch", /* Текущий ник пользователя */
-           "profileUrl": "http://ely.by/erickskrauch", /* Ссылка на профиль */
-           "email": "erickskrauch@ely.by", /* Вы получите E-mail только если вы запросили право на доступ */
-           "skin": { /* Ссылки на различные изображения скина пользователя */
-               "faceUrl": "http://ely.by/minecraft/skin_buffer/faces/1c659e89546ae0cbf16965619053e31d.png",
-               "renderUrl": "http://ely.by/minecraft/skin_buffer/skins/1c659e89546ae0cbf16965619053e31d.png",
-               "skinUrl": "http://ely.by/minecraft/skins/1c659e89546ae0cbf16965619053e31d.png"
-           }
-       }
+       "expires_in": 86400 // Количество секунд, на которое выдан токен
   }

-На этом процедура авторизации закончена. Дальнейшая обработка данных зависит от потребностей вашего приложения.
-Вы можете выдать пользователю форму для довведения дополнительных данных или сразу произвести его регистрацию
-в своей системе и дальнейшую авторизацию.
+На этом процедура авторизации закончена. Полученный ``access_token`` может быть использован для получения информации о
+пользователе и взаимодействия с нашим API.
+
+Получение информации о пользователе
+===================================
+
+Если полученный токен имеет scope ``account_info``, то вы можете запросить информацию об аккаунте пользователя. Для
+этого необходимо отправить запрос на URL:
+
+.. code-block:: text
+
+   https://account.ely.by/api/account/v1/info
+
+Для передачи ``access_token`` используется заголовок ``Authorization`` со значением ``Bearer {access_token}``.
+
+**Пример реализации получения информации о пользователе на PHP:**
+
+.. code-block:: php
+
+   <?php
+   $accessToken = 'some_access_token_value';
+
+   $curl = curl_init();
+   curl_setopt($curl, CURLOPT_URL, 'https://account.ely.by/api/oauth2/v1/token');
+   curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
+   curl_setopt($curl, CURLOPT_HTTPHEADER, [
+       'Authorization: Bearer ' . $accessToken,
+   ]);
+   $result = json_decode(curl_exec($curl), true);
+   curl_close($curl);
+
+В ответ вы получите JSON документ со следующим содержимым:
+
+.. code-block:: json
+
+   {
+       "id": 1,
+       "uuid": "ffc8fdc9-5824-509e-8a57-c99b940fb996",
+       "username": "ErickSkrauch",
+       "registeredAt": 1470566470,
+       "profileLink": "http:\/\/ely.by\/u1",
+       "preferredLanguage": "be",
+       "email": "erickskrauch@ely.by"
+   }
+
+Обратите внимание, что поле ``email`` будет присутствовать лишь в том случае, когда был запрошен scope
+``account_email``.
+
+.. note:: В ходе дальнейшего развития сервиса, количество возвращаемых полей может увеличиться, но не уменьшиться или
+          измениться.
+
+.. _refresh-token-grant:
+
+Обновление токена доступа
+=========================
+
+Если при выполнении авторизации вами было запрошено право на получение scope ``offline_access``, то вместе с
+``access_token`` вы также получите и ``refresh_token``. Данный токен не истекает и может быть использован для получения
+нового токена доступа, когда он истечёт.
+
+Для выполнения операции обновления токена необходимо отправить POST запрос на тот же URL, что использовался и
+`при обмене кода на ключ доступа <#authorization-code-grant>`_, но со следующими параметрами:
+
+ ``grant_type`` со
+значением *refresh_grant*, ``client_id``, ``client_secret``, ``scope`` и непосредственно ``refresh_token``.
+
+.. list-table::
+   :widths: 1 99
+   :header-rows: 0
+
+   * - ``client_id``
+     - ClientID, полученный при регистрации приложения.
+   * - ``client_secret``
+     - ClientSecret, полученный при регистрации приложения.
+   * - ``scope``
+     - Те же scope, что были запрошены и при получении начального токена доступа. Попытка запросить большее количество
+       прав приведёт к ошибке.
+   * - ``refresh_token``
+     - Непосредственно токен, полученный вместе с начальным токеном доступа.
+
+**Пример реализации обновления токена доступа на PHP:**
+
+.. code-block:: php
+
+   <?php
+   // refresh_token, полученный при завершении авторизации
+   $refreshToken = 'm0APA99Ee7E6jNryVBrZ4qlktsEiwgspKEAotaze';
+
+   $requestParams = [
+       'client_id' => 'ely', // Ваш ClientId, полученный при регистрации
+       'client_secret' => 'Pk4uCtZw5WVlSUpvteJuTZkVqHXZ6aNtTaLPXa7X', // Ваш ClientSecret, полученный при регистрации
+       'scope' => 'account_info account_email',
+       'refresh_token' => $refreshToken,
+       'grant_type' => 'refresh_token',
+   ];
+
+   $curl = curl_init();
+   curl_setopt($curl, CURLOPT_URL, 'https://account.ely.by/api/oauth2/v1/token');
+   curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
+   curl_setopt($curl, CURLOPT_POST, true);
+   curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($requestParams));
+   $result = json_decode(curl_exec($curl), true);
+   curl_close($curl);
+
+В качестве ответа будет точно такое же тело, какое было получено в результате
+`обмена кода на ключ доступа <#authorization-code-grant-response>`_. Поле ``refresh_token`` будет отсутствовать.
+
+Готовые библиотеки
+==================
+
+Более простым способом будет использовать уже готовую библиотеку, которой будет необходимо передать лишь регистрационные
+параметры. Ниже перечислены библиотеки для различных языков программирования. Вы можете дополнить этот список своей
+библиотекой.
+
+* **PHP**:
+
+  - [Official] https://github.com/elyby/league-oauth2-provider
+
+* **Ruby**:
+
+  - [Official] https://github.com/elyby/omniauth-ely

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

-Так или инчае, но реализовать oAuth авторизацию с первого раза получается далеко не у всех. Самым важным является правильно
-понять причину и исправить её. Ниже приведены стандартные и предусмотренные сообщения, которые вы можете получить в случае
-неправильной передачи данных на сервер или нестандартных действий пользователя.
-
-Тем не менее, если вы получили ошибку, неописанную в этой документации, пожалуйста, сообщите мне о ней в
+Ниже приведены стандартные ошибки, которые вы можете получить в случае неправильной передачи данных на сервер
+авторизации. Если вы столкнулись с ошибкой, не описанной в этой документации, пожалуйста, сообщите о ней через
 `форму обратной связи <http://ely.by/site/contact>`_.

-.. _auth-start:
+.. _auth-start-errors:

 Ошибки при инициализации авторизации
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-.. _auth-start-fields:
-
-Поля
-""""
-
-Ошибка с текстом:
+Этот раздел описывает ошибки, отображаемые при переадресации пользователя с вашего сайта на нашу страницу инициализации
+авторизации.

 .. code-block:: text

-   The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "redirect_uri" parameter.
+   Invalid request ({parameter} required).

-Означает то, что вы забыли передать в параметрах то или иное значение.
-Необходимое значение указано во 2 предложении.
-Чтобы решить эту проблему вам нужно просто добавить поле и его значение в передаваемые параметры.
-
-Клиент
-""""""
-
-Если же вы встретили следующую проблему:
+Данная ошибка означает, что вы передали не все необходимые параметры. Чтобы решить эту ошибку просто добавьте
+недостающий параметр.

 .. code-block:: text

-   Client authentication failed.
+   Invalid response type '{invalid_response_type_value}'.

-Это означает, что переданные параметры не соответствуют ни одному зарегистрированному приложению.
-Проверьте ваши значения code и redirect_uri, а лучше используйте уже сгенерированную ссылку на странице информации о приложении.
+Данная ошибка означает, что вы передали неподдерживаемый тип ``response_type``. На данный момент поддерживается только
+значение ``code``.

-.. _auth-finish:
+.. code-block:: text

-Ошибки во время завершения авторизации
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   Invalid scope '{invalid_scope}'.

-После того, как пользователь пройдёт авторизацию на Ely, ему будет предоставлен список разрешений, касающихся вашего приложения.
-Если пользователь разрешит доступ, то всё пройдёт как описано в документации выше, но если же он нажмёт на кнопку "Отказать",
-то он будет перенаправлен на ваш redirect_uri, но с другими GET параметрами:
+Ошибка указывает на то, что было запрошено неизвестный ``scope``. Убедитесь, что вы запрашиваете
+`поддерживаемые права <#available-scopes>`_

-.. code-block:: http
+.. code-block:: text

-   http://someresource.by/oauth/some.php?error=access_denied&error_message=The+resource+owner+or+authorization+server+denied+the+request.
+   Can not find application you are trying to authorize.

-То есть в вашем обработчике по пути redirect_uri вам необходимо обработать состояние, когда нет параметра code, но есть error
-и вывести пользователю какое-либо сообщение о том, что пользователь не дал доступа к своим данным - вы не дадите доступа к своему сервису :_:
+Данная ошибка говорит о том, что переданные параметры не соответствуют ни одному из зарегистрированных приложений.
+Для решения проблемы исправьте ваши значения ``client_id`` и ``redirect_uri``.

-.. _access-token:
+.. _issue-token-errors:

-Ошибки во время обмена токенов
+Ошибки при обмене кода на ключ
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-Поскольку обмен кода на токен доступа происходит через отправку POST запроса, данные передаются обратно в формате JSON.
-Поэтому опознать сообщение об ошибке можно по наличию поля **error** в ответе от сервера.
+В случае возникновения ошибки вместо ожидаемого ответа с ``200`` статусом вы получите ``40x`` код и следующие 2 поля:

-В случае возникновения ошибки вы получите 2 поля:
-
-.. code-block:: javascript
+.. code-block:: json

   {
       "error": "invalid_request",
-       "error_description": "bla bla bla bla"
+       "error_description": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the \"code\" parameter."
   }

-В поле **error** находится системное описание ошибки, оно указано в скобках у разделов ниже. В поле **error_description**
-находится описание ошибки на английском языке. Содержание достаточно для самостоятельного решения проблемы, но в случае непонятности
-той или иной ошибки, внизу привидён список возможных ошибок с пояснениями на русском языке.
+В поле ``error`` находится системный идентификатор ошибки, в ``error_description`` — описание ошибки на английском
+языке.

-Поля (invalid_request)
-""""""""""""""""""""""
+**Возможные значения error:**

-Смотрите "Ошибки при инициализации авторизации - :ref:`auth-start-fields`".
+.. list-table::
+   :widths: 1 99
+   :header-rows: 0

-Неподдерживаемый Grant (unsupported_grant_type)
-"""""""""""""""""""""""""""""""""""""""""""""""
+   * - ``invalid_request``
+     - Переданы не все необходимые параметры запроса или значение ``code`` не был найден в базе выданных кодов.
+   * - ``unsupported_grant_type``
+     - Данная ошибка сигнализирует о том, что вы попытались произвести авторизацию по неизвестному для нашего OAuth2
+       сервера типу Grant.
+   * - ``invalid_client``
+     - Эта ошибка возникает в случае, когда трио значений ``client_id``, ``client_secret`` и ``redirect_uri`` не совпали
+       ни с одним из зарегистрированных приложений.

-Если вы встретили эту ошибку, то это значит, что вы попытались произвести авторизацию по неизвестному для нашего oAuth сервера типу Grant.
-На данный момент Ely поддерживает только grant **authorization_code**, поэтому использование любого другого значения привидёт к этой ошибке.
+Ошибки при запросе информации о пользователе
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-Клиент (invalid_client)
-"""""""""""""""""""""""
+Ответ со статусом ``401`` указывает на то, что заголовок ``Authorization`` не присутствует в запросе или его значение
+сформировано неверно. Тело ответа будет следующим:

-Эта ошибка возникает в случае, когда трио значений **client_id**, **client_secret** и **redirect_uri** не совпали
-ни с одним из зарегистрированных приложений. Перепроверьте ваши значения.
+.. code-block:: json

-Ошибка доступа (invalid_grant)
-""""""""""""""""""""""""""""""
+   {
+       "name": "Unauthorized",
+       "status": 401,
+       "message": "Your request was made with invalid credentials."
+   }

-Эта ошибка встречается в том случае, если переданный **code** не соответствует вашим **client_id** и **redirect_uri**.
-Возможно, вы неправильно обработали полученные данные или на нашем сервере были сброшены коды авторизации по каким-либо техническим причинам (маловероятно).
+Ответ со статусом ``403`` сигнализирует о том, что переданный в заголовке ``Authorization`` токен не содержит scope
+``account_info`` или он истёк. Получаемый ответ будет иметь следующий формат:

-Неизвестная ошибка (undefined_error)
-""""""""""""""""""""""""""""""""""""
+.. code-block:: json

-Код на сервере никогда не будет идеален и может случится так, что виноват буду я, а не вы. Если вы стабильно получаете эту ошибку,
-то, пожалуйста, сообщите мне об этом в `форму обратной связи <http://ely.by/site/contact>`_, чтобы я мог оперативно всё исправить.
+   {
+       "name": "Forbidden",
+       "status": 403,
+       "message": "You are not allowed to perform this action."
+   }
+
+Ошибки при обновлении токена доступа
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+При выполнении обновления токена доступа вам могут встретиться те же ошибки, что и при
+`обмене кода на ключ доступа <#issue-token-errors>`_, а также несколько новых:
+
+.. list-table::
+   :widths: 1 99
+   :header-rows: 0
+
+   * - ``invalid_request``
+     - Переданы не все необходимые параметры запроса или значение ``refresh_token`` не был найден в базе выданных
+       токенов.
+   * - ``invalid_scope``
+     - Были перечислены неподдерживаемые scope или запрошено больше, чем было у изначального токена.