oAuth авторизация ----------------- На этой странице вы найдёте информацию о подключении oAuth авторизации для вашего сайта через сервис Ely.by. Это такой же способ авторизации, как и вход через Вконтакте, Twitter, Google, Facebook и другие. Вкупе с использованием нашей системы скинов на своём сервере это позволит увеличить количество игроков на сервере и на сайте сервера. Добавление приложения ===================== Для начала вам необходимо создать новое приложение. Вы можете это сделать на `странице добавления приложения `_. Внимательно отнеситесь к заполняемым полям - они будут влиять на внешний вид страницы авторизации. .. note:: Просмотреть уже зарегистрированные приложения можно на `небольшой странице `_, посвящённой oAuth авторизации на основном сайте. Описание: ~~~~~~~~~ :Название: Задаёт имя приложения, отображаемое на странице авторизации и в списке ваших приложений. **Обязательное поле**. :Описание: Отображается под назаванием приложения и позволяет пользователю убедится в том, что он авторизуется именно на желаемом ресурсе. :Адрес сайта: Позволяет задать обратную ссылку на ваш сайт. :Изображение: Ссылка на логотип или нечто иное, идентифицирующее ваш проект. Это поле не обязательно, но является крайне желательным для заполнения. Параметры авторизации: ~~~~~~~~~~~~~~~~~~~~~~ :Тип ответа: Задаёт дальнейшие действия сервиса oAuth авторизации после выполнения пользователем авторизации. На данным момент поддерживается только вариант "Получить код авторизации", что является форматом ответа для авторизации на сайтах. :Перенаправление: URL адрес, на который будет переадресован пользователь с данными, согласно выбранному *типу ответа*, после авторизации. **Обязательное поле**. Разрешения: ~~~~~~~~~~~ .. note:: Поскольку API для работы с Ely.by ещё не создано, вместе с получением токена доступа (access_token) вы получите и данные о пользователе. .. list-table:: Список доступных разрешений :widths: 15 85 :header-rows: 1 * - Разрешение - Описание * - E-mail адрес - Регистрационный e-mail адрес пользователя, подтверждённый им при регистрации. Инициализация авторизации ========================= После того, как вы добавите приложение, получите ссылку на инициализацию авторизации и разместите её в любом удобном месте, например так: .. code-block:: html Войти через Ely.by По нажатию на ссылку, `если всё в порядке `_, пользователь попадёт на нашу страницу авторизации, где будут представлены данные вашего приложения, указанные при его регистрации. После успешного завершения процедуры авторизации, пользователь будет перенаправлен на страницу **перенаправления после авторизации** (redirect_uri). Если пользователь откажется от авторизации, то вы можете обработать и это, согласно `следующему разделу `_. Данные придут в следующем формате: .. code-block:: html ?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 '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 объектом и могут быть прочитаны в большинстве языков программирования без привлечения сторонних библиотек. Ознакомьтесь со списком возможных ошибкок в `следующем разделе `_. ------------------- После парсинга 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 авторизацию с первого раза получается далеко не у всех. Самым важным является правильно понять причину и исправить её. Ниже приведены стандартные и предусмотренные сообщения, которые вы можете получить в случае неправильной передачи данных на сервер или нестандартных действий пользователя. Тем не менее, если вы получили ошибку, неописанную в этой документации, пожалуйста, сообщите мне о ней в `форму обратной связи `_. .. _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) """""""""""""""""""""""""""""""""""" Код на сервере никогда не будет идеален и может случится так, что виноват буду я, а не вы. Если вы стабильно получаете эту ошибку, то, пожалуйста, сообщите мне об этом в `форму обратной связи `_, чтобы я мог оперативно всё исправить.