Loginza.API quick guide

Table of contents

  1. Loginza.API overview
  2. Token key verification through the Loginza.API
  3. The format of the token verification response
  4. Installing the JavaScript widget
  5. Adjusting the selection of provider buttons in the widget
  6. Default authentication provider
  7. Setting the widget interface language
  8. Loginza plugins

Loginza.API overview

The Loginza.API is a single authentication mechanism that uses various algorithms for authenticating users with a wide range of accounts such as OpenID, Google, Yandex and so on.

The Loginza.API is a program layer that converts different authentication mechanisms into a common mechanism. In other words, by using the Loginza.API, you won’t have to get to grips with the different authentication programming nuances of any of the account providers we support.

We have made the Loginza.API as simple, convenient and, most importantly, secure a method of logging in using OpenID and accounts from other providers as we possibly could. The authorization process always looks the same in terms of the website using the Loginza.API, it doesn’t matter which login method or account provider the end user chooses.

The process of logging in through the Loginza.API can be divided into the following stages:

  1. The site requests the user to log in through the Loginza.Widget. The end user has a selection of login methods at their disposal.
  2. The user then picks a provider with which they have an account, for example, Google, Yandex, Rambler, OpenID etc.
  3. The Loginza.Widget processes the user’s request and redirects them to the relevant account provider, and processes the responses returned.
  4. No matter whether of not the authentication was successful, the Loginza.Widget redirects the user back to the URL address of the website requesting authorization.
  5. A token variable will be included in the POST request to the URL when the user is redirected. The variable token contains a unique identifier of the location of the result of the authorization on the Loginza server.
  6. The site requesting authentication should receive a POST value for the token variable, and, using the Loginza.API, request the results of the user authentication by transfering the token value.
  7. In response to this token verification request, the Loginza.API returns a response in the JSON format. The response will either contain user profile data or errors (if any occur during the process).
  8. On the basis of the response received, the site requesting authorization stores the user profile data and considers the user to be authorized (begins a session) or generates an error message for the user.

Token key verification through the Loginza.API

The following address is used to verify the value of the variable token transferred during the POST request and to determine the result of the user’s authorization request:

[TOKEN_KEY_VALUE] - is the value of the verified token;
[WIDGET_ID] - widget ID;
[API_SIGNATURE] - request signature API. Calculate as: md5(token+skey).

Attention: To improve security while logging in, be sure to use the id and sig parameters when verifying the token. Activate secure token verification in the widget settings menu (see My Loginza widget).

You can acquire a widget ID and secret key in the My Loginza widget section of your Loginza account.

The format of the token verification response

If an an error occurs during the user authentication process, a response in JSON format will be returned, the response shall contain the error code and script:

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

If the authentication was successfully then, in response, the user’s information will be transferred in JSON format:

"name":{"full_name":"\u0421\u0435\u0440\u0433\u0435\u0439 \u0421\u0435\u0440\u0433\u0435\u0439"},

The PHP function json_decode() or PHP class JSON.php can be used to parse the JSON data.

Installing the JavaScript widget

In order to use the Loginza.Widget you must first perform a simple installation procedure on your site.

Embed the following HTML-code in a page of your site:

<script src="//loginza.ru/js/widget.js" type="text/javascript"></script>
<a href="https://loginza.ru/api/widget?token_url=[RETURN_URL]" class="loginza">Sign In</a>
[RETURN_URL] - is the URL address of the page to which the user will be directed after successfully logging in or if an error occurs. A full URL address must be indicated using the http:// or https:// prefix, which would be preliminarily coded by the PHP function urlencode().

Attention: The [RETURN_URL] value should be exactly the same as the domain used when registering the widget (see My Loginza widget).

We also recommend that you familiarize yourself with further examples of installing widgets on pages of your website.

Adjusting the selection of provider buttons in the widget

If you need to limit the number of provider buttons available to users or change the order that they appear, then you should use the providers_set parameter in the href address of the widget link. The button order shall correspond to the order the providers are listed in the providers_set parameter.

The following providers_set parameter values are acceptable (if more than one value is used please separate them with a comma):
google, yandex, mailruapi, mailru, vkontakte, facebook, twitter, loginza, myopenid, webmoney, rambler, flickr, lastfm, verisign, aol, steam, openid.

The following is an example of a widget request link using a selection of buttons from the social networks VKontakte, Facebook, and 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">Sign In</a>
A request from a widget with these parameters will open the following dialogue:

Widget buttons from the social networks Vkontakte, Facebook and Twitter.

Default authentication provider

The authentication provider that is offered to the widget user can be defined in advance. For that you’ll need to add provider=[PROVIDER_NAME] to the href parameter of the link.

The following is an example of a request link from the Yandex widget:

<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">Sign in from Yandex</a>

The following provider parameter values are acceptable:
google, yandex, mailruapi, mailru, vkontakte, facebook, twitter, loginza, myopenid, webmoney, rambler, flickr, lastfm, verisign, aol, steam, openid.

Setting the widget interface language

The widget interface is available in five languages: Russian, украинский, белорусский, французский and English. The language is set by the lang parameter within the "inf" parameter in the href links to the widget. Acceptable values are: ru, uk, be, fr, en. You can also use ISO 639-3 three-letter language identifiers.

The following is an example of a widget request link in English:

<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>

If the lang parameter is not specified in the widget settings then the language of the widget will be defined according to the user’s browser settings.

Loginza plugins

WordPress plug-in based on the Loginza.API

For owners of a blog powered by the WordPress engine we would recommend using the WordPress plug-in from Loginza.

Loginza LiveStreet plugin

We would like to introduce owners of LiveStreet sites to the Loginza LiveStreet plugin.

PhpBB modification of Loginza authentication

For forums powered by the phpBB engine you may use the phpBB modification from Loginza. This modification allows our users to go through the authentication and registration procedures by using their existing accounts with popular portals and social networks.

Third-party plugin for Joomla

Developers: Anton Piskunov, Roman Aleksandrov
Website:  http://vjoomla.ru/blogs/item/277-loginza.html

CMS Cogear with Loginza integration

Official website:  http://cogear.ru
Description:  http://cogear.ru/loginza-502.html

Third-party plugin for CMS Drupal

Developer: Obukhov Nikita
Webpage:  http://docs.drupal.ru/node/45330