Разработчикам

  • info_outlineЧто такое AuthGram?

    AuthGram - сервис авторизации пользователей при помощи Telegram. Весь процесс, со стороны пользователя, сводится к тому, чтобы получить команду авторизации и отправить её боту, который передаст данные из профиля Telegram на тот сайт, где совершается вход. Со стороны сайта, соответственно, необходимо принять авторизационные данные пользователя и идентифицировать его.

    Весь процесс авторизации поэтапно можно представить следующим образом:

    1. Пользователь, при помощи виджета, отправляет запрос на авторизацию и получает значение команды авторизации.
    2. При помощи мессенджера Telegram пользователь отправляет эту команду боту @AuthGramBot
    3. Бот подтверждает авторизацию и отправляет данные о пользователе на ваш сайт при помощи POST запроса на URL-адрес, который вы указали при регистрации.
    4. Помимо данных пользователя и секретного токена вашего приложения, таке будет отправлен авторизационный ключ. В случае успешного получения ответа от сайта, такой же ключ будет отправлен в виджет авторизации для дальнейшего связывания клиентской и серверной стороны авторизации.
  • vpn_keyПодключение javascript-виджета на сайте

    Для того, чтобы использовать виджет AuthGram, разместите следующий код на своём сайте:

    <!-- AuthGram widget: html of sign button -->
    <button data-role="authgram-sign-button" class="authgram-sign-button"><span>Войти через Telegram</span></button>
    <!-- /AuthGram widget: html of sign button -->
    
    <!-- AuthGram js-widget -->
    <script type="text/javascript" src="https://cdn.authgram.ru/js/authgram-widget.js"></script>
    <script type="text/javascript">
        var AuthGramWidget = new AuthGramWidget('[UUID ВАШЕГО ПРИЛОЖЕНИЯ]', [НАСТРОЙКИ]);
    </script>
    <!-- /AuthGram js-widget -->

    Размещать HTML-код кнопки не обязательно - вы можете привязать виджет к абсолютно любому элементу своего сайта, при помощи указания значения настройки selector

    Конструктор виджета принимает на вход два параметра - uuid вашего приложения и объект с настройками. Настройки являются необязательным параметром, но они позволяют более гибко настроить взаимодействие пользователя с виджетом авторизации.

    Доступные настройки

    • selector — селектор элемента, клик по которому запустит начало процесса авторизации при помощи AuthGram.
      По умолчанию - [data-role="authgram-sign-button"]
    • messageClass — дополнительный класс стилей для оформления инструкций по авторизации.
      По умолчанию имеет пустое значение
    • onAuthSuccess(authKey) — метод, который выполняется при успешной авторизации. На вход подаётся ключ авторизации, который отправлен на серверную часть вашего сайта. Вы можете определить здесь свою собственную логику для работы с авторизацией пользователя.
      По умолчанию происходит редирект на ту же страницу с переданным в GET-параметре ключом авторизации.
    • onAuthFail(reason) — метод, который выполняется при ошибке авторизации. На вход подаётся текст с причиной ошибки авторизации.
      По умолчанию ошибка отображается пользователю в модальном окне авторизации.
  • codeПолучение авторизационных данных пользователя

    После того, как пользователь отправит код потверждения боту, инициируется отправка данных на сайт, где выполняется вход. Будет отправлен POST запрос, в теле которого находится json следующего вида:

    {
    	"token":    "[ТОКЕН ВАШЕГО ПРИЛОЖЕНИЯ]",
    	"authKey":  "[КЛЮЧ АВТОРИЗАЦИИ ПОЛЬЗОВАТЕЛЯ]",
    	"user": {
    		"uuid":             "[ИДЕНТИФИКАТОР ПОЛЬЗОВАТЕЛЯ В UUID ФОРМАТЕ]",
    		"username":         "[НИКНЕЙМ ПОЛЬЗОВАТЕЛЯ]",
    		"firstName":        "[ИМЯ ПОЛЬЗОВАТЕЛЯ]",
    		"lastName":         "[ФАМИЛИЯ ПОЛЬЗОВАТЕЛЯ]"
    		"profilePhotoUrl":  "[ФОТО ПРОФИЛЯ (ПРИ ЕГО НАЛИЧИИ)]"
    	}
    }
    			

    Пример получения авторизационных данных для языка PHP:

    <?php
    	session_start();
    
    	$request = file_get_contents('php://input');
    	$request = json_decode($request);
    
    	$token = $request->token;
    	$user  = $request->user;
    
    	if ('ЗДЕСЬ ТОКЕН ВАШЕГО ПРИЛОЖЕНИЯ' !== $token) {
    		// токен запроса неправильный, запрос нельзя считать валидным
    	} else {
    		// токен запроса совпал с токеном вашего приложения, запрос валиден
    		// у объекта $request есть поле authKey, при помощи которого можно связать клиентскую и серверную части авторизации
    		// к примеру, сохраним идентификатор пользователя в сессию
    		$_SESSION[$request->authKey] = [
    			'uuid'      => $user->uuid,
    			'username'  => $user->username,
    			'firstName' => $user->firstName,
    			'lastName'  => $user->lastName,
    		];
    
    		// теперь, когда в js виджет придёт подтверждение авторизации и будет вызван метод onAuthSuccess(authKey)
    		// вы должны передать этот authKey на сервер, получить по нему данные из ранее сохранённой сессии
    		// и зафиксировать факт авторизации пользователя на сайте
    	}
    ?>
    			

    info Важно: при отправке POST запроса, бот ожидает ответ 200 от сервера. В случае, если этот ответ не будет получен, авторизация будет считаться проваленной.

  • settings_input_hdmiГотовые решения

    AuthGram Request Handler — библиотека для обработки входящих запросов на авторизацию. Превращает тело POST запроса с данными в PHP объект, готовый к использованию в ваших приложениях


    Данный раздел находится в стадии наполнения. Если у вас есть готовое решение для обработки авторизации и вы хотите им поделиться, сообщите об этом нам - code@authgram.ru - и мы добавим ваш плагин в этот список.