mirror of
https://github.com/elyby/docs.git
synced 2024-12-26 15:00:37 +05:30
289 lines
18 KiB
ReStructuredText
289 lines
18 KiB
ReStructuredText
oAuth авторизация
|
||
-----------------
|
||
|
||
На этой странице вы найдёте информацию о подключении oAuth авторизации для вашего сайта через сервис Ely.by.
|
||
Это такой же способ авторизации, как и вход через Вконтакте, Twitter, Google, Facebook и другие.
|
||
Вкупе с использованием нашей системы скинов на своём сервере это позволит увеличить количество игроков на сервере и на сайте сервера.
|
||
|
||
Добавление приложения
|
||
=====================
|
||
|
||
Для начала вам необходимо создать новое приложение. Вы можете это сделать на `странице добавления приложения <http://ely.by/oauth/add>`_.
|
||
Внимательно отнеситесь к заполняемым полям - они будут влиять на внешний вид страницы авторизации.
|
||
|
||
.. note:: Просмотреть уже зарегистрированные приложения можно на `небольшой странице <http://ely.by/oauth>`_, посвящённой oAuth авторизации
|
||
на основном сайте.
|
||
|
||
Описание:
|
||
~~~~~~~~~
|
||
|
||
:Название: Задаёт имя приложения, отображаемое на странице авторизации и в списке ваших приложений. **Обязательное поле**.
|
||
|
||
:Описание: Отображается под назаванием приложения и позволяет пользователю убедится в том, что он авторизуется именно на желаемом ресурсе.
|
||
|
||
:Адрес сайта: Позволяет задать обратную ссылку на ваш сайт.
|
||
|
||
:Изображение: Ссылка на логотип или нечто иное, идентифицирующее ваш проект. Это поле не обязательно, но является крайне желательным для заполнения.
|
||
|
||
Параметры авторизации:
|
||
~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
:Тип ответа: Задаёт дальнейшие действия сервиса oAuth авторизации после выполнения пользователем авторизации.
|
||
На данным момент поддерживается только вариант "Получить код авторизации", что является форматом ответа для авторизации на сайтах.
|
||
|
||
:Перенаправление: URL адрес, на который будет переадресован пользователь с данными, согласно выбранному *типу ответа*,
|
||
после авторизации. **Обязательное поле**.
|
||
|
||
Разрешения:
|
||
~~~~~~~~~~~
|
||
|
||
.. note:: Поскольку API для работы с Ely.by ещё не создано, вместе с получением токена доступа (access_token) вы получите и данные о пользователе.
|
||
|
||
.. list-table:: Список доступных разрешений
|
||
:widths: 15 85
|
||
:header-rows: 1
|
||
|
||
* - Разрешение
|
||
- Описание
|
||
* - E-mail адрес
|
||
- Регистрационный e-mail адрес пользователя, подтверждённый им при регистрации.
|
||
|
||
Инициализация авторизации
|
||
=========================
|
||
|
||
После того, как вы добавите приложение, получите ссылку на инициализацию авторизации и разместите её в любом удобном месте, например так:
|
||
|
||
.. code-block:: html
|
||
|
||
<a href="<ваша_ссылка>">Войти через Ely.by</a>
|
||
|
||
По нажатию на ссылку, `если всё в порядке </oauth.html#auth-start>`_, пользователь попадёт на нашу страницу авторизации,
|
||
где будут представлены данные вашего приложения, указанные при его регистрации.
|
||
|
||
После успешного завершения процедуры авторизации, пользователь будет перенаправлен на страницу **перенаправления после авторизации** (redirect_uri).
|
||
|
||
Если пользователь откажется от авторизации, то вы можете обработать и это, согласно `следующему разделу </oauth.html#auth-finish>`_.
|
||
|
||
Данные придут в следующем формате:
|
||
|
||
.. code-block:: html
|
||
|
||
<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
|
||
|
||
Обмен кода на ключ
|
||
==================
|
||
|
||
После получения кода авторизации, вам необходимо обменять его на ключ авторизации (access_key). Для этого вам необходимо выполнить POST запрос на url:
|
||
|
||
.. code-block:: http
|
||
|
||
http://oauth.ely.by/access-token
|
||
|
||
И передать туда параметры **client_id**, **client_secret**, **redirect_uri** и **grant_type**. Значения этих параметров
|
||
вы можете найти на странице с информацией о вашем приложении.
|
||
|
||
Пример реализации запроса на 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' // Просто нужно по протоколу. Не меняйте это значение
|
||
);
|
||
|
||
// Выполняем код ниже только если пришёл код авторизации
|
||
if (!is_null($_GET['code'])) {
|
||
$oauth_params['code'] = $_GET['code'];
|
||
|
||
$curl = curl_init();
|
||
curl_setopt($curl, CURLOPT_URL, 'http://oauth.ely.by/access-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_close($curl);
|
||
}
|
||
|
||
Пояснение по коду:
|
||
|
||
* Сначала мы объявляем переменную $oauth_params, в которую заносим значения, полученные после регистрации приложения.
|
||
|
||
* Затем проверяем, пришёл ли код. Если кода нет, то, вероятно, пользователь отклонил запрошенные права. Подробнее об ошибках.
|
||
|
||
* Инициализируем Curl для отправки запроса на форму обмена кода на токен: http://oauth.ely.by/access-token.
|
||
|
||
* Запрос должен быть выполнен как POST и в него должны быть переданы 5 параметров: client_id, client_secret, redirect_uri, grant_type и code.
|
||
Имена полей должны быть именно такими, порядок не важен.
|
||
|
||
* Выполняем запрос, получаем строку ответа от Ely и сразу же декодируем JSON строку.
|
||
|
||
-------------------
|
||
|
||
Таким образом в переменной **$out** будет находиться информация об авторизации.
|
||
|
||
Ответ от сервера
|
||
================
|
||
|
||
В случае успешного запроса, в теле ответа будет находиться результат обмена кода авторизации на токен доступа.
|
||
Данные являются простым JSON объектом и могут быть прочитаны в большинстве языков программирования без привлечения сторонних библиотек.
|
||
|
||
Ознакомьтесь со списком возможных ошибкок в `следующем разделе </oauth.html#access-token>`_.
|
||
|
||
-------------------
|
||
|
||
После парсинга JSON строки вы получите следующие данные:
|
||
|
||
.. code-block:: javascript
|
||
|
||
{
|
||
"access_token": "4qlktsEiwgspKEAotazem0APA99Ee7E6jNryVBrZ", /* Токен доступа */
|
||
"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"
|
||
}
|
||
}
|
||
}
|
||
|
||
На этом процедура авторизации закончена. Дальнейшая обработка данных зависит от потребностей вашего приложения.
|
||
Вы можете выдать пользователю форму для довведения дополнительных данных или сразу произвести его регистрацию
|
||
в своей системе и дальнейшую авторизацию.
|
||
|
||
Возможные ошибки
|
||
================
|
||
|
||
Так или инчае, но реализовать oAuth авторизацию с первого раза получается далеко не у всех. Самым важным является правильно
|
||
понять причину и исправить её. Ниже приведены стандартные и предусмотренные сообщения, которые вы можете получить в случае
|
||
неправильной передачи данных на сервер или нестандартных действий пользователя.
|
||
|
||
Тем не менее, если вы получили ошибку, неописанную в этой документации, пожалуйста, сообщите мне о ней в
|
||
`форму обратной связи <http://ely.by/site/contact>`_.
|
||
|
||
.. _auth-start:
|
||
|
||
Ошибки при инициализации авторизации
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
.. _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.
|
||
|
||
Означает то, что вы забыли передать в параметрах то или иное значение.
|
||
Необходимое значение указано во 2 предложении.
|
||
Чтобы решить эту проблему вам нужно просто добавить поле и его значение в передаваемые параметры.
|
||
|
||
Клиент
|
||
""""""
|
||
|
||
Если же вы встретили следующую проблему:
|
||
|
||
.. code-block:: text
|
||
|
||
Client authentication failed.
|
||
|
||
Это означает, что переданные параметры не соответствуют ни одному зарегистрированному приложению.
|
||
Проверьте ваши значения code и redirect_uri, а лучше используйте уже сгенерированную ссылку на странице информации о приложении.
|
||
|
||
.. _auth-finish:
|
||
|
||
Ошибки во время завершения авторизации
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
После того, как пользователь пройдёт авторизацию на Ely, ему будет предоставлен список разрешений, касающихся вашего приложения.
|
||
Если пользователь разрешит доступ, то всё пройдёт как описано в документации выше, но если же он нажмёт на кнопку "Отказать",
|
||
то он будет перенаправлен на ваш redirect_uri, но с другими GET параметрами:
|
||
|
||
.. code-block:: http
|
||
|
||
http://someresource.by/oauth/some.php?error=access_denied&error_message=The+resource+owner+or+authorization+server+denied+the+request.
|
||
|
||
То есть в вашем обработчике по пути redirect_uri вам необходимо обработать состояние, когда нет параметра code, но есть error
|
||
и вывести пользователю какое-либо сообщение о том, что пользователь не дал доступа к своим данным - вы не дадите доступа к своему сервису :_:
|
||
|
||
.. _access-token:
|
||
|
||
Ошибки во время обмена токенов
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Поскольку обмен кода на токен доступа происходит через отправку POST запроса, данные передаются обратно в формате JSON.
|
||
Поэтому опознать сообщение об ошибке можно по наличию поля **error** в ответе от сервера.
|
||
|
||
В случае возникновения ошибки вы получите 2 поля:
|
||
|
||
.. code-block:: javascript
|
||
|
||
{
|
||
"error": "invalid_request",
|
||
"error_description": "bla bla bla bla"
|
||
}
|
||
|
||
В поле **error** находится системное описание ошибки, оно указано в скобках у разделов ниже. В поле **error_description**
|
||
находится описание ошибки на английском языке. Содержание достаточно для самостоятельного решения проблемы, но в случае непонятности
|
||
той или иной ошибки, внизу привидён список возможных ошибок с пояснениями на русском языке.
|
||
|
||
Поля (invalid_request)
|
||
""""""""""""""""""""""
|
||
|
||
Смотрите "Ошибки при инициализации авторизации - :ref:`auth-start-fields`".
|
||
|
||
Неподдерживаемый Grant (unsupported_grant_type)
|
||
"""""""""""""""""""""""""""""""""""""""""""""""
|
||
|
||
Если вы встретили эту ошибку, то это значит, что вы попытались произвести авторизацию по неизвестному для нашего oAuth сервера типу Grant.
|
||
На данный момент Ely поддерживает только grant **authorization_code**, поэтому использование любого другого значения привидёт к этой ошибке.
|
||
|
||
Клиент (invalid_client)
|
||
"""""""""""""""""""""""
|
||
|
||
Эта ошибка возникает в случае, когда трио значений **client_id**, **client_secret** и **redirect_uri** не совпали
|
||
ни с одним из зарегистрированных приложений. Перепроверьте ваши значения.
|
||
|
||
Ошибка доступа (invalid_grant)
|
||
""""""""""""""""""""""""""""""
|
||
|
||
Эта ошибка встречается в том случае, если переданный **code** не соответствует вашим **client_id** и **redirect_uri**.
|
||
Возможно, вы неправильно обработали полученные данные или на нашем сервере были сброшены коды авторизации по каким-либо техническим причинам (маловероятно).
|
||
|
||
Неизвестная ошибка (undefined_error)
|
||
""""""""""""""""""""""""""""""""""""
|
||
|
||
Код на сервере никогда не будет идеален и может случится так, что виноват буду я, а не вы. Если вы стабильно получаете эту ошибку,
|
||
то, пожалуйста, сообщите мне об этом в `форму обратной связи <http://ely.by/site/contact>`_, чтобы я мог оперативно всё исправить.
|