docs/source/oauth.rst
2015-02-06 23:09:41 +03:00

286 lines
18 KiB
ReStructuredText
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

oAuth авторизация
-----------------
На этой странице вы найдёте информацию о подключении oAuth авторизации для вашего сайта через сервис Ely.by.
Это такой же способ авторизации, как и вход через Вконтакте, Twitter, Google, Facebook и другие.
Вкупе с использованием нашей системы скинов на своём сервере это позволит увеличить количество игроков на сервере и на сайте сервера.
Добавление приложения
=====================
Для начала вам необходимо создать новое приложение. Вы можете это сделать на `Странице добавления приложения <http://ely.by/auth/add>`_.
Внимательно отнеситесь к заполняемым полям - они будут влиять на внешний вид страницы авторизации.
Описание:
~~~~~~~~~
:Название: Задаёт имя приложения, отображаемое на странице авторизации и в списке ваших приложений. **Обязательное поле**.
:Описание: Отображается под назаванием приложения и позволяет пользователю убедится в том, что он авторизуется именно на желаемом ресурсе.
:Адрес сайта: Позволяет задать обратную ссылку на ваш сайт.
:Изображение: Ссылка на логотип или нечто иное, идентифицирующее ваш проект. Это поле не обязательно, но является крайне желательным для заполнения.
Параметры авторизации:
~~~~~~~~~~~~~~~~~~~~~~
:Тип ответа: Задаёт дальнейшие действия сервиса 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>`_, чтобы я мог оперативно всё исправить.