Keycloak

Описание страницы

Keycloak — это сервер аутентификации и авторизации с открытым исходным кодом, который обеспечивает безопасность и управление доступом для веб-приложений и сервисов

Как это работает

На странице создаётся конфигурация подключения к серверу Keycloak для авторизации пользователей и синхронизации данных

После настройки Keycloak может использоваться как поставщик единого входа (SSO), при этом пользователь проходит проверку учетных данных в Keycloak, а сервер RuDesktop получает результат авторизации и данные пользователя, включая группы, из токена или при синхронизации

Группы из Keycloak можно связать с локальными группами RuDesktop, чтобы назначать пользователям права RuDesktop на основании членства в группах Keycloak

Сценарии использования

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

Только SSO авторизация

Пользователи входят через единую форму Keycloak, но списки пользователей и групп в RuDesktop заранее не наполняются — учётная запись создаётся при первом входе

Что включать в RuDesktop:

  • Включить — да

  • Использовать для SSO авторизации — да

  • Использовать для синхронизации — нет

Что настроить в Keycloak: клиент типа OpenID Connect (см. Создание Clients) и маппер Group Membership (см. Настройка передачи групп для SSO). Сервисный аккаунт не нужен

Только синхронизация

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

Что включать в RuDesktop:

  • Включить — да

  • Использовать для SSO авторизации — нет

  • Использовать для синхронизации — да

Что настроить в Keycloak: клиент OpenID Connect и сервисный аккаунт с ролями realm-management (см. Настройка сервисного аккаунта). Маппер групп не нужен — данные забираются через API Keycloak

SSO авторизация и синхронизация одновременно

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

Что включать в RuDesktop:

  • Включить — да

  • Использовать для SSO авторизации — да

  • Использовать для синхронизации — да

Что настроить в Keycloak: все шаги из обоих предыдущих режимов — клиент OpenID Connect, маппер Group Membership и сервисный аккаунт

Важно

На сервере RuDesktop одновременно может быть только одна конфигурация Keycloak с включённым параметром Использовать для SSO авторизации. Число конфигураций с включённой синхронизацией не ограничено — можно одновременно синхронизировать пользователей из нескольких Realms

Подготовка Keycloak

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

  • Установить и настроить сервер Keycloak

Примечание

Руководство по установке Keycloak: https://www.keycloak.org/guides#server

  • Создать клиентское приложение в Keycloak, чтобы получить конфигурационные данные для аутентификации и авторизации

  • Настроить приложение для использования конфигурационных данных Keycloak

Настройка Keycloak

Примечание

Инструкция актуальна для Keycloak версии 19 и выше с новой административной панелью. В более ранних версиях названия вкладок и расположение элементов могут отличаться, но смысл настроек остаётся прежним

Создание Realm

Realm создаётся отдельно для интеграции с RuDesktop

  1. Войти в административную панель Keycloak под учётной записью администратора

  2. Открыть выпадающий список Realm в левом верхнем углу панели

  3. Нажать на кнопку Create Realm

  1. В поле Realm name ввести название нового Realm

    Примечание

    Это же значение позже потребуется указать в поле Название Realm при создании конфигурации в RuDesktop

  2. Убедиться, что переключатель Enabled включён

  3. Нажать на кнопку Create

Создание Clients

Client создаётся для RuDesktop как клиент типа OpenID Connect

  1. Войти в административную панель Keycloak

  2. Убедиться, что в выпадающем списке слева выбран нужный Realm

  3. Открыть раздел Clients в левом меню

  1. Нажать на кнопку Create client

  2. Во вкладке General Settings заполнить поля:

    5.1. Client type — выбрать значение OpenID Connect

    5.2. Client ID — ввести уникальный идентификатор клиента, например rudesktop

    Примечание

    Это же значение позже потребуется указать в поле ID клиента с правами на чтение при создании конфигурации в RuDesktop

    5.3. Name — указать понятное название клиента

  1. Нажать на кнопку Next и перейти во вкладку Capability config

  2. Во вкладке Capability config настроить переключатели:

    • Client authentication — включить (нужно для генерации Client Secret, по которому RuDesktop подтверждает подлинность перед Keycloak)

    • Standard flow — включить (по этому потоку работает SSO RuDesktop)

    • Service accounts roles — включить, если планируется использовать синхронизацию пользователей и групп через API Keycloak (параметр Использовать для синхронизации в RuDesktop)

    • Остальные переключатели оставить со значениями по умолчанию

  1. Нажать на кнопку Next и перейти во вкладку Login settings

  2. Во вкладке Login settings заполнить поля:

    9.1. Root URL — указать базовый адрес сервера RuDesktop, например https://rudesktop.example.com

    9.2. Home URL — указать адрес страницы, на которую возвращается пользователь после авторизации, например https://rudesktop.example.com/admin/

    9.3. Valid redirect URIs — указать точный адрес обработчика обратного вызова RuDesktop:

    https://rudesktop.example.com/keycloak/callback/

    Важно

    Не используйте маску /* или * в качестве значения Valid redirect URIs — это уязвимость класса Open Redirect. RuDesktop принимает callback только по адресу /keycloak/callback/, его и нужно указать целиком. Замените rudesktop.example.com на фактический домен вашего сервера RuDesktop; если адресов несколько, добавьте каждый отдельной строкой

    9.4. Valid post logout redirect URIs — указать страницу, на которую Keycloak возвращает пользователя после выхода, например https://rudesktop.example.com/admin/login/

    9.5. Web origins — указать домен RuDesktop для CORS, например https://rudesktop.example.com или значение + (использовать список из Valid redirect URIs)

  1. Нажать на кнопку Save для завершения создания клиента

  2. После сохранения Keycloak откроет страницу клиента. Перейти во вкладку Credentials и скопировать значение Client Secret — оно потребуется при создании конфигурации в RuDesktop (поле Ключ доступа к клиенту)

    Важно

    Client Secret отображается только в панели Keycloak. Если значение утеряно, его можно перегенерировать кнопкой Regenerate, но после этого потребуется обновить настройки и в RuDesktop

Настройка сервисного аккаунта

Примечание

Раздел нужен только при использовании синхронизации (параметр Использовать для синхронизации в RuDesktop). Если планируется только SSO авторизация — раздел можно пропустить

В режиме синхронизации RuDesktop обращается к API Keycloak от имени клиента, поэтому сервисному аккаунту нужно выдать права на чтение пользователей и групп

  1. Открыть созданного клиента в разделе Clients

  2. Перейти во вкладку Service accounts roles

  3. Нажать на кнопку Assign role

  4. В фильтре выбрать Filter by clients и назначить сервисному аккаунту следующие роли клиента realm-management:

    • view-users — для чтения списка пользователей и их атрибутов

    • view-realm — для чтения настроек Realm

    • query-groups — для чтения списка групп

    • query-users — для поиска пользователей по фильтрам

Важно

Без перечисленных ролей синхронизация завершится ошибкой 403 Forbidden

Настройка передачи групп для SSO

Примечание

Раздел обязателен, если в RuDesktop параметр Использовать для синхронизации выключен — в этом случае группы пользователя берутся из токена. При включённой синхронизации группы запрашиваются через API Keycloak, и раздел можно пропустить

Чтобы группы пользователя передавались в JWT-токене, в Keycloak настраивается маппер Group Membership

  1. Открыть созданного клиента в разделе Clients

  2. Перейти во вкладку Client scopes

  3. Открыть область с именем <Client ID>-dedicated (создаётся автоматически вместе с клиентом)

  4. Перейти во вкладку Mappers и нажать на кнопку Configure a new mapper

  5. Выбрать тип маппера Group Membership

  6. Заполнить поля маппера:

    • Name — указать понятное имя, например groups

    • Token Claim Name — указать строго groups

    • Full group path — рекомендуется выключить (тогда группа передаётся как support — именно это значение нужно указывать в поле Группа в Keycloak локальной группы RuDesktop)

    • Add to ID token — включить

    • Add to access token — включить

    • Add to userinfo — включить

  7. Нажать на кнопку Save

Важно

Если группы не передаются в токене и не доступны серверу RuDesktop при синхронизации, пользователь сможет пройти авторизацию, но попадёт только в группу по умолчанию

Создание Users

Этот раздел нужен, если в созданном Realm пока нет пользователей и их нужно создать вручную. При синхронизации с внешним каталогом (LDAP, Active Directory) пользователи появятся автоматически после настройки Identity Provider

  1. Войти в административную панель Keycloak

  2. Убедиться, что в выпадающем списке слева выбран нужный Realm

  3. Открыть раздел Users в левом меню

  1. Нажать на кнопку Add user

  1. Заполнить форму создания пользователя:

    5.1. Username — логин пользователя (используется для входа)

    5.2. Email — адрес электронной почты

    5.3. First name — имя

    5.4. Last name — фамилия

    5.5. Включить переключатель Email verified, если адрес уже подтверждён

  1. Нажать на кнопку Create

  2. На открывшейся странице пользователя перейти во вкладку Credentials и задать пароль:

    7.1. Нажать на кнопку Set password

    7.2. Ввести пароль и его подтверждение

    7.3. Переключатель Temporary оставить включённым, чтобы при первом входе пользователь сменил пароль самостоятельно

    7.4. Нажать на кнопку Save

  3. При необходимости перейти во вкладку Groups и добавить пользователя в нужные группы Keycloak — именно эти группы будут передаваться в RuDesktop при авторизации

Настройка Identity Provider

Примечание

Раздел применяется, когда Keycloak должен делегировать проверку логина и пароля внешней системе (LDAP, Active Directory, другой OIDC-провайдер). Если пользователи создаются непосредственно в Keycloak, раздел можно пропустить

  1. Открыть раздел Identity providers в левом меню

  2. Выбрать нужный тип провайдера (например, LDAP, Kerberos или один из социальных провайдеров)

  1. Задать настройки провайдера: адрес сервера, порт, протокол, маппинг атрибутов пользователя и т. д.

  1. Нажать на кнопку Save для сохранения настроек провайдера

Создание конфигурации в RuDesktop

  1. Войти в административную панель RuDesktop

  2. Открыть блок Администрирование

  3. Нажать на пункт Keycloak

  4. Нажать на кнопку Добавить Keycloak

  5. Заполнить поля:

    5.1. Активировать галочку в чек-боксе Включить

    5.2. При необходимости активировать чек-бокс Использовать для SSO авторизации

    5.3. При необходимости активировать чек-бокс Использовать для синхронизации

    5.4. Указать адрес сервера Keycloak в поле Адрес сервера

    5.5. Если используется TLS шифрование, то активировать галочку в чек-боксе Использовать TLS шифрование

    5.6. Указать название Realm в поле Название Realm

    5.7. Указать ID клиента в поле ID клиента с правами на чтение

    5.8. Указать Client Secret в поле Ключ доступа к клиенту

    5.9. Выбрать из списка группу по умолчанию для новых пользователей в поле Группа по умолчанию для новых пользователей

  1. Нажать на кнопку Сохранить и продолжить

Авторизация через Keycloak

  1. Перейти на страницу авторизации

  2. Выбрать Realm в поле выбора домена

  1. Ввести Логин и Пароль

  2. Нажать на кнопку Войти

Описание работы синхронизации и SSO

В этом разделе описано, что именно делает RuDesktop при синхронизации и при SSO авторизации, как формируется имя пользователя, что происходит с удалёнными учётными записями и как локальные группы связываются с группами Keycloak

Запуск синхронизации

Синхронизацию можно запустить:

  • Вручную — кнопкой Синхронизировать на странице конфигурации Keycloak в RuDesktop

  • Через серверную команду rude keycloak sync — удобно для запуска по расписанию через cron на стороне сервера

Примечание

Кнопка Синхронизировать доступна только для записей, у которых активирован чек-бокс Использовать для синхронизации

При SSO авторизации членство пользователя в группах обновляется отдельно — независимо от ручной или фоновой синхронизации (см. раздел Как работает SSO авторизация)

Формат имени пользователя в RuDesktop

Все пользователи, импортированные из Keycloak, сохраняются в RuDesktop под именем по шаблону <username>@<realm_name> — это исключает конфликты с локальными пользователями и с пользователями из других Realm

Например: пользователь ivanov из Realm corp будет сохранён в RuDesktop как ivanov@corp

Примечание

На странице авторизации пользователь вводит свой обычный логин Keycloak (без суффикса) — суффикс @<realm_name> подставляется сервером автоматически. Имя со суффиксом отображается в списке пользователей в административной панели RuDesktop

Что именно синхронизируется

При запуске синхронизации RuDesktop обращается к API Keycloak от имени сервисного аккаунта клиента и переносит данные в локальную базу в следующем порядке: сначала группы, затем пользователи и их членство в группах

Синхронизация групп

RuDesktop запрашивает у Keycloak полный список групп выбранного Realm и для каждой группы создаёт или обновляет соответствующую локальную группу в RuDesktop

Что переносится:

  • Имя группы — записывается в поле Название локальной группы и одновременно в поле Группа в Keycloak, по которому происходит сопоставление при SSO авторизации

  • Полный путь группы в Keycloak (например, /parent/support) — сохраняется в служебном поле локальной группы и используется для однозначной идентификации группы при последующих синхронизациях

Примечание

Иерархия групп Keycloak обходится рекурсивно: для каждой родительской группы синхронизируются все вложенные подгруппы. В RuDesktop все группы создаются как плоский список, но различаются по полному пути из Keycloak — это позволяет корректно различать группы с одинаковыми именами в разных ветках иерархии

Важно

Права доступа локальных групп RuDesktop при синхронизации не изменяются. Синхронизация только создаёт или обновляет запись о группе. Назначение прав остаётся за администратором RuDesktop — это сделано для того, чтобы иерархия и состав групп Keycloak не могли случайно изменить набор разрешений на сервере

Возможные результаты по каждой группе:

  • OK — группа создана или уже существовала с теми же значениями

  • Conflict — в RuDesktop уже есть группа с таким именем, но привязанная к другому пути или другому Keycloak. Такая группа пропускается, нужно либо переименовать локальную группу, либо удалить дубликат

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

RuDesktop запрашивает у Keycloak список пользователей Realm и обрабатывает каждого пользователя, у которого включён флаг Enabled в Keycloak

Что переносится:

  • Username — сохраняется в RuDesktop в формате <username>@<realm_name>, чтобы избежать конфликтов с локальными пользователями и пользователями из других Realms

  • First name — имя

  • Last name — фамилия

  • Email — адрес электронной почты

  • Членство в группах — для каждого пользователя RuDesktop запрашивает список групп через API Keycloak и привязывает пользователя к локальным группам по полному пути группы

Если у пользователя в Keycloak не указано ни одной группы и в конфигурации RuDesktop заполнено поле Группа по умолчанию для новых пользователей, пользователь добавляется в эту группу. Это позволяет новым сотрудникам сразу получать минимальный набор прав для входа в систему

Примечание

Пользователи с флагом Enabled = false в Keycloak при синхронизации пропускаются — соответствующие учётные записи в RuDesktop не создаются и не обновляются

Возможные результаты по каждому пользователю:

  • OK — пользователь создан или обновлён

  • Not found — пользователь не найден в RuDesktop при попытке обновления (редкая ситуация при гонке записей)

  • Conflict — в RuDesktop уже есть пользователь с таким username, но связанный с другим Realm или с другой записью Keycloak

Что происходит с удалёнными или отключёнными пользователями

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

  • Пользователи, удалённые в Keycloak

  • Пользователи с выключенным флагом Enabled в Keycloak

Важно

Удаление затрагивает только пользователей, импортированных из соответствующего Keycloak — локальные пользователи RuDesktop и пользователи из других конфигураций не трогаются. Если нужно временно ограничить доступ без удаления учётной записи, не отключайте пользователя в Keycloak, а исключите его из групп, дающих права в RuDesktop

Как работает SSO авторизация

При SSO авторизации Keycloak является источником проверки учетных данных пользователя:

  1. Пользователь открывает страницу авторизации RuDesktop

  2. Выбирает Realm, для которого включено использование Keycloak для авторизации

  3. RuDesktop перенаправляет пользователя на авторизацию через Keycloak или проверяет учетные данные через настроенную интеграцию

  4. После успешной проверки Keycloak возвращает серверу RuDesktop данные пользователя

  5. RuDesktop создает пользователя, если его еще нет на сервере, или обновляет данные существующего пользователя

  6. RuDesktop сопоставляет группы пользователя из Keycloak с локальными группами RuDesktop

  7. Пользователь получает права, которые назначены его локальным группам на сервере RuDesktop

Важно

Для SSO авторизации в конфигурации Keycloak на сервере RuDesktop должен быть включен параметр Использовать для SSO авторизации

Связь группы Keycloak с локальной группой RuDesktop

Локальная группа RuDesktop используется для назначения прав, а группа Keycloak используется как внешний источник членства пользователя в этой группе

Чтобы связать группу Keycloak с локальной группой RuDesktop:

  1. Открыть административную панель RuDesktop

  2. Перейти в раздел Организация → Группы

  3. Создать новую локальную группу или открыть существующую группу

  4. На вкладке Основная информация заполнить поле Группа в Keycloak

  5. В поле Группа в Keycloak указать название группы так, как оно передается из Keycloak

    Подсказка

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

  6. Настроить права доступа локальной группы RuDesktop

  7. Нажать на кнопку Сохранить

После этого при авторизации или синхронизации пользователь будет добавлен в локальную группу RuDesktop, если он состоит в соответствующей группе Keycloak

Примечание

Название группы в поле Группа в Keycloak должно совпадать с именем группы, которое RuDesktop получает от Keycloak. Например, если группа в Keycloak называется support, в поле Группа в Keycloak нужно указать support

Почему локальные группы могут сбрасываться после SSO авторизации

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

Параметр Использовать для синхронизации определяет, откуда RuDesktop получает группы при SSO авторизации:

  • Если параметр включен, группы запрашиваются через API Keycloak

  • Если параметр выключен, группы берутся из токена авторизации Keycloak

Даже если параметр Использовать для синхронизации выключен, после успешной SSO авторизации текущие группы пользователя на сервере RuDesktop могут быть заменены группами, которые пришли из Keycloak

Если пользователь был вручную добавлен в локальную группу RuDesktop, но эта группа не пришла из Keycloak при SSO авторизации, такая локальная группа может быть удалена из списка групп пользователя

Например:

  1. В RuDesktop есть локальная группа Сотрудники поддержки

  2. Администратор вручную добавил пользователя в группу Сотрудники поддержки в RuDesktop

  3. В настройках Keycloak параметр Использовать для синхронизации выключен

  4. При SSO авторизации из токена Keycloak не пришла группа, которая соответствует группе Сотрудники поддержки

  5. После SSO авторизации RuDesktop получает данные из Keycloak и удаляет пользователя из локальной группы Сотрудники поддержки

Такое поведение необходимо, чтобы права пользователя на сервере RuDesktop соответствовали актуальному членству в группах Keycloak

Чтобы локальная группа не сбрасывалась после SSO авторизации:

  • Добавьте пользователя в соответствующую группу на стороне Keycloak

  • Проверьте, что группа передается в токене, если параметр Использовать для синхронизации выключен

  • Проверьте, что группа доступна через API Keycloak, если параметр Использовать для синхронизации включен

  • Убедитесь, что значение в поле Группа в Keycloak совпадает со значением группы, которое получает RuDesktop

Предупреждение

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

Проверка настройки

Если после настройки SSO пользователь авторизуется, но не получает нужные права, проверьте:

  • Пользователь создан и активен в Keycloak

  • Пользователь состоит в нужной группе Keycloak

  • Для клиента Keycloak настроена передача групп

  • Группа передается в токене или доступна серверу RuDesktop при синхронизации

  • Значение группы из Keycloak совпадает со значением в поле Группа в Keycloak

  • В локальной группе RuDesktop настроены нужные права доступа

  • В конфигурации Keycloak на сервере RuDesktop включен параметр Использовать для SSO авторизации

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

  • Если параметр Использовать для синхронизации включен, нужные группы доступны через API Keycloak

Типовые ошибки

При настройке интеграции чаще всего встречаются следующие ошибки:

  • В поле Группа в Keycloak указан полный путь группы, например /support, хотя для сопоставления ожидается имя группы support

  • Пользователь вручную добавлен в локальную группу RuDesktop, связанную с Keycloak, но на стороне Keycloak не состоит в соответствующей группе

  • Для клиента Keycloak не настроен маппер групп, поэтому RuDesktop не получает список групп пользователя

  • Параметр Использовать для синхронизации выключен, но нужная группа не передается в токене авторизации Keycloak

  • Администратор ожидает, что выключенный параметр Использовать для синхронизации сохранит вручную назначенные локальные группы, но при SSO авторизации группы пользователя обновляются по данным Keycloak

  • Новому пользователю назначается группа по умолчанию, но у этой группы нет прав, необходимых для работы

  • Включена синхронизация с Keycloak, и она обновляет членство пользователя в связанных локальных группах по данным внешней системы