mirror of https://github.com/elyby/docs.git
Update OAuth2 documentation article
This commit is contained in:
ErickSkrauch
parent
cfea09cdf0
commit
e7e832a9a8
527
source/oauth.rst
527
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:: html
|
||||
|
||||
<a href="<ваша_ссылка>">Войти через Ely.by</a>
|
||||
.. code-block:: text
|
||||
|
||||
По нажатию на ссылку, `если всё в порядке </oauth.html#auth-start>`_, пользователь попадёт на нашу страницу авторизации,
|
||||
где будут представлены данные вашего приложения, указанные при его регистрации.
|
||||
https://account.ely.by/oauth2/v1?client_id=<clientId>&redirect_uri=<redirectUri>&response_type=code&scope=<scopesList>
|
||||
|
||||
После успешного завершения процедуры авторизации, пользователь будет перенаправлен на страницу **перенаправления после авторизации** (redirect_uri).
|
||||
.. list-table:: Допустимые параметры запроса
|
||||
:widths: 1 1 98
|
||||
:header-rows: 1
|
||||
|
||||
Если пользователь откажется от авторизации, то вы можете обработать и это, согласно `следующему разделу </oauth.html#auth-finish>`_.
|
||||
* - Параметр
|
||||
- Пример значения
|
||||
- Описание
|
||||
* - *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 пользователя вы
|
||||
автоматически выберете аккаунт за него. Это полезно в случае повторного входа, когда токен истёк.
|
||||
|
||||
Данные придут в следующем формате:
|
||||
|
||||
.. code-block:: html
|
||||
|
||||
<redirect_uri>?code=<код_авторизации>
|
||||
|
||||
Например это может выглядеть так:
|
||||
|
||||
.. code-block:: http
|
||||
|
||||
http://someresource.by/oauth/ely.php?code=dkpEEVtXBdIcgdQWak4SOPEpTJIvYa8KIq5cW9GJ
|
||||
|
||||
Где:
|
||||
|
||||
.. list-table::
|
||||
:widths: 15 85
|
||||
.. _available_scopes:
|
||||
.. list-table:: Перечень доступных scopes
|
||||
:widths: 1 99
|
||||
:header-rows: 0
|
||||
|
||||
* - redirect_uri
|
||||
- http://someresource.by/oauth/ely.php
|
||||
* - код_авторизации
|
||||
- dkpEEVtXBdIcgdQWak4SOPEpTJIvYa8KIq5cW9GJ
|
||||
* - **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>
|
||||
|
||||
По нажатию на ссылку, пользователь попадёт на нашу страницу авторизации, откуда после он будет перенаправлен обратно
|
||||
по адресу, указанному в параметре ``redirect_uri``.
|
||||
|
||||
Обратная переадресация выполняется в виде ``<redirect_uri>?code=<код авторизации>&state=<state>`` для успешной
|
||||
авторизации и ``<redirect_uri?error=<идентификатор ошибки>&error_message=<описание ошибки>`` для неудачной.
|
||||
|
||||
Пример успешного и неудачного редиректов:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
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.
|
||||
|
||||
.. _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 или запрошено больше, чем было у изначального токена.
|
||||
|
|
|
|||
Loading…
Reference in New Issue