mirror of
https://github.com/elyby/docs.git
synced 2024-11-26 16:52:04 +05:30
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.
|
На этой странице вы найдёте информацию о реализации авторизации по протоколу OAuth2 на вашем проекте через сервис
|
||||||
Это такой же способ авторизации, как и вход через Вконтакте, Twitter, Google, Facebook и другие.
|
Аккаунты 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`
|
||||||
|
|
||||||
Описание:
|
После успешного добавления приложения вы попадёте на страницу со списком всех ваших приложений. Кликнув по названию
|
||||||
~~~~~~~~~
|
приложения вы увидите его идентификатор ``clientId`` и секрет ``clientSecret``. Они буду использоваться на
|
||||||
|
следующих шагах.
|
||||||
:Название: Задаёт имя приложения, отображаемое на странице авторизации и в списке ваших приложений. **Обязательное поле**.
|
|
||||||
|
|
||||||
:Описание: Отображается под назаванием приложения и позволяет пользователю убедится в том, что он авторизуется именно на желаемом ресурсе.
|
|
||||||
|
|
||||||
:Адрес сайта: Позволяет задать обратную ссылку на ваш сайт.
|
|
||||||
|
|
||||||
:Изображение: Ссылка на логотип или нечто иное, идентифицирующее ваш проект. Это поле не обязательно, но является крайне желательным для заполнения.
|
|
||||||
|
|
||||||
Параметры авторизации:
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
:Тип ответа: Задаёт дальнейшие действия сервиса oAuth авторизации после выполнения пользователем авторизации.
|
|
||||||
На данным момент поддерживается только вариант "Получить код авторизации", что является форматом ответа для авторизации на сайтах.
|
|
||||||
|
|
||||||
:Перенаправление: URL адрес, на который будет переадресован пользователь с данными, согласно выбранному *типу ответа*,
|
|
||||||
после авторизации. **Обязательное поле**.
|
|
||||||
|
|
||||||
Разрешения:
|
|
||||||
~~~~~~~~~~~
|
|
||||||
|
|
||||||
.. note:: Поскольку API для работы с Ely.by ещё не создано, вместе с получением токена доступа (access_token) вы получите и данные о пользователе.
|
|
||||||
|
|
||||||
.. list-table:: Список доступных разрешений
|
|
||||||
:widths: 15 85
|
|
||||||
:header-rows: 1
|
|
||||||
|
|
||||||
* - Разрешение
|
|
||||||
- Описание
|
|
||||||
* - E-mail адрес
|
|
||||||
- Регистрационный e-mail адрес пользователя, подтверждённый им при регистрации.
|
|
||||||
|
|
||||||
Инициализация авторизации
|
Инициализация авторизации
|
||||||
=========================
|
=========================
|
||||||
|
|
||||||
После того, как вы добавите приложение, получите ссылку на инициализацию авторизации и разместите её в любом удобном месте, например так:
|
Для инициализации процесса авторизации вам необходимо перенаправить пользователя по следующему URL:
|
||||||
|
|
||||||
.. code-block:: html
|
.. code-block:: text
|
||||||
|
|
||||||
<a href="<ваша_ссылка>">Войти через Ely.by</a>
|
|
||||||
|
|
||||||
По нажатию на ссылку, `если всё в порядке </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 пользователя вы
|
||||||
|
автоматически выберете аккаунт за него. Это полезно в случае повторного входа, когда токен истёк.
|
||||||
|
|
||||||
Данные придут в следующем формате:
|
.. _available_scopes:
|
||||||
|
.. list-table:: Перечень доступных scopes
|
||||||
.. code-block:: html
|
:widths: 1 99
|
||||||
|
|
||||||
<redirect_uri>?code=<код_авторизации>
|
|
||||||
|
|
||||||
Например это может выглядеть так:
|
|
||||||
|
|
||||||
.. code-block:: http
|
|
||||||
|
|
||||||
http://someresource.by/oauth/ely.php?code=dkpEEVtXBdIcgdQWak4SOPEpTJIvYa8KIq5cW9GJ
|
|
||||||
|
|
||||||
Где:
|
|
||||||
|
|
||||||
.. list-table::
|
|
||||||
:widths: 15 85
|
|
||||||
:header-rows: 0
|
:header-rows: 0
|
||||||
|
|
||||||
* - redirect_uri
|
* - **account_info**
|
||||||
- http://someresource.by/oauth/ely.php
|
- Получение информации о пользователе.
|
||||||
* - код_авторизации
|
* - **account_email**
|
||||||
- dkpEEVtXBdIcgdQWak4SOPEpTJIvYa8KIq5cW9GJ
|
- В ответе на запрос информации о пользователе будет также присутствовать его 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
|
.. code-block:: php
|
||||||
|
|
||||||
<?php
|
<?php
|
||||||
// В этой переменной будут храниться ваши параметры oAuth
|
// В этой переменной будут храниться ваши параметры OAuth2
|
||||||
$oauth_params = array(
|
$oauthParams = [
|
||||||
'client_id' => 'BdBrINDm3CMXhrb6gaAeWqquyZmP2VUS9CLDU50M', // Публичный ключ
|
'client_id' => 'ely', // Ваш ClientId, полученный при регистрации
|
||||||
'client_secret' => 'Pk4uCtZw5WVlSUpvteJuTZkVqHXZ6aNtTaLPXa7X', // Секретный ключ
|
'client_secret' => 'Pk4uCtZw5WVlSUpvteJuTZkVqHXZ6aNtTaLPXa7X', // Ваш ClientSecret, полученный при регистрации
|
||||||
'redirect_uri' => 'http://someresource.by/oauth/some.php', // Редирект после авторизации
|
'redirect_uri' => 'http://someresource.by/oauth/some.php', // Адрес, на который вы ожидаете получить пользователя обратно (текущий url)
|
||||||
'grant_type' => 'authorization_code' // Просто нужно по протоколу. Не меняйте это значение
|
'grant_type' => 'authorization_code',
|
||||||
);
|
];
|
||||||
|
|
||||||
|
// Если возникла ошибка, то прерываем выполнение скрипта
|
||||||
|
if (isset($_GET['error'])) {
|
||||||
|
echo $_GET['error_message'];
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
// Выполняем код ниже только если пришёл код авторизации
|
// Выполняем код ниже только если пришёл код авторизации
|
||||||
if (!is_null($_GET['code'])) {
|
if (!is_null($_GET['code'])) {
|
||||||
$oauth_params['code'] = $_GET['code'];
|
$oauthParams['code'] = $_GET['code'];
|
||||||
|
|
||||||
$curl = curl_init();
|
$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_RETURNTRANSFER, true);
|
||||||
curl_setopt($curl, CURLOPT_POST, true);
|
curl_setopt($curl, CURLOPT_POST, true);
|
||||||
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($oauth_params));
|
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($oauthParams));
|
||||||
$out = json_decode(curl_exec($curl));
|
$out = json_decode(curl_exec($curl), true);
|
||||||
curl_close($curl);
|
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 документа содержит следующие поля:
|
||||||
================
|
|
||||||
|
|
||||||
В случае успешного запроса, в теле ответа будет находиться результат обмена кода авторизации на токен доступа.
|
|
||||||
Данные являются простым JSON объектом и могут быть прочитаны в большинстве языков программирования без привлечения сторонних библиотек.
|
|
||||||
|
|
||||||
Ознакомьтесь со списком возможных ошибкок в `следующем разделе </oauth.html#access-token>`_.
|
|
||||||
|
|
||||||
-------------------
|
|
||||||
|
|
||||||
После парсинга JSON строки вы получите следующие данные:
|
|
||||||
|
|
||||||
.. code-block:: javascript
|
.. code-block:: javascript
|
||||||
|
|
||||||
{
|
{
|
||||||
"access_token": "4qlktsEiwgspKEAotazem0APA99Ee7E6jNryVBrZ", /* Токен доступа */
|
"access_token": "4qlktsEiwgspKEAotazem0APA99Ee7E6jNryVBrZ",
|
||||||
|
"refresh_token": "m0APA99Ee7E6jNryVBrZ4qlktsEiwgspKEAotaze", // Представлен только в случае запроса с правами offline_access
|
||||||
"token_type": "Bearer",
|
"token_type": "Bearer",
|
||||||
"expires": 1407528497, /* Unix-timestamp истечения токена доступа */
|
"expires_in": 86400 // Количество секунд, на которое выдан токен
|
||||||
"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"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|
||||||
На этом процедура авторизации закончена. Дальнейшая обработка данных зависит от потребностей вашего приложения.
|
На этом процедура авторизации закончена. Полученный ``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>`_.
|
`форму обратной связи <http://ely.by/site/contact>`_.
|
||||||
|
|
||||||
.. _auth-start:
|
.. _auth-start-errors:
|
||||||
|
|
||||||
Ошибки при инициализации авторизации
|
Ошибки при инициализации авторизации
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
.. _auth-start-fields:
|
Этот раздел описывает ошибки, отображаемые при переадресации пользователя с вашего сайта на нашу страницу инициализации
|
||||||
|
авторизации.
|
||||||
Поля
|
|
||||||
""""
|
|
||||||
|
|
||||||
Ошибка с текстом:
|
|
||||||
|
|
||||||
.. code-block:: text
|
.. 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
|
.. code-block:: text
|
||||||
|
|
||||||
Client authentication failed.
|
Invalid response type '{invalid_response_type_value}'.
|
||||||
|
|
||||||
Это означает, что переданные параметры не соответствуют ни одному зарегистрированному приложению.
|
Данная ошибка означает, что вы передали неподдерживаемый тип ``response_type``. На данный момент поддерживается только
|
||||||
Проверьте ваши значения code и redirect_uri, а лучше используйте уже сгенерированную ссылку на странице информации о приложении.
|
значение ``code``.
|
||||||
|
|
||||||
.. _auth-finish:
|
.. code-block:: text
|
||||||
|
|
||||||
Ошибки во время завершения авторизации
|
Invalid scope '{invalid_scope}'.
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
После того, как пользователь пройдёт авторизацию на Ely, ему будет предоставлен список разрешений, касающихся вашего приложения.
|
Ошибка указывает на то, что было запрошено неизвестный ``scope``. Убедитесь, что вы запрашиваете
|
||||||
Если пользователь разрешит доступ, то всё пройдёт как описано в документации выше, но если же он нажмёт на кнопку "Отказать",
|
`поддерживаемые права <#available-scopes>`_
|
||||||
то он будет перенаправлен на ваш redirect_uri, но с другими GET параметрами:
|
|
||||||
|
|
||||||
.. 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.
|
В случае возникновения ошибки вместо ожидаемого ответа с ``200`` статусом вы получите ``40x`` код и следующие 2 поля:
|
||||||
Поэтому опознать сообщение об ошибке можно по наличию поля **error** в ответе от сервера.
|
|
||||||
|
|
||||||
В случае возникновения ошибки вы получите 2 поля:
|
.. code-block:: json
|
||||||
|
|
||||||
.. code-block:: javascript
|
|
||||||
|
|
||||||
{
|
{
|
||||||
"error": "invalid_request",
|
"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
Block a user