From b2451ffc9caf8a0e23404be25c86c5e356e7a75c Mon Sep 17 00:00:00 2001 From: ErickSkrauch Date: Thu, 21 Feb 2019 03:52:03 +0300 Subject: [PATCH] Split documentation to multilingual structure --- source/_static/style.css | 17 +- source/conf.py | 9 +- source/en/oauth.rst | 424 ++++++++++++++++++ source/index.rst | 32 +- .../minecraft-auth/authlib-install.png | Bin .../minecraft-auth/authlib/authlib-1.3.1.jar | Bin .../minecraft-auth/authlib/authlib-1.3.jar | Bin .../minecraft-auth/authlib/authlib-1.5.13.jar | Bin .../minecraft-auth/authlib/authlib-1.5.16.jar | Bin .../minecraft-auth/authlib/authlib-1.5.17.jar | Bin .../installing_by_inclasstranslator.png | Bin source/{ => ru}/api.rst | 0 source/{ => ru}/minecraft-auth.rst | 0 source/{ => ru}/oauth.rst | 11 +- .../{skin-system.rst => ru/skins-system.rst} | 10 +- 15 files changed, 468 insertions(+), 35 deletions(-) create mode 100644 source/en/oauth.rst rename source/{ => ru}/_static/minecraft-auth/authlib-install.png (100%) rename source/{ => ru}/_static/minecraft-auth/authlib/authlib-1.3.1.jar (100%) rename source/{ => ru}/_static/minecraft-auth/authlib/authlib-1.3.jar (100%) rename source/{ => ru}/_static/minecraft-auth/authlib/authlib-1.5.13.jar (100%) rename source/{ => ru}/_static/minecraft-auth/authlib/authlib-1.5.16.jar (100%) rename source/{ => ru}/_static/minecraft-auth/authlib/authlib-1.5.17.jar (100%) rename source/{ => ru}/_static/minecraft-auth/installing_by_inclasstranslator.png (100%) rename source/{ => ru}/api.rst (100%) rename source/{ => ru}/minecraft-auth.rst (100%) rename source/{ => ru}/oauth.rst (98%) rename source/{skin-system.rst => ru/skins-system.rst} (99%) diff --git a/source/_static/style.css b/source/_static/style.css index 4100bbb..43bf85a 100644 --- a/source/_static/style.css +++ b/source/_static/style.css @@ -4,7 +4,16 @@ body { background: #ebe8e1!important; } -h1, h2, h3, h4, h5, h6, legend, .wy-side-nav-search > a, .wy-nav-top a { +h1, +h2, +h3, +h4, +h5, +h6, +legend, +.wy-side-nav-search > a, +.wy-nav-top a, +.caption-text { font-family: "Roboto Condensed", "Roboto Slab", sans-serif; font-weight: normal; } @@ -35,3 +44,9 @@ h1, h2, h3, h4, h5, h6, legend, .wy-side-nav-search > a, .wy-nav-top a { .wy-nav-top { line-height: 30px; } + +.wy-menu .caption-text { + color: #379070; + font-size: 18px; + text-transform: none; +} diff --git a/source/conf.py b/source/conf.py index aee0bd0..c74ea57 100644 --- a/source/conf.py +++ b/source/conf.py @@ -16,6 +16,7 @@ import sys import os import sphinx_rtd_theme +import datetime # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -45,8 +46,8 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = unicode('Документация Ely.by', "utf-8" ) -copyright = '2015, ErickSkrauch' +project = 'Documentation of the Ely.by' +copyright = str(datetime.datetime.now().year) + ', ErickSkrauch' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -59,7 +60,7 @@ release = '1.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -language = 'ru' +language = 'en' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: @@ -112,7 +113,7 @@ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -html_title = unicode('Документация Ely.by v' + release, 'utf-8') +html_title = 'Documentation for the Ely.by' # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None diff --git a/source/en/oauth.rst b/source/en/oauth.rst new file mode 100644 index 0000000..2864232 --- /dev/null +++ b/source/en/oauth.rst @@ -0,0 +1,424 @@ +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: + +* :samp:`http://site.com` +* :samp:`http://site.com/oauth/ely` +* :samp:`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: + +.. code-block:: text + + https://account.ely.by/oauth2/v1?client_id=&redirect_uri=&response_type=code&scope= + +.. list-table:: Valid query parameters + :widths: 1 1 98 + :header-rows: 1 + + * - Parameter + - Value example + - Description + * - *clientId* + - :samp:`ely` + - **Required**. ClientId that was received during registration. + * - *redirect_uri* + - :samp:`http://site.com/oauth.php` + - **Required**. Return-forwarding address, which is matches the address specified during the application + registration. + * - *response_type* + - :samp:`code` + - **Required**. Response type. At the moment, only ``code`` is supported. + * - *scope* + - :samp:`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 <#available-scopes>`_. + * - *state* + - :samp:`isfvubuysdboinsbdfvit` + - Randomly generated string. Used as a session identifier to increase security. Will be returned unchanged after + authorization is completed. + * - *description* + - :samp:`यो अनुप्रयोग विवरण` + - 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* + - :samp:`consent` or :samp:`select_account` + - Forcibly display the request for permissions (``consent``) or forcibly request an account selection + (``select_account``). + * - *login_hint* + - :samp:`erickskrauch` or :samp:`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. + +.. _available_scopes: +.. list-table:: List of available scopes + :widths: 1 99 + :header-rows: 0 + + * - **account_info** + - Get user information. + * - **account_email** + - Response to a request for user information will also contain user's email address. + * - **offline_access** + - With an ``access_token`` you will also recieve a ``refresh_token``. See more at + `the corresponding section <#refresh-token-grant>`_. + * - **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: + +.. code-block:: html + + Login via Ely.by + +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 ``?code=&state=`` for a successful authorization and +``&error_message=`` for a failed one. + +Examples of successful and unsuccessful redirects: + +.. code-block:: text + + 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. + +.. _authorization-code-grant: + +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: + +.. code-block:: text + + https://account.ely.by/api/oauth2/v1/token + +And pass in following parameters: + +.. list-table:: + :widths: 1 99 + :header-rows: 0 + + * - ``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. + +**An example of the exchange in PHP:** + +.. code-block:: php + + 'ely', // Your ClientId that was received during registration + 'client_secret' => 'Pk4uCtZw5WVlSUpvteJuTZkVqHXZ6aNtTaLPXa7X', // Your ClientSecret that was received during registration + 'redirect_uri' => 'http://someresource.by/oauth/some.php', // Address where you expect to get a user back (current url) + 'grant_type' => 'authorization_code', + ]; + + // If an error occurs, then the script will stop its execution + if (isset($_GET['error'])) { + echo $_GET['error_message']; + return; + } + + // We execute the code below only if the authorization code have arrived + 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. + +.. _authorization-code-grant-response: + +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: + +.. code-block:: javascript + + { + "access_token": "4qlktsEiwgspKEAotazem0APA99Ee7E6jNryVBrZ", + "refresh_token": "m0APA99Ee7E6jNryVBrZ4qlktsEiwgspKEAotaze", // Presented only if the request had offline_access scope + "token_type": "Bearer", + "expires_in": 86400 // Number of seconds that token is active for + } + +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: + +.. code-block:: text + + 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:** + +.. code-block:: php + + `_, but with the next parameters: + +.. list-table:: + :widths: 1 99 + :header-rows: 0 + + * - ``client_id`` + - ClientClientID 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:** + +.. code-block:: php + + 'ely', // Your ClientId, that was received during registration + 'client_secret' => 'Pk4uCtZw5WVlSUpvteJuTZkVqHXZ6aNtTaLPXa7X', // Your ClientSecret, that was received during registration + '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 <#authorization-code-grant-response>`_. 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 `_. + +.. _auth-start-errors: + +Errors during authorization initiation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This section describes the errors displayed when a user is redirected from your site to our authorization initiation +page. + +.. code-block:: text + + 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. + +.. code-block:: text + + 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``. + +.. code-block:: text + + Invalid scope '{invalid_scope}'. + +The error indicates that an unknown scope was requested. Make sure you request `supported scopes <#available-scopes>`_. + +.. code-block:: text + + 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. + +.. _issue-token-errors: + +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: + +.. code-block:: json + + { + "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:** + +.. list-table:: + :widths: 1 99 + :header-rows: 0 + + * - ``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: + +.. code-block:: json + + { + "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: + +.. code-block:: json + + { + "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 <#issue-token-errors>`_, as well as several new ones: + +.. list-table:: + :widths: 1 99 + :header-rows: 0 + + * - ``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. diff --git a/source/index.rst b/source/index.rst index 931d7ae..52fbbc1 100644 --- a/source/index.rst +++ b/source/index.rst @@ -1,25 +1,21 @@ -.. Ely.by docs documentation master file, created by - sphinx-quickstart on Sun Feb 1 22:04:01 2015. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +Welcome to the Ely.by documentation! +==================================== -Добро пожаловать в документацию Ely.by! -======================================= +In this documentation you will find information about the public services of the Ely.by project, using which you'll be +able to integrate your projects with the Ely.by services. -В этой документации вы найдёте информацию о публичных сервисах проекта Ely.by, ознакомившись с которой вы сможете самостоятельно -реализовать свои программные продукты для совместной работы с сервисом Ely.by. - -Вы можете свободно улучшать и вносить предложения по изменениям в документацию в -`репозитории документации `_. - -Содержание: -~~~~~~~~~~~ +You are free to improve this documentation in the `documentation's repository `_. .. toctree:: + :caption: English articles: :maxdepth: 2 + :glob: - skin-system - minecraft-auth - oauth - api + en/* +.. toctree:: + :caption: Статьи на русском: + :maxdepth: 2 + :glob: + + ru/* diff --git a/source/_static/minecraft-auth/authlib-install.png b/source/ru/_static/minecraft-auth/authlib-install.png similarity index 100% rename from source/_static/minecraft-auth/authlib-install.png rename to source/ru/_static/minecraft-auth/authlib-install.png diff --git a/source/_static/minecraft-auth/authlib/authlib-1.3.1.jar b/source/ru/_static/minecraft-auth/authlib/authlib-1.3.1.jar similarity index 100% rename from source/_static/minecraft-auth/authlib/authlib-1.3.1.jar rename to source/ru/_static/minecraft-auth/authlib/authlib-1.3.1.jar diff --git a/source/_static/minecraft-auth/authlib/authlib-1.3.jar b/source/ru/_static/minecraft-auth/authlib/authlib-1.3.jar similarity index 100% rename from source/_static/minecraft-auth/authlib/authlib-1.3.jar rename to source/ru/_static/minecraft-auth/authlib/authlib-1.3.jar diff --git a/source/_static/minecraft-auth/authlib/authlib-1.5.13.jar b/source/ru/_static/minecraft-auth/authlib/authlib-1.5.13.jar similarity index 100% rename from source/_static/minecraft-auth/authlib/authlib-1.5.13.jar rename to source/ru/_static/minecraft-auth/authlib/authlib-1.5.13.jar diff --git a/source/_static/minecraft-auth/authlib/authlib-1.5.16.jar b/source/ru/_static/minecraft-auth/authlib/authlib-1.5.16.jar similarity index 100% rename from source/_static/minecraft-auth/authlib/authlib-1.5.16.jar rename to source/ru/_static/minecraft-auth/authlib/authlib-1.5.16.jar diff --git a/source/_static/minecraft-auth/authlib/authlib-1.5.17.jar b/source/ru/_static/minecraft-auth/authlib/authlib-1.5.17.jar similarity index 100% rename from source/_static/minecraft-auth/authlib/authlib-1.5.17.jar rename to source/ru/_static/minecraft-auth/authlib/authlib-1.5.17.jar diff --git a/source/_static/minecraft-auth/installing_by_inclasstranslator.png b/source/ru/_static/minecraft-auth/installing_by_inclasstranslator.png similarity index 100% rename from source/_static/minecraft-auth/installing_by_inclasstranslator.png rename to source/ru/_static/minecraft-auth/installing_by_inclasstranslator.png diff --git a/source/api.rst b/source/ru/api.rst similarity index 100% rename from source/api.rst rename to source/ru/api.rst diff --git a/source/minecraft-auth.rst b/source/ru/minecraft-auth.rst similarity index 100% rename from source/minecraft-auth.rst rename to source/ru/minecraft-auth.rst diff --git a/source/oauth.rst b/source/ru/oauth.rst similarity index 98% rename from source/oauth.rst rename to source/ru/oauth.rst index e52a74b..8a19c46 100644 --- a/source/oauth.rst +++ b/source/ru/oauth.rst @@ -38,7 +38,7 @@ - Описание * - *clientId* - :samp:`ely` - - **Обязательное**. ClientId, полученный при регистрации + - **Обязательное**. ClientId, полученный при регистрации. * - *redirect_uri* - :samp:`http://site.com/oauth.php` - **Обязательное**. Адрес обратной переадресации, совпадающий с адресом, указанным при регистрации приложения @@ -238,8 +238,8 @@ Обратите внимание, что поле ``email`` будет присутствовать лишь в том случае, когда был запрошен scope ``account_email``. -.. note:: В ходе дальнейшего развития сервиса, количество возвращаемых полей может увеличиться, но не уменьшиться или - измениться. +.. note:: В ходе дальнейшего развития сервиса, количество возвращаемых полей может увеличиться, но уже существующие + останутся теми же. .. _refresh-token-grant: @@ -253,9 +253,6 @@ Для выполнения операции обновления токена необходимо отправить POST запрос на тот же URL, что использовался и `при обмене кода на ключ доступа <#authorization-code-grant>`_, но со следующими параметрами: - ``grant_type`` со -значением *refresh_grant*, ``client_id``, ``client_secret``, ``scope`` и непосредственно ``refresh_token``. - .. list-table:: :widths: 1 99 :header-rows: 0 @@ -346,7 +343,7 @@ Invalid scope '{invalid_scope}'. Ошибка указывает на то, что было запрошено неизвестный ``scope``. Убедитесь, что вы запрашиваете -`поддерживаемые права <#available-scopes>`_ +`поддерживаемые права <#available-scopes>`_. .. code-block:: text diff --git a/source/skin-system.rst b/source/ru/skins-system.rst similarity index 99% rename from source/skin-system.rst rename to source/ru/skins-system.rst index 8054152..34eebe5 100644 --- a/source/skin-system.rst +++ b/source/ru/skins-system.rst @@ -70,19 +70,19 @@ URL-адреса запросов Примеры запросов ~~~~~~~~~~~~~~~~ -.. code-block:: http +.. code-block:: text http://skinsystem.ely.by/skins/erickskrauch.png?version=2&minecraft_version=1.7.2 Получает скин игрока **erickskrauch** с версии Minecraft 1.7.2. -.. code-block:: http +.. code-block:: text http://skinsystem.ely.by/cloaks/notch?version=2&minecraft_version=1.6.4 Получает плащ игрока **notch** с версии Minecraft 1.6.4. Обратите внимание, что расширение ".png" не передано. -.. code-block:: http +.. code-block:: text http://skinsystem.ely.by/textures/EnoTiK?version=2&authlib_version=1.5.17 @@ -112,13 +112,13 @@ URL-адреса запросов Примеры запросов: """"""""""""""""" -.. code-block:: http +.. code-block:: text http://skinsystem.ely.by/skins/?version=2&minecraft_version=1.5.2&name=erickskrauch.png Получает скин игрока **erickskrauch** с версии Minecraft 1.5.2. -.. code-block:: http +.. code-block:: text http://skinsystem.ely.by/cloaks/?version=2&minecraft_version=1.4.7&name=notch