Перейти к основному содержимому

Интеграция с Keycloak

Настройка Keycloak​

  • Настроить авторизацию в YuChat через Keycloak

    • Импортировать конфигурацию клиента для возможности авторизации с использованием KC.

      Конфигурация: yuchat_web.json

      • На вкладке "General settings" → "Valid redirect URIs", "General settings" → "Valid post logout redirect URIs" https://yuchat.mycompany.com/*

        • заменить на эндпоинт вашего сервера YuChat

    • Импортировать конфигурацию для возможности авторизации в консоли администратора с использованием KC.

      Конфигурация: yuchat-dashboard.json

      • На вкладке "General settings" → "Valid redirect URIs", "General settings" → "Valid post logout redirect URIs" https://admin.yuchat.mycompany.com/*

        • заменить на эндпоинт вашего сервера YuChat

    • Импортировать конфигурацию сервера для доступа backend YuChat в Keycloak.

      Конфигурация: yuchat.json

      • На вкладке "Credentials":

        • В разделе "Client Authenticator" установить значение "Client Id and Secret"
        • В разделе "Client Secret" сгенерировать секрет и скопировать в конфигурацию backend YuChat (параметр "keycloak.clientSecret")

      • На вкладке "Service accounts roles":

        • добавить роли "manage-events" и "manage-users"

    • Добавить ключ RSA для шифрования токенов пользователя

      • Realm settings → Keys
        • Скопировать Kid ключа RS256 (далее будет использоваться для параметра keycloak.sigKeyKid конфигурации сервера)

  • Настроить ttl для выдаваемых токенов

    • Realm settings → Sessions → SSO Session Settings → SSO Session Idle → 5 days
    • Realm settings → Sessions → SSO Session Settings → SSO Session Max → 10 days
    • Realm settings → Tokens → Access tokens → Access Token Lifespan → 15 min
подсказка

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

Настройка синхронизации с каталогом пользователей посредством протокола LDAP​

Миграция пользователей из LDAP в Keycloak позволяет администратору управлять пользовательскими сессиями, настраивать миграцию пользователей в рабочие пространства а также отдельно от LDAP блокировать пользоватей (закрыть возможность доступа в YuChat)

примечание

Для осуществления корректной миграции пользователей, необходимо чтобы у каждого пользователя присутствовал email адрес. В большинстве случаев имя аттрибута в LDAP - mail. Пользователи без email адреса не смогут попасть в YuChat.

  • Раздел "User federation" → "Add new provider" → "LDAP"
  • В разделе "Connection and authentication settings" настроить параметры подключения по протоколу ldap к вашему каталогу
  • В разделе "LDAP searching and updating" → "User DN" указать OU должен быть смигрирован в Keycloak
  • В раделе "Advanced settings" → "Trust Email" установить значение в "On"
  • На вкладке "Mappers" добавить маппинги для атрибутов пользователей (при необходимости)
    • department = Департамент в YuChat
    • position = Должность в YuChat
    • phone = Номер телефона в YuChat
    • displayName = Имя пользователя в YuChat
warning

После настройки синхронизации необходимо убедиться что все пользователи корректно добавляются в Keycloak, это можно проверить запустив принудительную синхронизацию Actions -> Sync All Users

В случае если ADFS существуют пользователи без email адреса, необходимо отфильтровать таких пользователей путем задания фильтра в поле User LDAP filter :

(&(objectClass=user)
  (objectCategory=person)
  (mail=*)
)

Перед изменением User LDAP filter или других параметров области синхронизации (например User DN) необходимо учитывать последствия. Пользователи, которые перестанут попадать под фильтр LDAP User Federation, могут быть автоматически удалены из Keycloak при следующей синхронизации. Так как YuChat синхронизирует пользователей из Keycloak, такие пользователи будут удалены и из YuChat.

Если в системе используется вход через ADFS, не включайте transparent/browser SSO flow до тех пор, пока все пользователи, которым нужен SSO, не будут смигрированы в Keycloak. Порядок включения такого сценария описан в разделе Настройка SSO через ADFS.

Настройка backend​

  • Конфигурационные параметры для настройки подключения клиента к keycloak


      yuchat:
          client:
              config:
                  supportedAuthTypes: "email,keycloak" #Добавить keycloak чтобы клиенты   понимали что авторизация через keycloak доступна
                  keycloakUrl: "https://auth.yuchat.company.com" #Эндпоинт keycloak для доступа клиентов (в т.ч. снаружи)
                  keycloakRealm: "master" #Реалм keycloak с пользователями и конфигурацией
                  keycloakClientId: "yuchat_web" #ClientId настроенныый ранее

  • Конфигурационные параметры для настройки подключения сервера к keycloak

    keycloak:
        enabled: true #Вкл/вкл интеграция с keycloak
        serverUrl: https://auth.yuchat.company.com #Эндпоинт для доступа в keycloak с сервера
        realm: master #Реалм keycloak с пользователями и конфигурацией
        clientId: yuchat #ClientId для доступа backend в keycloak настроенныый ранее
        clientSecret: "${KC_CLIENT_SECRET}" #Секрет сгенерированный ранее
        sigKeyKid: "${KC_SIG_KEY_SECRET}" #Приватный ключ для подписи токенов сгенерированный ранее

Настройка синхронизации пользователей​

Для настройки автоматической миграции пользователей из LDAP в YuChat с добавлением пользователей в команды небходимо изменить конфигурацию application.yml для сервиса backend.

user:
  sync:
      enabled: true #Вкл/выкл синхронизация с Keycloak
      cron: "*/5 * * * *" #cron-expression расписания синхронизации
      lockAtLeastFor: PT3M #системный параметр (не менее минимального времени синхронизации)
      lockAtMostFor: PT6M #системный параметр (более максимального времени синхронизации)
      defaultMapping: #Дополнительные настройки синхронизации (значения по умолчанию указаны ниже, не обязательно для заполнения)
        DEPARTMENT: department #Подразделение
        POSITION: position #Должность
        PHONE: phone #Телефон
        ENTRY_DN: entryDn #Поле в Keycloak, в котором будет содержаться OU LDAP, заданный выше
        FULL_NAME: displayName #Поле в KC в котором будет содержаться полное имя пользователя, например Иван Иванович Иванов
      orgUnits: #настройка обхектов синхронизации
        - workspaceId: "d16wvhMJkm" #Id воркспейса, в который будут добавляться пользователи при синхронизации
          ldapOU: "dc=company,dc=com" #Org unit ldap, из которого будут синхронизироваться пользователи
          additionalMapping: #Дополнительные настройки синхронизации для переопределения маппинга в рамках отдельных org units  (значения по умолчанию указаны ниже, не обязательно для заполнения)
              DEPARTMENT: department #Подразделение
              POSITION: position #Должность
              PHONE: phone #Телефон
              ENTRY_DN: entryDn #Поле в Keycloak, в котором будет содержаться OU LDAP, заданный выше
              FULL_NAME: displayName #Поле в KC в котором будет содержаться полное имя пользователя, например Иван Иванович Иванов
          updateExisted: false #Требуется ли обновлять аттрибуты пользователей при синхронизации в Keycloak

Синхронизация пользователей по департаментам​

В YuChat предусмотрена возможность автоматизированной миграции пользователей в рабочие пространства по департаментам организации. Пример :

  • Единые Контакты для всей организации
  • Аккаунты пользователей в ADFS распределены по - Sales, Development, Management
  • При создании нового аккаунта в ADFS пользователь должен автоматически добавится в рабочее пространство департамента в YuChat

Для реализации такой модели необходимо добавить несколько правил синхронизации для различных департаментов. Для миграции пользователей в организацию можно использовать статический атрибут для всех пользователей из ADFS. В примере ниже атрибут company_label присвоен всем пользователям при миграции пользователей из ADFS в Keycloak.

user:
  sync:
    enabled: true
    cron: "*/1 * * * *"
    lockAtLeastFor: PT1M
    lockAtMostFor: PT2M
    updateExisted: true
    orgUnits:
      - workspaceId: "d16wvhMJkm" #идентификатор Глобального рабочего пространства компании
        ldapOU: "mycompany" #значение статического параметра company_label
        updateExisted: true
        additionalMapping:
          ENTRY_DN: company_label #название аттрибута в Keycloak, в котором будет содержаться статический параметр mycompany
      - workspaceId: "g3jqGXJF7Q" #id пространства департамента продаж
        ldapOU: "CN=Sales,CN=Users,DC=yuchat,DC=fun" #имя группы Продаж в ADFS
        updateExisted: true
        additionalMapping:
          ENTRY_DN: memberOf
      - workspaceId: "h78uY3dLSi" #идентификатор пространства департамента Разработки
        ldapOU: "CN=Development,CN=Users,DC=yuchat,DC=fun"  #имя группы Разработки в ADFS
        updateExisted: true
        additionalMapping:
          ENTRY_DN: memberOf
      - workspaceId: "h8vM5Yysy0" #идентификатор пространства департамента Руководителей
        ldapOU: "CN=Management,CN=Users,DC=yuchat,DC=fun" #имя группы Руководителей в ADFS
        updateExisted: true
        additionalMapping:
          ENTRY_DN: memberOf
примечание

Часто в ADFS пользователям присвоено несколько групп, например у руководителей разработки в AD будут присутствовать группы Development и Management, и пользователи будет смигрированы в Организацию, Пространство департамента Разработки и пространство департамента Management

примечание

При использовании синхронизации memberOf (группы пользователей из AD для синхронизации в рабочие пространства) необходимо в соответствуюшем маппинга поля включить Always Read Value From LDAP

Синхронизация пользователей в каналы по группам Keycloak​

В дополнение к синхронизации пользователей в рабочие пространства, YuChat поддерживает автоматическое добавление пользователей в конкретные каналы (чаты) рабочего пространства на основании их принадлежности к группам в Keycloak.

Настройка выполняется через Панель Администратора → Синхронизация Keycloak → вкладка «Маппинг чатов на группы» в диалоге создания/редактирования конфигурации.

Параметры маппинга:

  • Чат — канал рабочего пространства (выбирается из списка)
  • Группы Keycloak — названия групп через запятую (пользователи из любой из указанных групп будут добавлены)
  • Удалять не из группы — если включено, пользователи, не входящие ни в одну из указанных групп, будут исключены из канала при синхронизации

Пример: отдел продаж (группа Sales) автоматически попадает в канал «Продажи», а разработчики (Development, QA) — в канал «Разработка».

подсказка

Подробная инструкция по настройке через интерфейс доступна в разделе Панель Администратора — Синхронизация Keycloak.

Использование дополнительных аттрибутов​

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

Пример: в рамках департамента разработки CN=Development существуют 2 команды разработки - iOS и Android. Необходимо автоматизированно добавлять разработчиков только из этих команд в отдельное рабочее пространство. У всех разработчиков в ADFS нестроен аттрибут "dev_team", значения которых ios, android, web, server

user:
  sync:
    enabled: true
    cron: "*/1 * * * *"
    updateExisted: true
    orgUnits:
      - workspaceId: "h78uY3dLSi" #идентификатор пространства групп Мобильной разработки
        ldapOU: "CN=Development,CN=Users,DC=yuchat,DC=fun"  #имя группы Разработки в ADFS
        updateExisted: true
        additionalMapping:
          ENTRY_DN: memberOf
        filterAttributes:
          - name: dev_team #общий аттрибут для всех команд разработки
            value: ios #только iOS разработчикам присвоено значение ios в аттрибуте dev_team
            eqType: LIKE #возможно использование EQ (точное соответствие) или LIKE (частичное совпадение в строке)
      - workspaceId: "h78uY3dLSi" #идентификатор пространства групп Мобильной разработки
        ldapOU: "CN=Development,CN=Users,DC=yuchat,DC=fun"  #имя группы Разработки в ADFS
        updateExisted: true
        additionalMapping:
          ENTRY_DN: memberOf
        filterAttributes:
          - name: dev_team
            value: android
            eqType: LIKE
Последнее обновление