Тип статьи	Инструкция
Компетенции	Администратор
Необходимые права	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.

д