Подключиться

Услуги для владельцев сайтов

E-NUM – это система авторизации, используемая для дополнительной защиты закрытых ресурсов онлайн-сервисов посредством секретного ключа (уникальной кодовой книги), хранимой в мобильном устройстве пользователя.

Вы можете легко интегрировать E-NUM авторизацию на Ваш ресурс.

Предлагается два способа интеграции: OAuth2 и Soap.



Метод интеграции OAuth2

OAuth 2.0 позволяет предоставить третьей стороне доступ к защищенным ресурсам без необходимости сообщать ей (третьей стороне) данные аутентификации пользователя (число-вопрос, число-ответ).

E-NUM поддерживает спецификацию стандарта OAuth 2.0.


E-NUM OAuth2

Схема авторизации на сайте банка с использованием системы E-NUM методом OAuth2.


E-NUM OAuth2 Flow

Детальная схема авторизации с использованием системы E-NUM методом OAuth2 (сверху вниз)

  1. Клиент банка запрашивает вход в защищенную зону онлайн-банкинга
  2. Для предоставления доступа Банк требует пройти авторизацию, для чего перенаправляет его на сайт системы E-NUM
  3. После успешной авторизации система E-NUM возвращает клиенту одноразовый код
  4. Браузер клиента, в свою очередь, передает код авторизации сайту банка
  5. Сайт банка, используя код авторизации, запрашивает у E-NUM временный токен доступа
  6. Этот токен используется в дальнейшем для обращения к методам API E-NUM, которые обеспечивают идентификацию клиента.


Описание методов OAuth2 API

  • Запрос кода авторизации
  • Получение кода авторизации
  • Запрос токена доступа
  • Получение токена доступа
  • Получение идентификационных данных пользователя

Запрос кода авторизации

URL метода - https://auth.e-num.com/OAuth/Authorize

Метод HTTP протокола - GET

Формат параметров - application/x-www-form-urlencoded

Параметры запроса
Название Описание
response_type Значение параметра - "code"
client_id Идентификатор сервиса, полученный в системе E-NUM
redirect_uri URL, на который будет отправлен ответ запроса (необходимо указать в настройках сервиса в аккаунте E-NUM)
scope Набор запрашиваемых данных клиента из системы E-NUM, разделенный пробелом, например: email phone
state Используется для сопоставления запроса и ответа (сквозной параметр)

Пример
curl -i "https://auth.e-num.com/OAuth/Authorize?client_id=cd2068a8-cb18-4d24-bc85-dab0b3d3baf7&redirect_uri=https%3A%2F%2Fenumdemobank.e-num.com%2Fsignin-enum&scope=email%20phone&response_type=code&state=random-state"
HTTP/1.1 302 Found
Location: https://auth.e-num.com/Account/Login?ReturnUrl=%2FOAuth%2FAuthorize%3Fclient_id%3Dcd2068a8-cb18-4d24-bc85-dab0b3d3baf7%26redirect_uri%3Dhttps%253A%252F%252Fenumdemobank.e-num.com%252Fsignin-enum%26scope%3Demail%2520phone%26response_type%3Dcode%26state%3Drandom-state
                    


Получение кода авторизации

URL адрес — заданный параметр redirect_uri при вызове метода запроса кода авторизации

Метод HTTP протокола - GET

Формат параметров - application/x-www-form-urlencoded

Параметры ответа
Название Описание
code Одноразовый код авторизации, действителен в течение короткого промежутка времени
state Используется для сопоставления запроса и ответа (сквозной параметр)

Пример
GET https://enumdemobank.e-num.com/signin-enum?code=db8cea2e8bea4328b1ed&state=random-state
                    


Параметры ответа в случае ошибки
Название Описание
error Варианты: [invalid_request, unauthorized_client, access_denied, unsupported_response_type, invalid_scope, server_error, temporarily_unavailable]
error_description Описание ошибки (Необязательный параметер)
error_uri URL описания ошибки (Необязательный параметер)
state Используется для сопоставления запроса и ответа


Запрос токена доступа

URL адрес метода - https://auth.e-num.com/OAuth/Token

Метод HTTP протокола - POST

Формат параметров - application/x-www-form-urlencoded

Параметры запроса
Название Описание
client_id Идентификатор, полученный в системе E-NUM
client_secret Защищенный ключ, полученный в системе E-NUM
redirect_uri redirect_uri использованный при запросе кода авторизации
grant_type Значение параметра - "authorization_code"
code Одноразовый код авторизации, полученный из метода запроса кода авторизации

Пример
curl -i -d "client_id=cd2068a8-cb18-4d24-bc85-dab0b3d3baf7&client_secret=0e919552-1122-3344-5566-197f151bc349&redirect_uri=https%3A%2F%2Fenumdemobank.e-num.com%2Fsignin-enum&grant_type=authorization_code&code=db8cea2e8bea4328b1ed" "https://auth.e-num.com/OAuth/Token"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"bearer",
    "expires_in":900,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
}
                    


Получение токена доступа

Формат параметров - application/json

Параметры ответа
Название Описание
access_token Токен доступа
token_type Значение параметра - "bearer"
expires_in Время жизни токена, в секундах
refresh_token Токен, для повторного получения токена доступа


Получение идентификационных данных пользователя

Url адрес метода - https://auth.e-num.com/Api/Me

Метод HTTP протокола - GET

Заголовок HTTP запроса - Authorization: Bearer {токен доступа}

Пример
$ curl -i -H "Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA" "https://auth.e-num.com/Api/Me"
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"email":"test@example.com","phone":"00000000000"}
                    




Метод интеграции Soap

Метод интеграции Soap требует разового (первичного) перенаправления клиента на https://auth.e-num.com. Все последующие запросы не требуют перенаправления.


SOAP

Схема авторизации с использованием системы E-NUM методом Soap.

  • Пользователь стороннего сайта вводит свой email. Бекэнд сайта вызывает метод GetChallenge2 сервиса E-NUM (soap-интерфейс) для получения числа-вопроса.
  • Сайт отображает число-вопрос и просит пользователя ввести число-ответ. Для проверки ответа пользователя используется метод CheckUserAnswer.
  • При первой авторизации пользователь перенаправляется на сайт https://auth.e-num.com для получения разрешения пользователя на работу сайта с Е-NUM в связке с аккаунтом пользователя.

Для использования этой схемы владелец сайта должен зарегистрироватьcя на https://e-num.com/Account/Consumers.


Описание методов Soap API

Веб сервис http://service.e-num.com/Soap.asmx предоставляет базовые методы GetChallenge2 и CheckUserAnswer.


Метод GetChallenge2 (получение числа-вопроса)

Параметры запроса
Название Описание
consumerId Идентификатор сайта. Берется тут https://e-num.com/Account/Consumers, значение Client ID.
email Email пользователя
userIp IP-адрес пользователя
crc Код проверки параметров. Вычисляется хеш-функцией sha256(consumerSecret + email). Берется тут https://e-num.com/Account/Consumers, значение Client Secret. Результат хеш функции должен иметь строковой формат без дефисов и в нижнем регистре.
Параметры ответа
Название Описание
ErrorCode Код результата, описан ниже.
Challenge Число-вопрос
QrUrl URL QR-кода числа-вопроса
SessionId Идентификатор сессии, используется для автоподстановки числа-ответа
Описание ErrorCode
Код Описание
0 Успех
4 Пользователь с указанным email не обнаружен
5 Ошибка авторизации. Причиной может быть неверный consumerId или неправильно вычисленное значение параметра crc.
301 Пользователь еще не дал разрешение на использование ENUM-авторизации этому сайту. Смотрите ниже.
Другие коды Чтобы получить описание кода необходимо вызвать метод GetErrDesc.

При получении кода 301, сайт должен перенаправить пользователя по адресу https://auth.e-num.com/permission/ask?consumerId={consumerId}&email={email}&redirectUrl={redirectUrl}&nonce={nonce}

redirectUrl доменная часть должна совпадать с веб-сайтом проекта https://e-num.com/Account/Consumers
nonce опциональный сквозной параметр

Если пользователь дает разрешение, происходит его перенаправление на указанный redirectUrl с GET параметром allow=1. Если пользователь запрещает использование, происходит перенаправление с параметром deny=1. Ниже приведены другие GET параметры передаваемые к redirectUrl.

email Email пользователя
crc Код проверки параметров и признак того что этот запрос исходит из сервера авторизации E-NUM. Вычисляется хеш-функцией sha256(consumerSecret + email). Берется тут https://e-num.com/Account/Consumers, значение Client Secret. Результат хеш функции должен иметь строковой формат без дефисов и в нижнем регистре.


Метод CheckUserAnswer (проверка ответа)


Параметры запроса
Название Описание
consumerId Идентификатор сайта. Берется из страницы проекта https://e-num.com/Account/Consumers, значение Client ID.
email Email пользователя
userIp IP адрес пользователя
challenge Число-вопрос
response Число-ответ
addname Опциональное название сервиса, используется в логах
crc Код проверки параметров. Вычисляется по формуле sha256(consumerSecret + response). Тут consumerSecret берется из страницы проекта https://e-num.com/Account/Consumers, значение Client Secret. Результат хеш функции должен иметь строковой формат без дефисов и в нижнем регистре.
Параметр ответа
ErrorCode Код результата, описан выше, в описании метода GetChallenge2.


Автоподстановка числа-ответа

Число-ответ можно автоматически подставлять в форму ответа на сайте путем отправки из мобильного клиента E-NUM. Для этого необходимо добавить следующий javascript-код в страницу формы авторизации:

...
<form id="login" method="post">
    ...
    <input type="text" name="response" id="response" />
    ...
</form>
...
<script src="https://signalr2.enum.ru/js/jquery.min.js"></script>
<script src="https://signalr2.enum.ru/js/signalr.min.js"></script>
<script>
    $(function () {
        // сюда надо передавать параметр, полученный из метода GetChallenge2
        var sessionId = '<%= SessionId %>';
        var connection = new signalR.HubConnectionBuilder()
            .withUrl('https://signalr2.enum.ru/autoResponseHub?sessionId=' + sessionId, {
                skipNegotiation: true,
                transport: signalR.HttpTransportType.WebSockets
            })
            .build();
        connection.on('response', function (response) {
            if ($.trim(response) !== '') {
                $('input#response').focus();
                $('input#response').val(response);
                $('form#login').submit();
            }
        });
        connection.start();
    });
</script>

Демонстрация

На примере несуществующего банка демонстрируем возможность авторизации с использованием E-NUM методом OAuth2.

Перейти на рабочий пример

Исходный код примера

Вы можете реализовать свой OAuth2-клиент E-NUM (согласно описанию методов API выше), или воспользоваться готовыми клиентскими библиотеками под вашу платформу.

Библиотека для Microsoft ASP.NET + Owin.

Пример на PHP.


Пример интеграции авторизации E-NUM Soap-методом.