Authorization via OAuth2 protocol¶

On this page you’ll find how to implement OAuth2 authorization on your project through the Ely.by Accounts service. The implementation of this protocol will allow your users to authorize using their Ely.by account.

Application registration¶

First you need to create a new application. Select Website as the application type. For the Redirect URI you can get away with just specifying the domain, but to increase security it’s advised to use the full redirect path. Here are examples of valid addresses:

http://site.com
http://site.com/oauth/ely
http://site.com/oauth.php?provider=ely

After a successful creation of an application, you’ll be taken to the page containing a list of all your applications. If you click on the name of an application you’ll see its clientId identifier and its clientSecret secret. They’ll become important in later steps.

Authorization initiation¶

To initiate the authorization flow, you’ll have to redirect the user to the following URL:

https://account.ely.by/oauth2/v1?client_id=<clientId>&redirect_uri=<redirectUri>&response_type=code&scope=<scopesList>

Valid query parameters¶
Parameter	Value example	Description
clientId	`ely`	Required. ClientId that was received during registration.
redirect_uri	`http://site.com/oauth.php`	Required. Return-forwarding address, which matches the address specified during the application registration
response_type	`code`	Required. Response type. At the moment, only `code` is supported.
scope	`account_info account_email`	Required. The list of permissions that you want to access, separated by spaces. See all available permissions in the section below.
state	`isfvubuysdboinsbdfvit`	Randomly generated string. Used as a session identifier to increase security. Will be returned unchanged after authorization is completed.
description	`यो अनुप्रयोग विवरण`	If your application is available in several languages, you can use this field to override the default description in accordance with user’s preferred language.
prompt	`consent` or `select_account`	Forcibly display the request for permissions (`consent`) or forcibly request an account selection (`select_account`).
login_hint	`erickskrauch` or `erickskrauch@ely.by`	If a user has several accounts, then specifying username or user email in this parameter will automatically select corresponding account. This is useful in a case of re-login after the token has expired.

List of available scopes¶
account_info	Get user information.
account_email	Response to a request for user information will also contain user’s E-mail address.
offline_access	With an `access_token` you will also recieve a `refresh_token`. See more at the corresponding section.
minecraft_server_session	It will be possible to use `access_token` as a session identifier for the Minecraft.

After creating the link, place it in your template:

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

After clicking on the URL a user will be redirected to our login page after which they’ll be redirected back to the address specified in the redirect_uri parameter.

Reverse redirection returns as <redirect_uri>?code=<auth_code>&state=<state> for a successful authorization and <redirect_uri?error=<error_identifier>&error_message=<error_description> for a failed one.

Examples of successful and unsuccessful redirects:

http://site.com/oauth/ely.php?code=dkpEEVtXBdIcgdQWak4SOPEpTJIvYa8KIq5cW9GJ&state=ajckasdcjasndckbsadc
http://site.com/oauth/ely.php?error=access_denied&error_message=The+resource+owner+or+authorization+server+denied+the+request.

Exchange auth code for a access key¶

After receiving an authorization code (auth_code), you’ll need to exchange it for an authorization key (access_key). To do this, you must perform a POST request to the URL:

https://account.ely.by/api/oauth2/v1/token

And pass in following parameters:

`client_id`	ClientID that was received during registration.
`client_secret`	ClientSecret that was received during application registration.
`redirect_uri`	The exact URI that was used for user redirection.
`grant_type`	In this case, `authorization_code` should be used.
`code`	Authorization code received in GET params after successful redirect.

An example of the exchange in PHP:

<?php
// В этой переменной будут храниться ваши параметры OAuth2
$oauthParams = [
    'client_id' => 'ely', // Ваш ClientId, полученный при регистрации
    'client_secret' => 'Pk4uCtZw5WVlSUpvteJuTZkVqHXZ6aNtTaLPXa7X', // Ваш ClientSecret, полученный при регистрации
    'redirect_uri' => 'http://someresource.by/oauth/some.php', // Адрес, на который вы ожидаете получить пользователя обратно (текущий url)
    'grant_type' => 'authorization_code',
];

// Если возникла ошибка, то прерываем выполнение скрипта
if (isset($_GET['error'])) {
    echo $_GET['error_message'];
    return;
}

// Выполняем код ниже только если пришёл код авторизации
if (!is_null($_GET['code'])) {
    $oauthParams['code'] = $_GET['code'];

    $curl = curl_init();
    curl_setopt($curl, CURLOPT_URL, 'https://account.ely.by/api/oauth2/v1/token');
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($curl, CURLOPT_POST, true);
    curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($oauthParams));
    $out = json_decode(curl_exec($curl), true);
    curl_close($curl);
}

Notes to the code:

First, we declare the $oauthParams variable which will store the values that we got after registering the application.
Then we check if there was an error. In which case, we immediately stop the execution.
Then we create a POST request to exchange the code for an access_token, passing all required fields in the process.
Then we execute the request, get the answer and parse it from JSON into the associative array.

Server response¶

In case of a successful request, the response body will contain the result of exchanging the authorization code for an access_token. Data is a JSON document and can be easily interpreted by tools of a used programming language.

The JSON document body will contain the following fields:

{
    "access_token": "4qlktsEiwgspKEAotazem0APA99Ee7E6jNryVBrZ",
    "refresh_token": "m0APA99Ee7E6jNryVBrZ4qlktsEiwgspKEAotaze", // Представлен только в случае запроса с правами offline_access
    "token_type": "Bearer",
    "expires_in": 86400 // Количество секунд, на которое выдан токен
}

At this process authorization procedure is over. The resulting access_token can be used to obtain user information and to interact with our API.

Getting user information¶

If the received token has the account_info scope, then you can request information about the user’s account. To do it, you have to send a request to the URL:

https://account.ely.by/api/account/v1/info

To send access_token, the Authorization header is used with the value of Bearer {access_token}.

An example of getting user information in PHP:

<?php
$accessToken = 'some_access_token_value';

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://account.ely.by/api/account/v1/info');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $accessToken,
]);
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

In response, you will receive a JSON document with the following contents:

{
    "id": 1,
    "uuid": "ffc8fdc9-5824-509e-8a57-c99b940fb996",
    "username": "ErickSkrauch",
    "registeredAt": 1470566470,
    "profileLink": "http:\/\/ely.by\/u1",
    "preferredLanguage": "be",
    "email": "erickskrauch@ely.by"
}

Note that the email field will only be present when the account_email scope has been requested.

Note

In the future, the number of returned fields may increase, but existing ones will remain the same.

Refreshing access token¶

If you have requested the scope offline_access during authorization, then along with your access_token you’ll also get refresh_token. This token doesn’t expire and can be used to obtain a new access token when that one expires.

To perform a token update, you have to send a POST request to the same URL that was used for exchanging the auth code for an access token, but with the next parameters:

`client_id`	ClientID that was received during registration.
`client_secret`	ClientSecret that was received during application registration.
`scope`	The same scopes that were obtained for the initial access token. An attempt to extend this list will cause an error.
`refresh_token`	The token itself that was obtained along with the access token.

Example of a token refreshing in PHP:

<?php
// refresh_token, полученный при завершении авторизации
$refreshToken = 'm0APA99Ee7E6jNryVBrZ4qlktsEiwgspKEAotaze';

$requestParams = [
    'client_id' => 'ely', // Ваш ClientId, полученный при регистрации
    'client_secret' => 'Pk4uCtZw5WVlSUpvteJuTZkVqHXZ6aNtTaLPXa7X', // Ваш ClientSecret, полученный при регистрации
    'scope' => 'account_info account_email',
    'refresh_token' => $refreshToken,
    'grant_type' => 'refresh_token',
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://account.ely.by/api/oauth2/v1/token');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($requestParams));
$result = json_decode(curl_exec($curl), true);
curl_close($curl);

The answer will have exactly the same body as the result of exchanging auto code for an access token. The refresh_token field will be absent.

Available libraries¶

A simpler way is to use a ready-made library, to which you’ll only have to provide registration parameters. Listed below are libraries for various programming languages. You can extend this list by providing your own library.

PHP:
- [Official] https://github.com/elyby/league-oauth2-provider
Ruby:
- [Official] https://github.com/elyby/omniauth-ely

Possible errors¶

Below are the typical errors that you may receive after transmitting incorrect data to the authorization server. If you encounter an error that is not described in this documentation, please report it via feedback form.

Errors during authorization initiation¶

This section describes the errors displayed when a user is redirected from your site to our authorization initiation page.

Invalid request ({parameter} required).

This error means that you did not pass all the required parameters. To solve this error just add the missing parameter.

Invalid response type '{invalid_response_type_value}'.

This error indicates that you passed an unsupported type of response_type. Currently, the only supported value is code.

Invalid scope '{invalid_scope}'.

The error indicates that an unknown scope was requested. Make sure you request supported scopes.

Can not find application you are trying to authorize.

This error indicates that the passed parameters do not correspond to any of the registered applications. To solve the problem, fix your client_id and redirect_uri values.

Errors when exchanging code for a key¶

If an error occurs, instead of the expected response with the 200 status, you will receive a 40x code and the following 2 fields:

{
    "error": "invalid_request",
    "error_description": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the \"code\" parameter."
}

The error field contains the system error identifier, and error_description describes the error in English language.

Possible error values:

`invalid_request`	Not all the required request parameters were passed or the `code` value was not found in the issued codes database.
`unsupported_grant_type`	This error indicates that you tried to authorize using an unknown for our OAuth2 server Grant-type.
`invalid_client`	This error occurs when the trio of values `client_id`, `client_secret` and `redirect_uri` didn’t match with any of the registered applications.

Errors when requesting user information¶

Response status 401 indicates that the Authorization header is not present in the request or its value formed incorrectly. The response body will be as follows:

{
    "name": "Unauthorized",
    "status": 401,
    "message": "Your request was made with invalid credentials."
}

A response with the 403 status indicates that the token transferred in the Authorization header does not contain the account_info scope or it has expired. The response will be in the following format:

{
    "name": "Forbidden",
    "status": 403,
    "message": "You are not allowed to perform this action."
}

Errors while updating access token¶

When updating the access token you may encounter the same errors from exchanging auth code for an access token, as well as several new ones:

`invalid_request`	Not all the required request parameters were passed or the `refresh_token` value wasn’t found in the issued tokens database.
`invalid_scope`	The unsupported scope was listed or requested more scopes than the original token had.