search string side menu

Модули расширения системы > Примеры модулей интеграции с ELMA365 / Пользовательский модуль для авторизации через сторонние сервисы

Пользовательский модуль OAuth2 для авторизации через сторонние сервисы

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

начало внимание

Создавать и настраивать модули могут только пользователи, включённые в группу Администраторы.

конец внимание

Создание и настройка модуля

 

Чтобы создать новый модуль, перейдите в Администрирование > Модули, нажмите кнопку + Модуль и в открывшемся окне выберите опцию Создать. Заполните информацию о модуле и нажмите кнопку Создать. Подробнее читайте в статье «Создание модуля».

Добавление обязательных настроек

Добавьте в модуль обязательные настройки. Это глобальные параметры, которые будут использоваться в сценариях модуля.  

Перейдите на вкладку Настройки, нажмите + Добавить и создайте необходимое количество свойств типа Строка, в которых будут храниться значения настроек. Для корректной работы модуля обязательно нужно добавить следующие свойства:

  • ID приложения (client_id) — идентификатор приложения, которое будет запрашивать данные в стороннем сервисе. Выдаётся при регистрации приложения в стороннем сервисе;
  • Защищённый ключ (client_secret) — секретный ключ приложения. Выдаётся при регистрации приложения в стороннем сервисе. Вместе с client_id используется для получения токена доступа к API стороннего сервиса;
  • Адрес аутентификации (auth_url) — адрес страницы авторизации в стороннем сервисе, на которую пользователь будет перенаправлен из приложения;
  • Адрес получения токена (token_url) — адрес на стороне сервиса, на который будет отправлен запрос для получения ключа доступа к API (access-токена). В запросе указываются client_id и client_secret;
  • Права доступа (scopes) — права доступа, которые будут предоставлены приложению в стороннем сервисе по access-токену. Названия прав доступа разделяются пробелом. Обязательно необходимо запрашивать доступ к сведениям, которые позволяют однозначно идентифицировать пользователя, например, к адресу электронной почты;
  • Автоматическая регистрация (auto_signup) — свойство типа Выбор «да/нет». Если параметр установлен в значение Да, несозданные в системе внутренние или внешние пользователи автоматически добавятся в ELMA365 при авторизации.

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

Отображаемые имена свойств могут быть произвольными. 

При необходимости вы можете добавить свои свойства. Их имена могут быть любыми.

После того как вы укажете все свойства, перейдите на вкладку Основные и нажмите Сохранить.

Настройка страницы подключения модуля

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

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

Рассмотрим настройку страницы подключения на примере модуля для авторизации через ВКонтакте. Список его параметров приведён в предыдущем разделе. По умолчанию все они отображаются на странице модуля.

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

  1. На вкладке Настройка нажмите кнопку Изменить форму. Откроется дизайнер интерфейсов, в котором необходимо отредактировать форму настроек модуля.

oauth2-authorization-1

  1. Удалите стандартную форму элемента: выберите виджет, нажмите на значок корзины и подтвердите удаление. Пользователем вручную задаются настройки ID приложения (client_id) и Защищённый ключ (client_secret). Вынесите их с вкладки Свойства правой панели на форму настройки и нажмите Опубликовать.

oauth2-authorization-2

Теперь на странице подключения модуля пользователь увидит только параметры, которые он должен указать вручную: 

oauth2-authorization-3

  1. Для остальных параметров задайте значения по умолчанию. Для этого перейдите на вкладку Настройки, нажмите на название свойства и в открывшемся окне укажите значение в поле По умолчанию.  

Например, в модуле авторизации ВКонтакте для свойства auth_url значение будет следующим: https://oauth.vk.com/access_token.

oauth2-authorization-4

  1. Перейдите на вкладку Основные и нажмите Сохранить.

Добавление сценария

На следующем шаге в модуль нужно добавить сценарий. В нём считываются значения настроек модуля, затем из них формируется запрос на авторизацию.  Он отправляется на сторонний сервис, который возвращает идентификатор пользователя. Идентификатор сравнивается со значением в базе данных ELMA365 и при совпадении пользователь авторизуется в системе. 

Внутри сценария отправка запроса и получение ответа от стороннего сервиса реализованы в методе oauth2_profile. Обратите внимание, что имя метода менять нельзя, поскольку система использует его для распознавания типа модуля.

Чтобы добавить сценарий:

  1. На странице модуля перейдите на вкладку Методы API и нажмите Редактировать. Откроется редактор методов.
  2. Перейдите на вкладку Сценарии и напишите код по следующему шаблону:

interface AccessTokenData { // структура данных для хранения access-токена стороннего сервиса
    access_token: string;
    refresh_token: string;
    token_type: string;
    expires_in: number;
}
 
interface OAuth2Profile {  // структура данных для хранения идентификатора пользователя
 
    user_id: string;
}
 
interface OAuth2ResponseFail { // структура данных для хранения сообщения об ошибке
    error: string;
    error_description: string; 
}
 
async function oauth2_profile (tokenData: AccessTokenData): Promise<OAuth2Profile | OAuth2ResponseFail> {
    код метода, который возвращает идентификатор пользователя или текст ошибки из OAuth2-провадйера
}

  1. Сохраните и опубликуйте сценарий.

Пример сценария для модуля авторизации через ВКонтакте

Пример для "vk.com":
/**
 * Контракт расширения для OAuth2 аутентификации
 */
 
interface AccessTokenData {
    access_token: string;
    refresh_token: string;
    token_type: string;
    expires_in: number;
}
 
interface OAuth2Profile {
    // идентификатор пользователя
    user_id: string;
    //email
    email: string;
}
 
interface OAuth2ResponseFail {
    error: string;
    error_description: string; 
}
 
 
interface UsersGetResp {
response: {
        id: string;
    }[];
 
    // Для неуспешного ответа
    error?: {
        error_code: Number;
        error_msg: string;
    };
}
 
async function oauth2_profile (tokenData: AccessTokenData): Promise<OAuth2Profile | OAuth2ResponseFail> {
    const resp = await fetch(`https://api.vk.com/method/users.get?v=5.130&access_token=${ tokenData.access_token }`);
    if (resp.ok) {
        const body = <UsersGetResp> await resp.json()
 
        if (body.error) {
            return <OAuth2ResponseFail> {
                error: body.error.error_code.toString(),
                error_description: body.error.error_msg,
            }
        }
 
        if (body.response.length == 0) {
            return <OAuth2ResponseFail> {
                error: "user_not_found",
                error_description: "User not found!"
            };
        }
 
        return <OAuth2Profile> {
            user_id: id,
            email: email
        };
    }
    
    return <OAuth2ResponseFail> {
        error: resp.statusText,
        error_description: await resp.text()
    };
}

Настройка модуля завершена. После этого пользователи смогут авторизоваться в ELMA365 с помощью учётной записи подключённого сервиса.

Чтобы подключить модуль к внешнему порталу компании, перейдите в раздел, где находится портал. На странице управления порталом нажмите на значок шестерёнки. В открывшемся окне настроек на вкладке Авторизация установите флажок рядом с названием модуля.

oauth2-authorization-5

В целях безопасности можно запретить вход на портал по логину и паролю. Для этого в поле Разрешить вход по логину / паролю установите переключатель в положение Нет. В этом случае пользователи смогут авторизоваться на портале только через сторонние сервисы. 

начало примечание

Примечание

Чтобы пользователь мог войти в ELMA365, используя как базовый адрес компании, так и дополнительный (алиас), в настройках на стороне стороннего сервиса укажите два соответствующих URL-адреса для редиректа.

конец примечание

Настройка logout в модуле OAuth2

Для обеспечения дополнительной безопасности вы можете настроить механизм logout в пользовательском модуле OAuth2. С помощью этого механизма пользователь, выходя из профиля в ELMA365, также будет выходить из привязанной учётной записи настроенного провайдера.  

Чтобы настроить механизм logout в модуле, выполните следующие действия:

  1. На странице модуля перейдите на вкладку Методы API и нажмите Редактировать. Откроется редактор методов.
  2. Перейдите на вкладку Сценарии и подключите интерфейс logout:

interface OAuth2LogoutResponse {
    redirect_url: string;
}

  1. Затем реализуйте метод oauth2_logout:

async function oauth2_logout(): Promise<OAuth2LogoutResponse | OAuth2ResponseFail> {
    return <OAuth2LogoutResponse> {
        redirect_url: "https://my_idp.com/logout"            
    };
}

В качестве параметра redirect_url укажите адрес настроенного провайдера. На указанный адрес из ELMA365 будет отправляться запрос о выходе из учётной записи.

  1. Сохраните и опубликуйте сценарий.

После этого пользователь, нажавший кнопку Выйти в ELMA365, будет перенаправлен на страницу выхода из учётной записи в настроенном провайдере OAuth2.

Также вы можете настроить на стороне провайдера OAuth2 обратную переадресацию на страницу авторизации в ELMA365 после выхода из системы.

Привязка учётной записи OAuth2 к профилю в сценариях

С помощью сценариев вы можете управлять привязкой профиля пользователя ELMA365 к учётной записи настроенного провайдера OAuth2. Для этого доступны следующие методы:

  • createWithAuthData — метод позволяет создать нового пользователя в ELMA365 и автоматически связать его с существующей учётной записью в провайдере OAuth2. Добавленные с помощью данного метода пользователи сразу получают статус Активный.

Обратите внимание, пользователь, добавленный таким способом, сможет авторизоваться в ELMA365 только с помощью провайдера OAuth2. Другие методы авторизации будут недоступны;

  • addOAuth2Data — метод позволяет привязать к профилю существующего в ELMA365 пользователя учётную запись настроенного провайдера OAuth2. После привязки пользователь сможет авторизоваться в ELMA365, используя данные провайдера. Данный метод аналогичен ручному добавлению учётной записи провайдера OAuth2 в настройках профиля пользователя на вкладке Аутентификация;
  • removeOAuth2Data — метод позволяет отвязать учётную запись провайдера OAuth2 от профиля пользователя ELMA365. Данный метод аналогичен ручному удалению учётной записи из профиля пользователя.

Подробнее о работе с перечисленными методами читайте в справке ELMA365 TS SDK в статье «Объект пользователей».

Пример работы модуля

Рассмотрим подробнее регистрацию и авторизацию пользователей на портале на примере модуля для сервиса ВКонтакте. Чтобы установить и ознакомиться с его работой, скачайте файл формата .e365 с преднастроенным модулем.

Предварительная настройка

Для установки модуля:

  1. Перейдите в Администрирование > Модули и нажмите кнопку + Модуль.
  2. В открывшемся окне нажмите Загрузить файл.
  3. Выберите загруженный ранее файл на вашем ПК и нажмите Далее.

Зарегистрируйте модуль на стороннем сервисе. Для этого:

  1. Авторизуйтесь ВКонтакте.
  2. Создайте мини-приложение. Как это сделать, читайте в официальной справке ВКонтакте.
  3. В настройках приложения задайте следующие значения:
  • Состояние — Приложение включено и видно всем;
  • Установка приложения — Требуется;
  • Open API — Включён;
  • Адрес сайта — http://elma365.ru;
  • Базовый домен — elma365.ru.

oauth2-authorization-6

Остальные настройки оставьте по умолчанию.

  1. Скопируйте ID приложения и защищённый ключ.

oauth2-authorization-7

  1. Вернитесь в интерфейс ELMA365. Перейдите в Администрирование > Модули и выберите модуль VK.com OAuth2.
  2. В настройках модуля укажите ID и защищённый ключ мини‑приложения ВКонтакте, созданного ранее.

oauth2-authorization-8

  1. Сохраните настройки и включите модуль.
  2. Перейдите в раздел, в котором подключен внешний портал.
  3. В окне настроек портала на вкладке Авторизация поставьте флажок напротив названия модуля VK.com OAuth2, через который будет выполняться авторизация.
  4. Сохраните настройки.

Принцип работы модуля

 

Разберём принцип работы модуля на примере входа на внешний портал:

  1. Пользователь переходит по ссылке-приглашению на портал и в окне регистрации нажимает Использовать другой метод регистрации.

oauth2-authorization-9

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

  1. В окне доступных сторонних сервисов выбирает опцию VK.com OAuth2.

oauth2-authorization-10

  1. Далее в окне авторизации ВКонтакте пользователь вводит логин и пароль для входа в аккаунт социальной сети.
  2. В следующем окне необходимо разрешить доступ к аккаунту.

oauth2-authorization-11

  1. Затем появляется окно приглашения на портал, в котором пользователь вводит фамилию, имя и отчество и нажимает Сохранить.
  2. Регистрация завершена. Теперь для авторизации на портале пользователю достаточно будет войти в свой аккаунт социальной сети ВКонтакте.

oauth2-authorization-12

external_viewer_intergation.html dadata_integration.html