Подключение хранилищ атрибутов#

Типы хранилищ#

В качестве хранилищ атрибутов пользователей Blitz Identity Provider позволяет использовать:

  1. Внешнее (подключенное) хранилище. В качестве такового может выступать:

    • LDAP-хранилище – это может быть любой сервер, поддерживающий протокол LDAP (389 Directory Server, OpenLDAP, FreeIPA и другие), а также Microsoft Active Directory или Samba4;

    • иное хранилище, для подключения которого к Blitz Identity Provider необходимо разработать специальные REST-сервисы (см. Подключение к хранилищу по REST).

  2. Внутреннее хранилище. Все атрибуты пользователей хранятся в базе данных Blitz Identity Provider. В случае если в качестве СУБД используется Couchbase Server, то базу данных Blitz Identity Provider можно использовать для хранения небольшого числа учетных записей. В случае если в качестве СУБД используется PostgreSQL, то можно хранить любое число учетных записей.

Для корректной работы Blitz Identity Provider требуется настройка хотя бы одного хранилища и конфигурирование атрибутов (см. Конфигурирование доступных атрибутов). По умолчанию настроено внутреннее хранилище и добавлен ряд атрибутов.

Примечание

Каждая учетная запись пользователя хранится в каком-то одном определенном хранилище. Blitz Identity Provider допускает конфигурирование и подключение нескольких хранилищ, однако рекомендуется использовать одно основное хранилище для работы. Решение об использовании второго хранилища должно быть принято с учетом применяемой модели данных. Например, в подключенном корпоративном Active Directory могут храниться данные сотрудников организации, а в дополнительном LDAP-хранилище – данные специально зарегистрированных «внешних» пользователей (сотрудники партнерских организаций, фрилансеры и пр.).

Выбор и настройка используемого хранилища осуществляется после настройки атрибутов в разделе «Источники данных» в разделе «Хранилища атрибутов». По умолчанию настроено внутреннее хранилище. Для добавления внешнего хранилища следует нажать на кнопку «Добавить новое хранилище», после чего указать тип внешнего хранилища и настроить параметры взаимодействия с ним. Хранилища после создания создаются выключенными – их нужно включить с помощью тумблера в разделе «Хранилища атрибутов».

:size=60%

Допустимо удалить внутреннее хранилище, если его не планируется использовать. Для этого необходимо перейти в свойства соответствующего внешнего хранилища и нажать на кнопку «Удалить».

Использование нескольких хранилищ может решить задачу входа пользователей, хранящихся в разных LDAP-каталогах или в разных ветках одного каталога. Например, в результате объединения двух компаний можно подключить два каталога к Blitz Identity Provider и обеспечить вход пользователей, не прибегая к настройкам доверия или построению метакаталога.

:size=80%

Подключение хранилища по LDAP#

Если в качестве источника учетных записей пользователей используется LDAP хранилище, развернутое в организации, для его настройки необходимо воспользоваться разделом «Источники данных» консоли управления и выполнить следующие шаги:

  • добавить новое хранилище, указать следующие данные:

    • тип добавляемого хранилища – выбрать LDAP;

    • адрес хранилища;

    • порт;

    • отметить галочку «Использовать SSL», если должно использоваться защищенное соединение.

  • сконфигурировать LDAP-хранилище, настроив следующие параметры:

    • описание хранилища (опционально);

    • использует ли хранилище только для чтения данных или возможна запись в него;

    • необходимость использования SSL-соединения;

    • необходимость DNS-балансировки вызовов к LDAP-хранилищу – для этого нажать кнопку «DNS-балансировка» и задать параметры «Доменное имя», «Порт», «Использовать SSL», «Режим работы», «Время хранения в кэше, мс»;

      Примечание

      При DNS-балансировке Blitz Identity Provider запрашивает у DNS-сервера по заданному доменному имени LDAP-каталога все адреса подключения. Если в DNS прописано более одного адреса, то в зависимости от выбранного режима работы Blitz Identity Provider устанавливает подключение к первому доступному серверу (режим работы FAILOVER), к случайному серверу (режим работы RANDOM) или к каждому серверу по очереди (режим работы ROUND_ROBIN). Полученный от DNS список серверов хранится в кэше Blitz Identity Provider в течение времени, заданного в настройке «Время хранения в кэше, мс».

    • настройки пула соединений;

  • указать логин и пароль пользователя, от имени которого будет осуществляться работа с LDAP-хранилищем (у этого пользователя должны быть права на чтение и на запись данных), а также базовый DN – раздел каталога с учетными записями пользователей;

    Примечание

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

  • указать настройки поиска – глубину поиска и максимальное число возвращаемых учетных записей (это влияет на число пользователей, отображаемых в разделе «Пользователи» консоли управления).

../_images/ldap.jpg

Далее можно настроить правила сопоставления атрибутов и указать правила разбиения и правила преобразования значений атрибутов. Это позволяет:

  • дать атрибуту в системе другое название, не совпадающее с его именем в LDAP-каталоге. Например, если в LDAP-каталоге атрибут задан как sn, а в Blitz Identity Provider необходимо его использовать как family_name, то выберите атрибут family_name и укажите sn в качестве его названия в LDAP. Пример такой настройки приведен на рисунке ниже;

  • использовать специальные правила записи атрибутов в данный LDAP-каталог. Например, если вы хотите сохранять мобильный телефон в формате +7(999)1234567 в LDAP-каталог без скобок, то для записи задайте правило разбиения ^\+7\(([0-9]{3})\)([0-9]{7})$ и правило преобразования +7${1-}${2-}.

  • использовать специальные правила чтения атрибутов из данного LDAP-каталога. Например, если в LDAP-каталоге атрибут с номером мобильного телефона задан в формате +79991234567, а в Blitz Identity Provider используется формат +7(999)1234567, то для чтения из каталога можно использовать правило разбиения ^\+7([0-9]{3})([0-9]{7})$ и правило преобразования +7(${1-})${2-}.

../_images/attr_matching.png

Если хранение созданного ранее (см. Конфигурирование доступных атрибутов) атрибута в данном хранилище не предполагается, то можно просто удалить атрибут, используя кнопку удаления. В этом случае значение удаленного атрибута будет сохраняться при создании/редактировании учетной записи не в подключаемом внешнем хранилище, а в базе данных Blitz Identity Provider.

Если планируется использовать возможность блокировки учетной записи, то необходимо удалить атрибут, определенный в разделе «Источники данных» в качестве признака блокировки, из таблицы с правилами сопоставления атрибутов.

Если Blitz Identity Provider используется для регистрации пользователей, причем запись осуществляется в данный каталог, то необходимо указать параметры создания новых пользователей – DN родительского контейнера, внутри которого будут создаваться пользователи, и системные атрибуты, связанные со спецификой хранилища***.

Примечание

Например, objectclass, определяющий тип создаваемой учетной записи в LDAP. Для Microsoft Active Directory objectclass должен иметь формат Array of string и значение - top,person.

../_images/attrs_ldap.png

Подключение к хранилищу по REST#

Если в качестве источника учетных записей пользователей используется внешняя база данных (не LDAP-хранилище), то для подключения к ней требуется разработать коннектор. Коннектор обеспечивает чтение (или изменение) необходимых данных из базы данных и предоставляет данные в корректном формате в виде REST-сервисов для Blitz Identity Provider.

Для настройки взаимодействия с REST-сервисами необходимо выполнить следующие шаги:

  • добавить новое хранилище, указав тип добавляемого хранилища - REST;

  • указать описание хранилища (опционально);

  • указать, используется ли хранилище только для чтения данных или возможна запись в него;

  • указать максимальное количество записей, возвращаемых при поиске;

  • указать перечень доступных через REST-сервисы атрибутов;

  • указать URL следующих сервисов:

    • сервис поиска пользователей;

    • сервис получения данных пользователя;

    • сервис проверки логина и пароля;

    • сервис смены пароля пользователем;

    • сервис добавления нового пользователя;

    • сервис изменения данных пользователя;

    • сервис удаления пользователя.

Скриншот страницы с настройками подключения к хранилищу c использованием REST-сервисов представлен ниже.

:size=80%

В следующих подразделах описаны требования к разработке REST-сервисов, предоставляющих необходимый Blitz Identity Provider доступ к хранилищу учетных записей.

Сервис получения данных пользователя#

В ряде случаев Blitz Identity Provider запрашивает данные конкретного пользователя. Сервис получения данных пользователя должен обрабатывать запросы методом GET, в котором в URL указывается атрибут id – внутренний идентификатор пользователя в подключенной базе данных. При задании URL этого сервиса в консоли управления необходимо использовать строку подстановки для идентификатора пользователя – ${id}, например:

https://idstore.identityblitz.com/users/${id}

Если пользователь найден, то сервис должен отвечать 200 OK и возвращать данные пользователя в формате JSON в кодировке UTF-8. Если пользователь не найден: 400 Bad Request, код ошибки USER_NOT_FOUND в формате text/plain; charset=utf-8.

Пример запроса:

GET /users/ID123 HTTP/1.1
Host: idstore.identityblitz.com
Content-Type: application/json
Cache-Control: no-cache

Пример ответа, если пользователь найден:

HTTP/1.1 200 OK
Date: Mon, 18 Jul 2016 12:28:59 GMT
Content-Type: application/json; charset=utf-8

{
  "id": "ID123",
  "attrs": {
    "sub": "BIP123",
    "given_name": "Ivan",
    "family_name": "Ivanov",
    "email": "ivanov@test.org",
    "phone_number": "+79991234567"
  }
}

Ответ для случая, если пользователь не найден:

HTTP/1.1 400 Bad Request
Date: Mon, 18 Jul 2016 12:28:59 GMT
Content-Type: text/plain; charset=utf-8

USER_NOT_FOUND

Сервис проверки логина и пароля#

Сервис проверки логина и пароля должен обрабатывать запросы методом POST, в теле которых указаны следующие параметры (в формате application/x-www-form-urlencoded):

  • id – внутренний идентификатор пользователя в подключенной базе данных;

  • password – пароль.

В случае успеха сервис должен вернуть ответ 200 OK.

При невозможности провести аутентификацию сервис должен вернуть 400 Bad Request с одной из следующих ошибок:

  • INVALID_CREDENTIALS – неверный логин или пароль пользователя;

  • UNWILLING_TO_PERFORM – пользователь заблокирован;

  • INAPPROPRIATE_AUTHENTICATION — пользователь не может быть аутентифицирован по паролю;

  • PASSWORD_EXPIRED — пароль пользователя устарел.

Пример запроса:

POST /users/bind HTTP/1.1
Host: idstore.identityblitz.com
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

id=ivanov&password=12345678

Пример ответа (успешная проверка логина и пароля):

HTTP/1.1 200 OK
Date: Mon, 18 Jul 2016 12:38:53 GMT
Content-Type: application/json; charset=utf-8

Пример ответа (неверный логин и/или пароль):

HTTP/1.1 400 Bad Request
Date: Mon, 18 Jul 2016 12:38:53 GMT
Content-Type: text/plain; charset=utf-8

INVALID_CREDENTIALS

Сервис смены пароля пользователем#

Сервис смены пароля пользователем должен обрабатывать запросы методом POST, в теле которых указаны следующие параметры (в формате application/x-www-form-urlencoded):

  • id – идентификатор пользователя, полученный по результату операции проверки пароля пользователя;

  • old_password – старый пароль;

  • new_password – новый пароль.

В случае успеха сервис должен вернуть ответ 200 OK.

В случае ошибки сервис должен вернуть 400 Bad Request с одной из следующих ошибок:

  • INVALID_CREDENTIALS — пользователь с данным идентификатором и паролем не найден;

  • UNWILLING_TO_PERFORM — пользователь заблокирован;

  • CONSTRAINT_VIOLATION — новый пароль не соответствует политикам безопасности.

Остальные возвращаемые ошибки должны быть аналогичны операции по проверке логина и пароля.

Пример запроса:

POST /users/changePassword HTTP/1.1
Host: idstore.identityblitz.com
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

id=ivanov&old_password=12345678&new_password=0987654321

Пример ответа:

HTTP/1.1 400 Bad Request
Date: Mon, 18 Jul 2016 12:43:23 GMT
Content-Type: text/plain; charset=utf-8

CONSTRAINT_VIOLATION

Сервис добавления нового пользователя#

Сервис добавления нового пользователя должен обрабатывать запросы методом PUT, в теле которых указаны следующие параметры (в формате application/json):

  • password – пароль пользователя (опционально);

  • attrs – атрибуты пользователя.

В случае успеха сервис должен вернуть данные пользователя в формате JSON в кодировке UTF-8.

Если пароль не удовлетворяет политикам безопасности, сервис должен вернуть 400 Bad Request с ошибкой CONSTRAINT_VIOLATION.

Если такой пользователь уже существует, сервис должен вернуть 400 Bad Request с ошибкой USER_ALREADY_EXISTS и уточнением, что пользователь с данным идентификатором уже существует.

Пример запроса:

PUT /users HTTP/1.1
Host: idstore.identityblitz.com
Content-Type: application/json
Cache-Control: no-cache

{
    "password":"********",
    "attrs": {
            "sub": "ivanov@test.org",
            "email": "ivanov@test.org"
    }
}

Пример ответа (пользователь создан):

HTTP/1.1 200 OK
Date: Mon, 18 Jul 2016 12:28:53 GMT
Content-Type: application/json; charset=utf-8

{
    "id": "ID678",
    "attrs": {
        "sub": "ivanov@test.org",
        "email": "ivanov@test.org"
    }
}

Пример ответа (учетная запись уже зарегистрирована):

HTTP/1.1 400 Bad Request
Date: Mon, 18 Jul 2016 12:43:23 GMT
Content-Type: text/plain; charset=utf-8

USER_ALREADY_EXISTS:ivanov@test.org

Сервис изменения данных пользователя#

Сервис изменения данных пользователя должен обрабатывать запросы методом POST, в URL вызываемого сервиса указывается атрибут id – внутренний идентификатор пользователя в подключенной базе данных. При задании URL этого сервиса в консоли управления необходимо использовать строку подстановки для идентификатора пользователя – ${id}, например:

http://idstore.identityblitz.com/users/${id}

В теле запроса на изменение данных указаны следующие параметры (в формате application/json):

  • password – новое значение пароля пользователя (если пароль не передан, то он не должен измениться);

  • replaced – новые значения атрибутов пользователя, которые нужно заменить или добавить;

  • deleted – список названий удаляемых атрибутов.

В случае успеха сервис должен вернуть данные пользователя в формате JSON в кодировке UTF-8.

Если новый пароль не удовлетворяет политикам безопасности, сервис должен вернуть 400 Bad Request с ошибкой CONSTRAINT_VIOLATION.

Если такой пользователь не существует, сервис должен вернуть 400 Bad Request с ошибкой USER_NOT_FOUND.

Пример запроса:

POST /users/ID123 HTTP/1.1
Host: idstore.identityblitz.com
Content-Type: application/json
Cache-Control: no-cache

{
    "replaced": {
        "email": "ivanov@domain.org"
    },
    "deleted": ["family_name"],
    "password": "########"
}

Пример ответа:

HTTP/1.1 200 OK
Date: Mon, 18 Jul 2016 12:38:53 GMT
Content-Type: application/json; charset=utf-8

{
    "id": "ID123",
    "attrs": {
        "sub": "BIP123",
        "given_name": "Ivan",
        "email": "ivanov@domain.org"
    }
}

Сервис удаления пользователя#

Сервис удаления учетной записи пользователя должен обрабатывать запросы методом DELETE, в URL вызываемого сервиса указывается атрибут id – внутренний идентификатор пользователя в подключенной базе данных. При указании URL этого сервиса необходимо использовать строку подстановки для идентификатора пользователя – ${id}, например:

http://idstore.identityblitz.com/users/${id}

В случае успеха сервис должен вернуть статус 200 ОК.

Если пользователь не существует, сервис должен вернуть 400 Bad Request с ошибкой USER_NOT_FOUND.

Пример запроса:

DELETE /users/ID123 HTTP/1.1
Host: idstore.identityblitz.com
Content-Type: application/json
Cache-Control: no-cache

Пример ответа:

HTTP/1.1 200 OK
Date: Mon, 18 Jul 2016 12:28:53 GMT
Content-Type: application/json; charset=utf-8

Настройка внутреннего хранилища#

Если в качестве источника учетных записей пользователей используется база данных Blitz Identity Provider, то необходимо выполнить следующие шаги:

  • добавить новое хранилище, указав тип добавляемого хранилища – BUILT-IN;

  • указать идентификатор хранилища;

  • дать описание хранилища;

  • определить, используется ли хранилище только для чтения или нет;

  • указать максимальное число возвращаемых учетных записей при поиске.

:size=80%

Примечание

В случае если в качестве СУБД используется PostgreSQL, то можно хранить любое число учетных записей. В случае если в качестве СУБД используется Couchbase Server, то внутреннее хранилище можно использовать для хранения небольшого числа учетных записей.