1. Контур.Помощь
  2. Контур.SSO
  3. Инструкции для провайдеров
Инструкции для провайдеров
Настройка AD FS версии 3.0 Настройка AD FS версии 4.0 Настройка Keycloak

Настройка Keycloak

Keycloak — это решение с открытым исходным для SSO. Позволяет управлять аутентификацией и авторизацией пользователей.

Этап 1. Подготовка к установке

Перед началом установки Keycloak:

  • убедитесь, что на стороне вашей организации реализован LDAP;
  • зарегистрируйте домен;
  • выпустите сертификат TLS (например, в Let's Encrypt).

Этап 2. Установка Keycloak

  1. Обновите информацию о пакетах и установите обновления. 
    apt update && apt upgrade -y
  2. Установите необходимые пакеты для работы Keycloak. 
    apt install curl openjdk-17-jdk
  3. Скачайте Keycloak. Рекомендуем скачать версию 23.0.3, т. к. она наиболее стабильна по результатам тестирования. 
    curl -LO https://github.com/keycloak/keycloak/releases/download/23.0.3/keycloak-23.0.3.tar.gz
  4. Распакуйте архив. 
    tar -xvf keycloak-*.tar.gz
  5. Удалите архив. 
    rm keycloak-*.tar.gz
  6. При необходимости переместите папку с Keycloak в нужную директорию. 
    mv keycloak-*/ /opt/keycloak

​Этап 3. Установка и настройка базы данных PostgreSQL

  1. Установите последнюю версию PostgreSQL из репозитория. 
    apt -y install postgresql
  2. Установите пароль для созданной учетной записи в PostgreSQL. 
    passwd postgres
  3. Подключитесь к оболочке PostgreSQL. 
    su - postgres
psql
  4. Создайте базу данных keycloak. 
    create database keycloak;
  5. Создайте пользователя keycloak_user. 
    createuser keycloak_user
  6. Перейдите в psql и проверьте, успешно ли созданы база данных и пользователь. 
    psql
\l #выводит список баз данных
\du #выводит список пользователей
    Если база и пользователь созданы успешно, отобразится следующая информация:
     
  7. В psql установите пароль для супер-пользователя баз данных и пользователя keycloak_user.

    Команды должны заканчиваться символом ; .

    ALTER USER postgres WITH PASSWORD 'Gfhjkm123';
ALTER USER keycloak_user WITH PASSWORD 'Gfhjkm123';
  8. Предоставьте пользователю keycloak_user все необходимые права и подключитесь к базе данных keycloak. 
    grant all privileges on database keycloak to keycloak_user;
\c keycloak
  9. Предоставьте пользователю права доступа к схеме базы данных и выйдите из оболочки. 
    GRANT ALL ON SCHEMA public TO keycloak_user;
\q
exit

Этап 4. Настройка конфигурационного файла Keycloak

Для корректной работы приложения актуализируйте конфигурационный файл keycloak.conf. Для этого:

  1. Откройте конфигурационный файл Keycloak. 
    nano /opt/keycloak/conf/keycloak.conf
  2. Раскомментируйте строки и укажите нужные значения. 
    db=postgres
db-username=keycloak_user
db-password=Gfhjkm123
https-port=<номер_порта_прослушки>
https-certificate-file=/путь/до/сертификат.pem
https-certificate-key-file=/путь/до/ключа.pem
hostname=<FQDN> #обратите внимание: нужно ввести именно полное имя домена (FQDN), по которому будет доступен keycloak
  3. Добавьте переменные окружения и запустите сервис. 
    export KEYCLOAK_ADMIN=admin
export KEYCLOAK_ADMIN_PASSWORD=Gfhjkm123
cd /opt/keycloak/bin/
sudo ./kc.sh start
  4. После первого запуска обязательно создайте профиль администратора. Для этого войдите в консоль администратора Keycloak через веб-интерфейс, используя данные переменных из предыдущего пункта.

Этап 5. Создание сервиса автозапуска Keycloak

  1. Создайте сервис запуска Keycloak. 
    nano /lib/systemd/system/keycloak.service
  2. Скопируйте указанный текст в файл, сохраните его и закройте. После этого сохраните и закройте файл. 
    [Unit]
Description=Start Keycloak
After=multi-user.target
[Service]
Type=idle
ExecStart=/opt/keycloak/bin/kc.sh start
[Install]
WantedBy=multi-user.target
  3. Предоставьте права, необходимые для работы. 
    chmod 644 /lib/systemd/system/keycloak.service
  4. Обновите конфигурацию. 
    systemctl daemon-reload
  5. Добавьте сервис в автозагрузку. 
    systemctl enable keycloak.service

После запуска сервис будет доступен по адресу, который указан в конфигурации.

Этап 6. Создание Realm

Realm — это рабочее пространство Keycloak, в котором происходит управление набором пользователей, учетных данных, ролей и групп.

Создайте новый Realm. Для этого:

  1. Перейдите в панель администратора Keycloak и авторизуйтесь под учетной записью администратора. Для авторизации используйте данные из ранее заданных переменных (на этапе 4).
  2. В левом верхнем углу нажмите на выпадающий список и выберите Create Realm.

  3. В появившемся поле Real name укажите имя для Realm.

  4. Нажмите Create.

Этап 7. Создание client

Client — это приложение, которое будет обрабатывать аутентификацию пользователей.

  1. Перейдите в созданный Realm и на панели слева выберите раздел Clients.
  2. Нажмите Create client.
  3. В появившемся поле укажите Client ID (идентификатор, который будет передаваться в сервис в ID-токене). Сохраните этот идентификатор, он понадобится для завершения настроек на стороне сервиса (на этапе 10).
  4. Нажмите Next.

  5. Включите следующие параметры:

    • Client authentication;

    • Authorization;

    • Implicit Flow;

    • Standard flow.

  6. Нажмите Next.

  7. Если Keycloak настраивается для облачной версии сервиса:

    1. В поле Valid redirect URLs введите адреса:

      • https://auth-gateway.kontur.ru/login/callback;

      • https://auth-gateway.testkontur.ru/login/callback.

    2. В поле Home URL введите адрес вашего пространства в сервисе в формате https://%SPACE%.ktalk.ru/ .
      Где посмотреть адрес, см. в статье Частые вопросы.

  8. Если Keycloak настраивается для серверной версии (On-premise):

    1. В поле Root URL введите опубликованный адрес, по которому доступен Keycloak, в формате https://keycloak.mycompany.ru/ .

    2. В поле Valid redirect URLs введите символ * (звездочку).

    3. В поле Valid post logout redirect URIs тоже введите символ * (звездочку).

  9. Нажмите Save.

  10. В блоке Login settings → Login theme выберите keycloak или кастомную тему.

  11. Нажмите Save.

Этап 8. Создание или синхронизация пользователей

Добавьте в Keycloak пользователей, которые будут работать с сервисом. Это можно сделать одним из способов:

Создать вручную

Подходит, если в организации не используется LDAP или если нужно протестировать серверную версию (On-premise).

Чтобы создать пользователя, выполните следующее:

  1. Перейдите в раздел Users.
  2. Нажмите Add user.
  3. Заполните поля Username, Email, First name и Last name.

  4. Нажмите Create.

  5. Перейдите в раздел Users и нажмите на созданного пользователя.

  6. В открывшемся окне перейдите на вкладку Credentials и укажите пароль для пользователя.

В claim (атрибуте) sid нужно передавать уникальный идентификатор пользователя. Мы рекомендуем передавать идентификатор, который Keycloak сгенерировал автоматически.

Для этого:

  1. Перейдите в раздел Client Scopes.
  2. Нажмите Create client scope.
  3. Укажите в поле Name значение атрибута sid.
  4. Нажмите Save.
  5. Перейдите на вкладку Mappers и нажмите Configure a new mapper.

  6. В поле Mapper type выберите User Property.

  7. В поле Name укажите значение «sid».

  8. В поле Property укажите значение «id».

  9. В поле Token Claim Name укажите значение «sid».

  10. На левой панели перейдите в раздел Clients и выберите ранее созданный client (на этапе 7).

  11. Перейдите на вкладку Client scopes и нажмите Add client scope.

  12. Выберите созданный sid, нажмите Add и выберите тип Default.

Keycloak готов к интеграции с облачной версией.

Синхронизировать данные с Active Directory (LDAP)

Подходит, если нужно перенести данные пользователей из Active Directory (LDAP) в Keycloak.

Чтобы настроить синхронизацию, выполните следующее:

  1. На панели слева выберите User federation.
  2. Нажмите Add Ldap providers.
  3. В поле UI display name укажите имя поставщика в формате any_name .

  4. В поле Vendor укажите имя поставщика Active Directory.

  5. В блоке Connection and authentication settings заполните следующие поля:
    • Connection URL: укажите адрес сервера LDAP: ldap:// .

    • Bind type: выберите simple.

    • Bind DN: укажите путь до записи LDAP-администратора (например, cn=admin,dc=domain,dc=ru).
    • Bind credentials: введите пароль LDAP-администратора.
  6. В блоке LDAP searching and updating заполните следующие поля:

    • Edit mode: укажите значение «WRITABLE».

    • Users DN: укажите путь до каталога с пользователями (например, ou=office,dc=domain,dc=ru).
    • Username LDAP attribute: выберите LDAP-атрибут. Он будет использоваться как имя пользователя в Keycloak. По умолчанию установлено значение cn.

    • RDN LDAP attribute: cn.

    • UUID LDAP attribute: укажите уникальный идентификатор (например, uidNumber).

    • User object classes: укажите «inetOrgPerson».

    • Search: укажите Subtree.

  7. В блоке Synchronization settings включите все параметры и укажите периодичность синхронизации.
  8. В блоке Advanced settings включите параметры Validate password policy и Trust email.
  9. Нажмите Save.
  10. Перейдите на вкладку Mappers и укажите наименования атрибутов:

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

    При указании атрибутов соблюдайте соответствие: User Model Attribute — название атрибута в Keycloak, LDAP Attribute — название атрибута в LDAP.

    • Выберите mail. В поле User Model Attribute укажите значение «email», в поле LDAP Attribute укажите значение «mail».

    • Нажмите Save.

    • Выберите first name. В поле User Model Attribute укажите значение «firstName», в поле LDAP Attribute укажите значение «givenName».

    • Нажмите Save.

    • Нажмите last name. В поле User Model Attribute укажите значение «lastName», в поле LDAP Attribute укажите значение «sn».

    • Нажмите Save.

  11. Проверьте доступность LDAP в Keycloak. Для этого перейдите в раздел Users, в поле поиска введите символ *  (звездочку) и нажмите Enter.
    Если пользователи появились, значит настройка выполнена успешно. Если не появились — проверьте доступность домена и правильность указанных данных.

В Keycloak пользователи смогут авторизоваться под учетной записью, указанной в LDAP. Логин имеет вид login@domain.ru.

Этап 9. Настройка claims

Установите соответствия для claims (атрибутов).

Наименования атрибутов (claims) указаны ниже в качестве примера. В вашей базе данных наименования могут отличаться от предложенных.

Обязательные claims:

  • email: email;
  • surname: family_name;
  • firstname: given_name.

Дополнительные claims (рекомендуемые):

  • post: title;
  • phone: phone_number;
  • picture: picture.

Сервис установит аватар пользователя, только если в атрибуте picture передать ссылку на изображение. Передача самого файла не поддерживается.

Этап 10. Завершение настройки

Если используете облачную версию, для завершения настройки сообщите своему специалисту по внедрению следующие данные:

  • Название организации.
  • Адрес вашего пространства в формате «name.ktalk.ru»​.
    Как его узнать, см. в статье Частые вопросы.
  • Адрес сервера OpenID Connect в формате:
    https://<ваш_домен.ru>:<port>/realms/<ваш_real_name>/.well-known/openid-configuration
    (где ваш_real_name — это имя, указанное на этапе 6).

    Можно предоставить дискавери-документ. Для этого в сервисе администрирования Keycloak перейдите в раздел Realm settings → General → Endpoints. Скопируйте ссылку на OpenID Endpoint Configuration и приложите в качестве адреса сервера.
  • Client_id.
    Укажите id, который вы установили при создании client на этапе 7.
  • Client_secret.
    Его можно найти в сервисе администрирования Keycloak → раздел Clients → выберите нужного client → Credentials → Secret.
База знаний