Руководство по Loginza.API

Оглавление

  1. Обзор Loginza.API
  2. Проверка ключа token через Loginza.API
  3. Формат данных ответа проверки token
  4. Установка JavaScript виджета
  5. Настройка набора кнопок провайдеров в виджете
  6. Провайдер авторизации по умолчанию
  7. Установка языка интерфейса виджета
  8. Готовые плагины Loginza

Обзор Loginza.API

Loginza.API - это единый механизм авторизации использующий различные алгоритмы аутентификации пользователей различных провайдеров учетных записей (OpenID, Google, Yandex и тп.).

Loginza.API — своего рода программная прослойка, преобразовывающая различные механизмы авторизации к единому механизму. Иными словами, при использовании Loginza.API Вам не придется вникать в различные программные аспекты авторизации поддерживаемых нами провайдеров учетных записей.

Мы сделали Loginza.API максимально простым, удобным, а главное безопасным способом авторизации через OpenID и др. провайдеров. Процесс авторизации конечного пользователя для стороны запрашивающей авторизацию (WEB-сайта использующего Loginza.API) всегда будет выглядеть одинаково, независимо от того, какой способ и какого провайдера авторизации выбрал конечный пользователь.

Процесс авторизации через Loginza.API можно разбить на этапы:

  1. Сайт запрашивает авторизацию пользователя, предлагая конечному пользователю выбор варианта авторизации с использованием Loginza.Widget;
  2. Пользователь выбирает провайдера учетных записей, на котором у пользователя создана учетная запись (Google, Yandex, Rambler и т.п., или OpenID учетная запись);
  3. Loginza.Widget обслуживает пользователя, перенаправляет его на сайт провайдера выбранной учетной записи и обрабатывает ответы провайдера;
  4. В случае успешной или не успешной авторизации, Loginza.Widget перенаправляет пользователя на указанный URL-адрес принадлежащий сайту который запрашивал авторизацию;
  5. Вместе с пользователем на URL-адрес будет передана в POST запросе переменная token, содержащая уникальный идентификатор ячейки хранения результата авторизации на сервере Loginza;
  6. Сайт, который запрашивает авторизацию, должен получить значение POST переменной token и, используя запрос к Loginza.API, запросить результат авторизации пользователя передав значение token;
  7. В ответ на данный запрос проверки token, Loginza.API возвращает ответ в формате JSON содержащий данные профиля пользователя или ошибки (если такая возникла в ходе авторизации);
  8. На основе полученного ответа, сайт запросивший авторизацию запоминает данные профиля пользователя и считает его авторизовавшимся (создает сессию) или выводит сообщение об ошибке для пользователя.

Проверка ключа token через Loginza.API

Чтобы проверить переданное в POST запросе значение переменной token на валидность и узнать результат авторизации пользователя, нужно сделать запрос по адресу:

http://loginza.ru/api/authinfo?token=[TOKEN_KEY_VALUE]&id=[WIDGET_ID]&sig=[API_SIGNATURE]
Где, [TOKEN_KEY_VALUE] - проверяемое значение token;
[WIDGET_ID] - ID виджета;
[API_SIGNATURE] - подпись запроса к API. Расчитывается как MD5 от сложения строк значения token и секретного ключа виджета. Пример: md5(token+skey).

ВНИМАНИЕ: Для наибольшей безопасности авторизации обязательно используйте передачу параметров id и sig при проверке token. Активируйте режим безопасной проверки token в настройках виджета (см. Мой виджет Loginza).

Получить ID виджета и секретный ключ можно в разделе Мой виджет Loginza Вашего аккаунта Loginza.

Формат данных ответа проверки token

В случае если в ходе авторизации пользователя возникла ошибка, будет возвращен ответ в формате JSON, содержащий код ошибки и ее расшифровку:

{"error_type":"token_validation","error_message":"Empty token value."}

Если авторизация прошла успешно, то в ответе будет передана информация о пользователе в формате JSON:

{"identity":"http:\/\/admin.loginza.ru\/","provider":"http:\/\/loginza.ru\/server\/",
"name":{"full_name":"\u0421\u0435\u0440\u0433\u0435\u0439 \u0421\u0435\u0440\u0433\u0435\u0439"},
"nickname":"admin","email":"admin@loginza.ru","gender":"M","dob":"1985-01-31"}

Перечень данных профиля может различаться в зависимости от выбранного провайдера авторизации. Список всех доступных полей доступен в разделе "Структура данных профиля".

Для парсинга JSON данных можно использовать PHP функцию json_decode() или PHP класс JSON.php.

Установка JavaScript виджета

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

Установите следующий HTML-код на страницу Вашего сайта:

<script src="//loginza.ru/js/widget.js" type="text/javascript"></script>
<a href="https://loginza.ru/api/widget?token_url=[RETURN_URL]" class="loginza">Войти через OpenID</a>
Где: [RETURN_URL] - URL-адрес страницы куда будет возвращен пользователь после успешной авторизации или в случае ошибки. Нужно указать полный URL-адрес с http:// или https://, предварительно кодированный PHP функцией urlencode().

ВНИМАНИЕ: В значении [RETURN_URL] используйте значение домена в том виде, в котором он был введен при регистрации виджета (см. Мой виджет Loginza).

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

Настройка набора кнопок провайдеров в виджете

Если Вам необходимо ограничить набор кнопок провайдеров доступных пользователям или изменить их порядок, то используйте параметр providers_set в адресе href ссылки на виджет. Порядок кнопок будет соответствовать порядку перечисления провайдеров в параметре providers_set.

Допустимы следующие значения параметра providers_set (если используется несколько значений, перечислите их через запятую):
google, yandex, mailruapi, mailru, vkontakte, facebook, odnoklassniki, livejournal, twitter, linkedin, loginza, myopenid, webmoney, rambler, flickr, lastfm, verisign, aol, steam, openid.

Пример ссылки вызова виджета с набором кнопок социальных сетей Вконтакте, Facebook и Twitter:

<script src="//loginza.ru/js/widget.js" type="text/javascript"></script>
<a href="https://loginza.ru/api/widget?token_url=http%3A%2F%2Fmysite.tld%2Fpath%2Fresult.php&providers_set=vkontakte,facebook,twitter" class="loginza">Войти через социальные сети</a>
Вызов виджета с такими параметрами откроет следующий диалог:

Виджет с набором кнопок социальных сетей Вконтакте, Facebook и Twitter

Провайдер авторизации по умолчанию

Есть возможность заранее определить провайдера авторизации, который будет предложен пользователю в виджете. Для этого необходимо добавить provider=[PROVIDER_NAME] в параметр href ссылки.

Пример ссылки вызова виджета для Yandex:

<script src="//loginza.ru/js/widget.js" type="text/javascript"></script>
<a href="https://loginza.ru/api/widget?token_url=http%3A%2F%2Fmysite.tld%2Fpath%2Fresult.php&provider=yandex" class="loginza">Войти через Yandex</a>

Допустимы следующие значения параметра provider:
google, yandex, mailruapi, mailru, vkontakte, facebook, odnoklassniki, livejournal, twitter, linkedin, loginza, myopenid, webmoney, rambler, flickr, lastfm, verisign, aol, steam, openid.

Установка языка интерфейса виджета

Интерфейс виджета реализован в пяти языках: русский, украинский, белорусский, французский и английский. Выбор языковой версии устанавливается параметром lang в параметре href ссылки на виджет.
Доступные значения параметра: ru, uk, be, fr, en. Так же разрешено использовать 3-х символьное обозначение языка, согластно ISO 639-3.

Пример ссылки вызова виджета на английском языке:

<script src="//loginza.ru/js/widget.js" type="text/javascript"></script>
<a href="https://loginza.ru/api/widget?token_url=http%3A%2F%2Fmysite.tld%2Fpath%2Fresult.php&lang=en" class="loginza">Sign in</a>

Если в параметрах виджета не задан параметр lang, то будет использоваться язык который установлен как предпочтительный в настройках браузера пользователя.

Готовые плагины

WordPress плагин на основе Loginza.API

Для обладателей блога на движке WordPress мы предлагаем ознакомиться с WordPress плагином Loginza.

LiveStreet плагин Loginza

Для обладателей сайтов на LiveStreet мы предлагаем ознакомиться с LiveStreet плагином Loginza.

PhpBB модификация авторизации Loginza

Для формов на движке phpBB Вы можете использовать phpBB модификацию Loginza. Данная модификация позволяет Вашим пользователям пройти авторизацию и регистрацию через уже существующие аккаунты популярных порталов и социальных сетей.

Сторонний плагин для Joomla

Авторы плагина: Антон Пискунов, Роман Александров
Страница плагина:  http://vjoomla.ru/blogs/item/277-loginza.html

CMS Cogear с интеграцией Loginza

Оф. сайт Cogear:  http://cogear.ru
Описание:  http://cogear.ru/loginza-502.html

Сторонний плагин для CMS Drupal

Автор плагина: Обухов Никита
Страница плагина:  http://docs.drupal.ru/node/45330