Создание и настройка локальных пользователей и групп Keycloak

В данном разделе описан процесс создания и настройки локальных пользователей Keycloak для авторизации в веб-интерфейсе Business Studio. Эту информацию можно использовать при отсутствии собственной группы каталогов.

Примечание. Рекомендуется объединять пользователей в группы (см. Создание и настройка Keycloak группы) и настраивать права в системе Business Studio через группы.

Данные из Keycloak загружаются в Business Studio в справочник "Пользователи". Соответствие между атрибутами Keycloak и параметрами Business Studio устанавливается заранее (до первой авторизации нового пользователя) в файле конфигурации appsettings.json в разделе "OpenId". Предусмотрены следующие настройки:

• Имя и идентификатор пользователя:
  • в строке "UserNameClaim" указывается атрибут Keycloak, который необходимо сопоставить с параметром "Название" справочника "Пользователи";
  • в строке "UserIdClaim" указывается атрибут Keycloak, который необходимо сопоставить с параметром "UserID" справочника "Пользователи".

Идентификатор пользователя ("UserID") - ключевой уникальный параметр пользователя (или группы) в системе Business Studio.

• Настройки для управления группами пользователей:
  • в строке "UserRolesClaim" указывается название атрибута в токене, где хранятся группы пользователя (подробнее см. Настройка клиентских разрешений);
  • в строке "UserRolesSeparator" задается символ‑разделитель, который разделяет несколько групп, указанных в одном поле.
• Дополнительные настраиваемые параметры. Указываются в подразделе "CustomClaims" в формате:

"CustomClaims": [
  {
    "Claim": "атрибут",
    "Property": "параметр"
  }
]

где атрибут - название пользовательского атрибута, передаваемого в токене, а параметр - guid или системное название параметра справочника "Пользователи".

Для создания Keycloak-пользователя необходим доступ в административную консоль Keycloak. Для создания пользователя нужно:

1. Зайти в административную консоль Keycloak.
2. Выбрать изолированную область (realm) в выпадающем меню в левом верхнем углу интерфейса (не master, при необходимости нужно создать новую кнопкой Create realm).
3. Перейти в Users, нажать Add user.
4. Заполнить поля:
   • Username – обязательный для заполнения атрибут, по умолчанию используется системой Keycloak для аутентификации. При необходимости Keycloak позволяет настроить аутентификацию по любому атрибуту пользователя.
   • атрибуты, соответствующие настройкам "UserNameClaim" и "UserIdClaim" (см. Настройка передачи атрибутов из Keycloak в Business Studio).
5. Нажать Create.
6. Перейти на вкладку Credentials, нажать Set password, установить флажок Temporary, если нужно поменять пароль при первом входе, нажать Save.

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

1. Выбрать изолированную область (realm) в левом верхнем углу интерфейса административной консоли Keycloak.
2. Перейти в раздел Groups, нажать Create group, ввести имя группы и нажать Create.

1. Открыть свойства группы, нажав на нее в разделе Groups.
2. Перейти на вкладку Members, нажать Add member.
3. Отметить требуемых пользователей (см. Создание Keycloak-пользователя) галочками, нажать Add.

На этом этапе необходимо настроить Client scope, а также настроить файл конфигурации appsettings.json.

Client scope — механизм в Keycloak для централизованного управления набором ролей, атрибутов и мапперов, которые могут быть назначены клиентам (в данном случае веб-сервер Business Studio).

Для настройки Client scope нужно:

1. Перейти в раздел Client scopes, нажать Create client scope.
2. Заполнить базовые параметры:
   • Name,
   • Protocol (выбрать OpenID Connect),
   • Type (выбрать Optional).
3. Нажать Save.
4. Открыть свойства созданного Client scope, нажав на него в разделе Client scopes.
5. Перейти на вкладку Mappers, нажать Add mapper – By configuration или Configure a new mapper.
6. Выбрать Group Membership.
7. Заполнить параметры: Name, Token Claim Name (имя поля в токене).
8. Включить следующие опции:
   • Add to ID token,
   • Add to access token,
   • Add to userinfo,
   • Add to token introspection.
9. Нажать Save.
10. В файле конфигурации appsettings.json в разделе "OpenId" внести следующие изменения:
    • В строке "UserRolesClaim", прописать значение Token Claim Name.
    • В подразделе "Scopes" добавить новую строку, содержащую имя (Name) созданного Client scope.
11. В административной консоли Keycloak перейти в раздел Clients, открыть свойства клиентского приложения (Business Studio).
12. Перейти на вкладку Client Scopes, нажать Add client scope.
13. Выбрать созданный Client scope, нажать Add, выбрав тип привязки:
    • Default, для автоматического применения ко всем запросам;
    • Optional, если требуется явное указание в параметре scope при авторизации.
14. Настроить доступ для группы к базе данных аналогично тому, как описано выше для Keycloak-пользователя, при этом в качестве названия и параметра Идентификатор пользователя ("UserID") для группы следует указывать название группы, заданное на этапе Создание группы.

Пользователь автоматически создается в системе Business Studio в справочнике "Пользователи" при первой авторизации Keycloak-пользователя в веб-интерфейсе. При включенной опции Автоматическая раздача прав автоматически выдается группа вертикальных прав "Права администратора" (см. Автоматическая раздача прав).

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

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

1. Отключить Автоматическую раздачу прав.
2. Создать пользователя в справочнике "Пользователи", заполнив поля в окне свойств:
   • "Название":
     Для отдельного Keycloak-пользователя это будет значение атрибута, соответствующего настройке "UserNameClaim".
     Для группы это будет название (Name) группы.
   • "Логин" – Идентификатор пользователя ("UserID"):
     Для отдельного Keycloak-пользователя это будет значение атрибута, соответствующего настройке "UserIdClaim".
     Для группы это будет название (Name) группы.
   • "UserID" – заполняется автоматически при заполнении поля "Логин".
3. Выдать пользователю категорию вертикальных прав (см. Права пользователя).
4. Настроить для пользователя горизонтальные права (см. Горизонтальные права).

1. Открыть окно выбора баз данных Business Studio.
2. Вызвать контекстное меню от базы данных и выбрать пункт Управление ветками.
3. Выбрать нужную ветку в дереве в левой части окна Управление ветками.
4. В нижнем правом углу окна Управление ветками нажать кнопку Добавить.
5. Выбрать вариант Пользователь Справочника.
6. В поле Пользователь ввести Идентификатор пользователя ("UserID"):Для отдельного Keycloak-пользователя это будет значение атрибута, соответствующего настройке "UserIdClaim".Для группы это будет название (Name) группы.
7. Убедиться, что в списке Права доступа появился добавленный пользователь и установить для него Права пользователя ("Полный доступ" или "Запрет изменений").
8. Сохранить.

Для настройки лицензии нужно в файле конфигурации appsettings.json прописать тип лицензии по принципу от частного к общему, то есть от конкретных пользователей до групп. Прописывать нужно в разделе "UsersEditions" в формате:

{
  "UserId": "ID", 
  "Edition": "название_лицензии"
},

где ID - Идентификатор пользователя ("UserID"), название_лицензии – Ultimate, Professional и т.д.