Запуск Keycloak и подключение LDAP каталога
Олег Иванов
Тип статьи | Инструкция |
---|---|
Компетенции | Администратор |
Необходимые права | root |
Версия платформы | 2.31 |
Статус | БЕТА |
Сложность | СЛОЖНО |
Полезные ссылки | https://www.keycloak.org/docs/latest/server_admin/index.html |
Дополнительные сведения | Ubuntu 22.04, Microsoft Windows Server 2022, Keycloak 19.0.3 |
При устаревании инструкции используйте описанные в ней подходы и более свежие знания в документации актуальной версии платформы и keycloak. Вы также всегда можете написать на support@visiology.su с запросом о помощи или замечанием по инструкции.
Введение
Данная инструкция поможет запустить Keycloak и подключить к нему ваш LDAP провайдер.
1. Вводные данные
В данной статье описан запуск и настройка Keycloak версии 19.0.3, если вы используете другую версию и инструкция не подходит, то следует обратиться к документации Keycloak и сделать корректировку. Также тут описана базовая настройка интеграции с LDAP, если вам необходимо выполнить какие-то действия не описанные в данной инструкции, воспользуйтесь документацией Keycloak.
Visiology установлен на Ubuntu 22.04, железо типовое и соответствует системным требованиям платформы для целей тестирования (см. статью системные требования).
Keycloak будет запущен в докере, процесс запуска описан в этой статье.
В качестве LDAP каталога выступает MS ADDS.
2. Запуск Keycloak
Keycloak будем запускать в докере. Для этого в файл /v2/external.yml в дистрибутиве платформы добавим следующие сервисы. Если вы уже используете этот файл, то добавьте в него сервисы из кода ниже, если он стандартный, то можно просто перезаписать весь файл:
# Put here your custom services version: "3.8" x-deploy: &deploy networks: visiology-2: deploy: placement: max_replicas_per_node: 1 constraints: - "node.labels.platform==true" volumes: postgres_data: driver: local services: kc_postgres: image: postgres labels: component: "kc_postgres" volumes: - postgres_data:/var/lib/postgresql/data environment: POSTGRES_DB: keycloak POSTGRES_USER: keycloak POSTGRES_PASSWORD: password << : *deploy keycloak: image: quay.io/keycloak/keycloak:legacy environment: DB_VENDOR: POSTGRES DB_ADDR: kc_postgres DB_DATABASE: keycloak DB_USER: keycloak DB_SCHEMA: public DB_PASSWORD: password KEYCLOAK_USER: admin KEYCLOAK_PASSWORD: Password ports: - 8080:8080 labels: component: "keycloak" depends_on: - kc_postgres << : *deploy networks: visiology-2: external: true name: ${FULL_NETWORK_NAME}
После редактирования файла перезапускаем платформу, дожидаемся загрузки образов keycloak и postgres, после этого можно работать. Попасть в keycloak можно через http://адресПлатформы:8080. Дефолтные логин и пароль: admin / Password (они описаны в yml файле).
3. Настройка User Federation в Keycloak
Для подключения LDAP каталога к Keycloak используется User federation. Откройте Keycloak и перейдите в User federation щелкнув по соответствующему пункту в меню слева:
Далее нажимаем на кнопку Add Ldap providers и приступаем к настройке нашего коннектора.
Console display name - любое удобное для вас имя.
Vendor - тип LDAP провайдера. Выбор вендора меняет предустановленные параметры в коннекторе, такие как атрибут имени пользователя и прочее.
Connection URL - url вашего ldap каталога. Следует писать в таком виде: ldap://example.com, либо ldaps:// в случае использования ssl.
Параметры шифрования настраиваете под ваш конкретный случай или не трогаете если у вас всё по умолчанию.
Bind type - выбираем либо Simple, либо none если у вас без авторизации.
Bind DN - DN LDAP админа, пример: CN=Admin,DC=example,DC=com
Bind credentials - пароль LDAP админа.
После ввода логина и пароля можно нажать на кнопку Test authentication для проверки соединения с каталогом.
Edit mode - как правило это READ_ONLY, но завит от вашего кейса.
Users DN - корень LDAP дерева где находятся пользователи.
Username LDAP attribute - LDAP атрибут используемый в качестве имени пользователя. Если хотите использовать другой, например userPrincipalName, то также необходимо изменить атрибут в маппере username.
RDN LDAP attribute - обычно используется тот же атрибут, что и для имени пользователя.
User LDAP filter - фильтр поиска пользователей в LDAP. Например если нужно синхронизировать только пользователей из определённой группы, то следует использовать фильтр.
Search scope - искать только на этом уровне или также на всех подуровнях.
На этом базовая настройка окончена. Можно попробовать выполнить синхронизацию пользователей нажав на кнопку Sync all users в правом верхнем углу. Если все настройки правильные, то пользователи будут синхронизированы. Если по какой-то причине не удастся синхронизировать того или иного пользователя то после синхронизации в уведомлении вы увидите информацию об этом. Более подробно об ошибке можно узнать в логах Keycloak.
4. Интеграция Visiology и Keycloak
Подключаем наш Keycloak к Visiology по этой инструкции Пример настройки Keycloak
После подключения можно пробовать заходить через наших LDAP пользователей.
5. Маппинг LDAP групп
Для проброса групп из LDAP каталога следует добавить маппер в наш ЛДАП коннектор. Заходим в наш коннектор и вверху выбираем Mappers:
Нажимаем Add mapper. Тип выбираем role-ldap-mapper, имя любое удобное для вас. Все параметры по умолчанию за исключением Client ID, тут выбираем клиент который мы создали для подключения к Visiolog:
Маппинг на стороне Visiology настраиваем по этой статье - Настройка соответствия OpenID Connect
6. Подключение двух и более LDAP каталогов
Если требуется подключить более одного каталога, то просто добавляете еще один коннектор в User federation.
Может возникнуть ситуация, что имена пользователей будут пересекаться, т.к. по умолчанию в качестве имени выступает атрибут cn. В этом случае следует изменить этот атрибут на userPrincipalName. Менять следует в параметрах коннектора и в параметрах маппера username.
д