Identify Wiki

Identify API предназначен для интеграции функциональной возможности двухфакторного подтверждения операций на пользовательский портал.

Identify SDK предназначен для интеграции функциональной возможности двухфакторного подтверждения в мобильные приложения iOS и Android.

В результате интеграции при выполнении действий, требующих подтверждения, на портале, в мобильное устройство пользователя поступает уведомление, требующее подтверждение от пользователя.

  1. Описание использования библиотек для Android (Java) и iOS (Swift) можно найти здесь.
  2. Описание использования С# методов для интегрированного портала можно найти здесь.
  3. Полное описание методов и классов библиотеки для Android (Java) можно найти здесь.
  4. Полное описание методов и классов библиотеки для iOS (Swift) можно найти здесь.

Требования

Android

  • minSdkVersion 14

iOS

  • iOS 8.0+
  • Xcode 8.0+
  • Swift 3.2+

Использование

Мобильные библиотеки для Android/iOS

Методы

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

  1. Регистрация аккаунта в Idenitfy.
  2. Авторизация в Identify
  3. Вход в приложение по пин-коду.
  4. Изменение пин-кода при необходимости.
  5. Добавление портала к аккаунту Identify.
  6. Просмотр списка доступных порталов.
  7. Получение "активной" операции при инициации действия на портале или авторизации на сайте.
  8. Обработка "активной" операции – подтверждение или отклонение ее выполнения.
  9. Получение архива операций – списка подтвержденных/отклоненных/просроченных операций и подробную информацию о каждой операции.
  10. Удаление привязки к порталу из аккаунта Identify.
  11. Выход из аккаунта Identify (окончание сессии).

Регистрация аккаунта в Idenitfy

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

При успешном выполнении регистрации, пользователь будет добавлен в систему и в дальнем может быть авторизован с заданными логином/паролем.

Регистрация может оказаться неудачной, если заданный логин уже существует в системе.

Android

try {
    boolean success = identifySdk.addAccount("email@mail.ru", "ultra-hard-password");
    // регистрация прошла успешно
} catch (RequestException e) {
    // произошла ошибка, получим ее локализованное описание
    String responseCodeDescription = e.getResponseCode().getDescription();
}

Подробнее:

iOS

identifySdk.addAccount(login: "email@mail.ru", password: "ultra-hard-password") { response in
    if response == .success {
        // регистрация прошла успешно
    } else {
        // произошла ошибка, получим ее локализованное описание
        let responseCodeDescription = response.description
    }
}

Подробнее:

Авторизация в Identify

Для дальнейшей работы в системе необходимо авторизовать пользователя.

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

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

Авторизация может оказаться неудачной, если логин/пароль неверен.

Android

try {
    // создаем пароль для хранилища ключей (пин-код)
    ISecureString pin = new SecureString("1485".toCharArray());

    // авторизация
    String token = identifySdk.authorize("email@mail.ru", "ultra-hard-password", pin);
    // регистрация прошла успешно - token теперь содержит авторизационный токен
} catch (RequestException e) {
    // произошла ошибка, получим ее локализованное описание
    String responseCodeDescription = e.getResponseCode().getDescription();
}

Подробнее

iOS

// создаем пароль для хранилища ключей (пин-код)
let pin = "1485"

// авторизация
identifySdk.authorize(login: "email@mail.ru", password: "ultra-hard-password", pinCode: pin) { token, response  in
    if response == .success {
        // регистрация прошла успешно - token теперь содержит авторизационный токен           
    } else {
        // произошла ошибка, получим ее локализованное описание
        let responseCodeDescription = response.description               
    }
}

Подробнее:

Вход в приложение по пин-коду

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

Android

ISecureString pin = new SecureString("1485".toCharArray());
if (identifySdk.tryToLogin(pin)) {
    // верный пин-код      
} else {
    // неверный пин-код
}

Подробнее

iOS

if identifySdk.tryToLogin(password: "1485") {
    // верный пин-код 
} else {
    // неверный пин-код
}

Подробнее:

Изменение пин-кода при необходимости

Есть возможность изменить старый пин-код на новый.

Android

ISecureString oldPin = new SecureString("1485".toCharArray());
ISecureString newPin = new SecureString("5814".toCharArray());
if (identifySdk.changeKeyStorePassword(oldPin, newPin)) {
    // успешное изменение пин-кода            
} else {
    // неудачное изменение пин-кода            
}

Подробнее

iOS

identifySdk.changeKeyStorePassword(newPassword: "5814")

Подробнее:

Добавление портала к аккаунту Identify

Для получения операций к аккаунту пользователя необходимо добавить портал.

Для добавления портала необходимо иметь активационный код, выданный этим порталом и авторизационный токен. Процедура получения активационного кода описывается в разделе "Методы портала" - "Активация пользователя портала в системе Identify"

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

  • указаны неверные логин/пароль в системе Identify;
  • истек срок действия активационного кода;
  • неверный активационный код.

При успешном добавлении портала, сервер вернет данные о нем.

Android

try {
    Portal portal = identifySdk.sendActivationCode(authorizationToken, "RK8DRF3", pin);
    // получены данные о добавленном портале
} catch (RequestException e) {
    // произошла ошибка, получим ее локализованное описание
    String responseCodeDescription = e.getResponseCode().getDescription();
}

Подробнее

iOS

identifySdk.sendActivationCode(authorizationToken: authorizationToken, activationCode: "RK8DRF3") { portal, response in
    if response == .success {
        // добавление портала прошло успешно - теперь portal содержит данные о портале
    } else {
        // произошла ошибка, получим ее локализованное описание
        let responseCodeDescription = response.description      
    }
}

Подробнее

Просмотр списка доступных порталов

Списки когда-либо добавленных порталов (даже удаленных, у них будет соответствующий статус) можно получить следующим образом, указав при этом авторизационный токен:

Android

try {
    List<Portal> portals = identifySdk.getPortals(authorizationToken, pin);
    // получены данные о порталах
} catch (RequestException e) {
    // произошла ошибка, получим ее локализованное описание
    String responseCodeDescription = e.getResponseCode().getDescription();
}

Подробнее

iOS

// Получение списка порталов
identifySdk.getPortals(authorizationToken: token) {
    portals, response in

    if response == .success {
        // получение списка порталов успешно - теперь portals содержит данные о порталах
    } else {
        // произошла ошибка, получим ее локализованное описание
        let responseCodeDescription = response.description
    }
}

Подробнее

Получение "активной" операции при инициации действия на портале или авторизации на сайте

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

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

  1. Авторизационный токен.
  2. (Опционально) Id операции, начиная с которой (не включая ее) необходимо получить новые операции, пропуская все ранее созданные до нее. Полезно для проверки и получения новых активных операций, когда предварительно был загружен более старый список операций.
  3. Максимальное количество операций допустимое в ответе на запрос.

В результате успешного запроса будет получен список активных операций:

Android

try {
    GetActiveOperationsResponse getActiveOperationsResponse = identifySdk.getActiveOperations(authorizationToken, operationId, count, pin);

    // получены данные о количестве доставленных операций
    int deliveredCount = getActiveOperationsResponse.getDeliveredCount();
    // получены данные об общем количестве операций
    int overallCount = getActiveOperationsResponse.getOverallCount();
    // получен список операций
    List<Operation> operations = getActiveOperationsResponse.getOperations();
} catch (RequestException e) {
    // произошла ошибка, получим ее локализованное описание
    String responseCodeDescription = e.getResponseCode().getDescription();
}

Подробнее

iOS

identifySdk.getActiveOperations(authorizationToken: token, operationId: operationId, maxCount: activeOperationsLoadCount) {
    getActiveOperationsResponse, response in

    if response == .success {
        // получены данные о количестве доставленных операций
        let deliveredCount = activeOperationsResponse.deliveredCount
        // получены данные об общем количестве операций
        let overallCount = activeOperationsResponse.overallCount
        // получен список операций
        let operations = activeOperationsResponse.operations
    } else {
        // произошла ошибка, получим ее локализованное описание
        let responseCodeDescription = response.description
    }
}

Подробнее

Обработка "активной" операции – подтверждение или отклонение ее выполнения

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

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

Подтверждение/отклонение может оказаться неудачным, если:

  • операции не существует;
  • срок действия операции истек;
  • операция уже была подтверждена/отклонена.

Android

try {
    boolean success = identifySdk.respondOperation(authorizationToken, operationId, OperationConfirmationType.ACCEPT, pin);
    // операция успешна подтверждена/отклонена
} catch (RequestException e) {
    // произошла ошибка, получим ее локализованное описание
    String responseCodeDescription = e.getResponseCode().getDescription();
}

Подробнее

iOS

identifySdk.respondOperation(authorizationToken: authorizationToken, operationId: operationId, operationConfirmationType: .Accept) {
    response in
    if response == .success {
        // операция успешна подтверждена/отклонена     
    } else {
        // произошла ошибка, получим ее локализованное описание
        let responseCodeDescription = response.description
    }
}

Подробнее

Получение архива операций – списка подтвержденных/отклоненных/просроченных операций и подробную информацию о каждой операции

Диапазон архива операций - всех созданных операций, которые были подтверждены/отклонены или время их действия истекло - можно контролировать с помощью двух параметров - даты начала и даты окончания получения всех операций. Если не указывать дату начала получения всех операций, то в ответе вернутся все операции до определенного времени указанного в дате окончания. Если не указывать дату окончания получения всех операций, то в ответе вернутся все операции полученных после какой-то отметки времени. Один из параметров времени обязательно должен быть указан для успешного получения архива.

Список параметров необходимых для получения архива:

  1. Авторизационный токен.
  2. (Опционально) Дата начала получения всех операций (миллисекунды с 1970 г.).
  3. (Опционально) Дата окончания получения всех операций (миллисекунды с 1970 г.).
  4. Тип сортировки архива (по времени/типу операции/названию операции).
  5. Сколько операций пропустить в данном промежутке времени и не возвращать в ответе.
  6. Порядок в котором возвращаются операции (убывания или возрастания).

Android

try {
    GetArchivedOperationsResponse getArchivedOperationsResponse = identifySdk.getArchiveOperations(authorizationToken, null, System.currentTimeMillis(), 0, 0, maxCount, true, pin);

    // получены данные о количестве доставленных операций
    int deliveredCount = getArchivedOperationsResponse.getDeliveredCount();
    // получены данные об общем количестве операций
    int overallCount = getArchivedOperationsResponse.getOverallCount();
    // получен список операций
    List<Operation> operations = getArchivedOperationsResponse.getOperations();
} catch (RequestException e) {
    // произошла ошибка, получим ее локализованное описание
    String responseCodeDescription = e.getResponseCode().getDescription();
}

Подробнее

iOS

identifySdk.getArchiveOperations(authorizationToken: authorizationToken, endDate: Int64((Date().timeIntervalSince1970 * 1000.0).rounded()), sort: .byDate, skip: 0, count: maxCount, ascending: true) {
    getArchivedOperationsResponse, response in

    if response == .success {
        // получены данные о количестве доставленных операций
        let deliveredCount = getArchivedOperationsResponse.deliveredCount
        // получены данные об общем количестве операций
        let overallCount = getArchivedOperationsResponse.overallCount
        // получен список операций
        let operations = getArchivedOperationsResponse.operations
    } else {
        // произошла ошибка, получим ее локализованное описание
        let responseCodeDescription = response.description
    }
}

Подробнее

Удаление привязки к порталу из аккаунта Identify

Удаление привязки портала из аккаунта приведет к тому, что аккаунт больше не сможет получать и подтверждать операции с этого портала.

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

Android

try {
    boolean success = identifySdk.sendDeletePortalRequest(authorizationToken, portalId, pin);
    // привязка к порталу удалена
} catch (RequestException e) {
    // произошла ошибка, получим ее локализованное описание
    String responseCodeDescription = e.getResponseCode().getDescription();
}

Подробнее

iOS

identifySdk.sendDeletePortalRequest(authorizationToken: authorizationToken, portalId: id) {
    response in
    if response == .success {
        // привязка к порталу удалена
    } else {
        // произошла ошибка, получим ее локализованное описание
        let responseCodeDescription = response.description
    }
}

Подробнее

Выход из аккаунта Identify (окончание сессии)

Завершение сессии пользователя.

После успешного завершения сессии авторизационный токен становится не валиден, также удаляется хранилище ключей.

Для начала работы с аккаунтом пользователя необходимо снова авторизоваться в Identify.

Android

try {
    boolean success = identifySdk.terminateSession(authorizationToken, pin);
    // сессия успешно завершена
} catch (RequestException e) {
    // произошла ошибка, получим ее локализованное описание
    String responseCodeDescription = e.getResponseCode().getDescription();
}

Подробнее

iOS

identifySdk.terminateSession(authorizationToken: authorizationToken) {
    response in
    if response == .success {
        // сессия успешно завершена
    } else {
        // произошла ошибка, получим ее локализованное описание
        let responseCodeDescription = response.description
    }
}

Подробнее

С# библиотека

Для интеграции портала с Identify, необходимо:

  1. Зарегистрировать портал в системе.
  2. Реализовать работу с методами интегрированного портала.

Для регистрации портала в системе необходимо предоставить:

  1. название;
  2. логотип 96 х 96;
  3. если портал должен работать на собственном лэйбле клиента, то информацию о лэйбле для связывания его с данным порталом - его название и описание.

Для портала создается RSA сертификат, содержащий ключи:

  1. публичный - используется сервером для шифрования данных, которые отправляются порталу, а также для проверки подписи данных, приходящих от портала;
  2. приватный - с его помощью расшифровываются данные от сервера, зашифрованные публичным ключом портала, а также подписываются данные, отправляемые порталом.

Идентификация пользователя в системе производится по email или номеру телефона. В приведенных ниже примерах описывается вариант использования email.

Методы

  1. Активация пользователя портала в системе Identify.
  2. Проверка статуса активации.
  3. Осуществление пользователем операции на портале.
  4. Проверка статуса операции.

Общая схема использования Identify

Для выполнения каждого метода API необходимо выполнить следующую последовательность действий:

  1. Сформировать параметры запроса соответствующего метода.
  2. Выполнить сам запрос с помощью метода GeneralHelper.ExecuteQueryGetEnvelope(String url, object data);, который вернет SignedCms для расшифровки и десериализации.
  3. Расшифровать и десериализовать ответ сервера с помощью метода GeneralHelper.DecrpyptDeserialize(SignedCms envelope, out T obj).
  4. В ответном сообщении сервера с кодом 200, т.е. когда запрос был успешно распознан и каким-то образом обработан, всегда содержится код ответа - Response, который сообщает о том, каким образом сервер обработал запрос (успешно, и каким именно образом, или же произошла ошибка, и какая именно ошибка).

Активация пользователя портала в системе Identify

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

Для получения активационного кода необходимо выполнить следующее.

Сформировать параметры запроса, указав электронную почту пользователя.

var userData = new UserData {Email = user.Email};

Выполнить запрос на сервер и получить его зашифрованный ответ.

var envelope = GeneralHelper.ExecuteQueryGetEnvelope(GeneralHelper.GetActivationCode, userData);

Если ответ не пустой, то необходимо расшифровать полученные данные и посмотреть Response, чтобы понять как именно обработался запрос.

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

if (envelope != null)
{   
    ActivationCodeResponse activationCodeResponse;
    if (GeneralHelper.DecrpyptDeserialize(envelope, out activationCodeResponse)) 
    {
        if (activationCodeResponse.Response < ResponseCode.Failure)
        {
            // успешный запрос, показываем пользователю активационный код
            show(activationCodeResponse.ActivationCode)
        }
        else
        {
            // запрос не удался, Response укажет в чем ошибка
        }
    } else 
    {
        // произошла ошибка десериализации
    }
}
else 
{
    // возникла локальная ошибка при формировании запроса к серверу
} 

Проверка статуса активации

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

Сам статус может иметь следующие значения:

  1. Пользователь с таким email не существует в системе.
  2. У пользователя нет аккаунта на лейбле Identify (при активации расширения).
  3. У пользователя нет аккаунта на лейбле.
  4. Аккаунт пользователя с лейблом Identify активирован.
  5. Аккаунт пользователя с лейблом Identify ожидает активации.
  6. Аккаунт пользователя с лейблом Identify не активирован (активационный код либо не был запрошен, либо запрошенный код истек).

Для проверки статуса активации нужно сформировать параметры запроса, указав электронную почту пользователя.

var checkActivationParams = new CheckActivationParams { Email = email }

Выполнить запрос на сервер и получить его зашифрованный ответ.

var envelope = GeneralHelper.ExecuteQueryGetEnvelope(GeneralHelper.CheckActivation, checkActivationParams);

Если ответ не пустой, то необходимо расшифровать полученные данные и посмотреть Response, чтобы понять как именно обработался запрос.

Если ответ успешный, то в Response также будет содержаться статус активации пользователя.

if (envelope != null)
{
    CheckActivationResponse checkActivationResponse;
    if (GeneralHelper.DecrpyptDeserialize(envelope, out checkActivationResponse)) 
    {
        if (checkActivationResponse.Response == ResponseCode.Success)
        {
            // успешный запрос, смотрим статус активации
            var result = checkActivationResponse.Result;
        }
        else 
        {
            // запрос не удался, Response укажет в чем ошибка
        }
    } 
    else 
    {
        //произошла ошибка десериализации
    }
}
else 
{
    // возникла локальная ошибка при формировании запроса к серверу
}

Осуществление пользователем операции на портале

Система Identify используется для подтверждения операций, проводимых пользователем на портале, через приложение на другом устройстве.

В системе заложены следующие типы операций:

  1. Общая операция.
  2. Удаление портала.
  3. Авторизация.
  4. Подпись документа.

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

Тип “Удаление портала” используется для разрыва связи в системе между пользователем и порталом. В этом случае пользователь больше не сможет подтверждать операции на данном портале через систему, а для возобновления функции ему придется заново регистрироваться в системе и запрашивать активационный код.

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

Сформировать параметр запроса со следующими данными:

  1. Электронная почта пользователя.
  2. Тип операции из представленных выше.
  3. Время, дающееся пользователю на подтверждение операции в секундах (максимум 232-1, т.е. максимальное значение типа Int32).
  4. Важность операции (в формате True/False).
  5. Имя операции.
  6. Браузер, через который проводится операция.
  7. Операционная система устройства, с которого проводится операция.
  8. IP адрес устройства, с которого проводится операция.
  9. Описание операции.
  10. Данные об операции.

Формат поля данных (OperationData) задается разработчиком. Он должен быть согласован с мобильным приложением, чтобы отправленная порталом информация в этом поле правильным образом распознавалась на стороне приложения. Передавать в это поле при создании операции необходимо строковый тип, который будет сохраняться в таком виде на сервере, и откуда впоследствии эта информация будет запрошена приложением.

var operationParams = new CreateOperationParams
{
    Email = "email@mail.ru",
    Type = OperationType.Common,
    Seconds = 5 * 60,
    IsImportant = false,
    OperationParams = new OperationParams
    {
        Name = "Название",
        Browser = "Chrome",
        OperatingSystem = "Windows",
        IpAddress = "192.168.0.1",
        Description = "Описание",
        OperationData = null
    }
};

Выполнить запрос на сервер и получить его зашифрованный ответ.

var envelope = GeneralHelper.ExecuteQueryGetEnvelope(GeneralHelper.CreateOperation, operationParams);

Если ответ не пустой, то необходимо расшифровать полученные данные и посмотреть Response, чтобы понять как именно обработался запрос.

Если ответ успешный, то в Response также будет содержаться, присвоенный сервером, id операции, по которому можно проверять статус данной операции.

if (envelope != null)
{
    CreateOperationResponse response;
    if (GeneralHelper.DecrpyptDeserialize(envelope, out response)) 
    {
        if (response.Response == ResponseCode.Success)
        {
            // успешный запрос, смотрим присвоенный id операции
            var operationId = response.OperationId;
        }
        else 
        {
            // запрос не удался, Response укажет в чем ошибка
        }
    } 
    else 
    {
        //произошла ошибка десериализации
    }
}
else 
{
    // возникла локальная ошибка при формировании запроса к серверу
}

Проверка статуса операции

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

Статусы операций:

  1. Активная (Active) - ожидает подтверждения или отмены.
  2. Успешно завершена (CompletedConfirmed).
  3. Отменена пользователем (CompletedCancelled).
  4. Отменена порталом (CancelledByPortal).

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

var checkOperationParams = new CheckOperationParams { OperationId = operationId, Email = email };

Выполнить запрос на сервер и получить его зашифрованный ответ.

var envelope = GeneralHelper.ExecuteQueryGetEnvelope(GeneralHelper.CheckOperation, checkOperationParams);

Если ответ не пустой, то необходимо расшифровать полученные данные и посмотреть Response, чтобы понять как именно обработался запрос.

Если ответ успешный, то в Response также будет содержаться статус запрошенной операции.

if (envelope != null)
{
    CheckOperationResponse operationResponse;
    if (GeneralHelper.DecrpyptDeserialize(envelope, out operationResponse)) 
    { 
        if (operationResponse.Response == ResponseCode.Success) 
        {
            // успешный запрос, смотрим статус операции
            var status = operationResponse.Status;
        } else 
        {
            // запрос не удался, Response укажет в чем ошибка
        }
    } 
    else 
    {
        // произошла ошибка десериализации
    }
} 
else 
{
    // возникла локальная ошибка при формировании запроса к серверу
}