oAuth авторизация

На этой странице вы найдёте информацию о подключении oAuth авторизации для вашего сайта через сервис Ely.by. Это такой же способ авторизации, как и вход через Вконтакте, Twitter, Google, Facebook и другие. Вкупе с использованием нашей системы скинов на своём сервере это позволит увеличить количество игроков на сервере и на сайте сервера.

Добавление приложения

Для начала вам необходимо создать новое приложение. Вы можете это сделать на странице добавления приложения. Внимательно отнеситесь к заполняемым полям - они будут влиять на внешний вид страницы авторизации.

Примечание

Просмотреть уже зарегистрированные приложения можно на небольшой странице, посвящённой oAuth авторизации на основном сайте.

Описание:

Название:Задаёт имя приложения, отображаемое на странице авторизации и в списке ваших приложений. Обязательное поле.
Описание:Отображается под назаванием приложения и позволяет пользователю убедится в том, что он авторизуется именно на желаемом ресурсе.
Адрес сайта:Позволяет задать обратную ссылку на ваш сайт.
Изображение:Ссылка на логотип или нечто иное, идентифицирующее ваш проект. Это поле не обязательно, но является крайне желательным для заполнения.

Параметры авторизации:

Тип ответа:Задаёт дальнейшие действия сервиса oAuth авторизации после выполнения пользователем авторизации. На данным момент поддерживается только вариант “Получить код авторизации”, что является форматом ответа для авторизации на сайтах.
Перенаправление:
 URL адрес, на который будет переадресован пользователь с данными, согласно выбранному типу ответа, после авторизации. Обязательное поле.

Разрешения:

Примечание

Поскольку API для работы с Ely.by ещё не создано, вместе с получением токена доступа (access_token) вы получите и данные о пользователе.

Список доступных разрешений
Разрешение Описание
E-mail адрес Регистрационный e-mail адрес пользователя, подтверждённый им при регистрации.

Инициализация авторизации

После того, как вы добавите приложение, получите ссылку на инициализацию авторизации и разместите её в любом удобном месте, например так:

<a href="<ваша_ссылка>">Войти через Ely.by</a>

По нажатию на ссылку, если всё в порядке, пользователь попадёт на нашу страницу авторизации, где будут представлены данные вашего приложения, указанные при его регистрации.

После успешного завершения процедуры авторизации, пользователь будет перенаправлен на страницу перенаправления после авторизации (redirect_uri).

Если пользователь откажется от авторизации, то вы можете обработать и это, согласно следующему разделу.

Данные придут в следующем формате:

<redirect_uri>?code=<код_авторизации>

Например это может выглядеть так:

http://someresource.by/oauth/ely.php?code=dkpEEVtXBdIcgdQWak4SOPEpTJIvYa8KIq5cW9GJ

Где:

redirect_uri http://someresource.by/oauth/ely.php
код_авторизации dkpEEVtXBdIcgdQWak4SOPEpTJIvYa8KIq5cW9GJ

Обмен кода на ключ

После получения кода авторизации, вам необходимо обменять его на ключ авторизации (access_key). Для этого вам необходимо выполнить POST запрос на url:

http://oauth.ely.by/access-token

И передать туда параметры client_id, client_secret, redirect_uri и grant_type. Значения этих параметров вы можете найти на странице с информацией о вашем приложении.

Пример реализации запроса на 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 объектом и могут быть прочитаны в большинстве языков программирования без привлечения сторонних библиотек.

Ознакомьтесь со списком возможных ошибкок в следующем разделе.


После парсинга JSON строки вы получите следующие данные:

{
    "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 авторизацию с первого раза получается далеко не у всех. Самым важным является правильно понять причину и исправить её. Ниже приведены стандартные и предусмотренные сообщения, которые вы можете получить в случае неправильной передачи данных на сервер или нестандартных действий пользователя.

Тем не менее, если вы получили ошибку, неописанную в этой документации, пожалуйста, сообщите мне о ней в форму обратной связи.

Ошибки при инициализации авторизации

Поля

Ошибка с текстом:

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 предложении. Чтобы решить эту проблему вам нужно просто добавить поле и его значение в передаваемые параметры.

Клиент

Если же вы встретили следующую проблему:

Client authentication failed.

Это означает, что переданные параметры не соответствуют ни одному зарегистрированному приложению. Проверьте ваши значения code и redirect_uri, а лучше используйте уже сгенерированную ссылку на странице информации о приложении.

Ошибки во время завершения авторизации

После того, как пользователь пройдёт авторизацию на Ely, ему будет предоставлен список разрешений, касающихся вашего приложения. Если пользователь разрешит доступ, то всё пройдёт как описано в документации выше, но если же он нажмёт на кнопку “Отказать”, то он будет перенаправлен на ваш redirect_uri, но с другими GET параметрами:

http://someresource.by/oauth/some.php?error=access_denied&error_message=The+resource+owner+or+authorization+server+denied+the+request.

То есть в вашем обработчике по пути redirect_uri вам необходимо обработать состояние, когда нет параметра code, но есть error и вывести пользователю какое-либо сообщение о том, что пользователь не дал доступа к своим данным - вы не дадите доступа к своему сервису :_:

Ошибки во время обмена токенов

Поскольку обмен кода на токен доступа происходит через отправку POST запроса, данные передаются обратно в формате JSON. Поэтому опознать сообщение об ошибке можно по наличию поля error в ответе от сервера.

В случае возникновения ошибки вы получите 2 поля:

{
    "error": "invalid_request",
    "error_description": "bla bla bla bla"
}

В поле error находится системное описание ошибки, оно указано в скобках у разделов ниже. В поле error_description находится описание ошибки на английском языке. Содержание достаточно для самостоятельного решения проблемы, но в случае непонятности той или иной ошибки, внизу привидён список возможных ошибок с пояснениями на русском языке.

Поля (invalid_request)

Смотрите “Ошибки при инициализации авторизации - Поля”.

Неподдерживаемый 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)

Код на сервере никогда не будет идеален и может случится так, что виноват буду я, а не вы. Если вы стабильно получаете эту ошибку, то, пожалуйста, сообщите мне об этом в форму обратной связи, чтобы я мог оперативно всё исправить.