Налаштування власного DNS-імені для Keycloak

🌐 Цей документ доступний українською та англійською мовами. Використовуйте перемикач у правому верхньому куті, щоб змінити версію.

1. Загальний опис

Адміністратори платформи мають змогу налаштовувати власні DNS-імена для сервісу управління користувачами та ролями Keycloak за допомогою адміністративної панелі Control Plane. Це дозволяє створити зручні URL-адреси для входу користувачів та забезпечує правильну роботу аутентифікації та міжсервісної взаємодії у приватних мережах.

Переваги використання функціональності:

  • Власні DNS-імена: надає можливість створювати зручні та легко запам’ятовувані URL-адреси для входу користувачів у їхні особисті кабінети.

  • Коректна робота в приватних мережах: добре працює у приватних мережах, забезпечуючи правильну перевірку сертифікатів та аутентифікацію за допомогою Keycloak для міжсервісної взаємодії.

Завдяки цьому адміністратори можуть легко та ефективно керувати налаштуваннями Keycloak, що сприяє полегшенню роботи користувачів із системою.

Функціональні сценарії:

  • Конфігурація DNS-імен компонента Keycloak через адмін-консоль на рівні Платформи

  • Вибір DNS-імені для логіна в кабінети користувачів через адмін-консоль на рівні реєстру

  • Видалення доданих DNS-імен до Keycloak

Загальні принципи та положення:

  • Технічний адміністратор Платформи відповідає за конфігурацію наявних Keycloak DNS-імен.

  • Адміністратор завантажує SSL-сертифікат у форматі .pem для домену разом із DNS-іменем.

  • Технічний адміністратор реєстру налаштовує DNS-імена для реєстрових кабінетів користувачів.

  • Адміністратор реєстру обирає домен для Keycloak зі списку доступних.

  • Список доступних доменів у системі формується з DNS-імен платформного Keycloak.

  • У налаштуваннях кабінетів можна завантажити окремі SSL-сертифікати у форматі .pem для кожного користувацького кабінету.

  • Адміністратор Платформи забезпечує ротацію сертифікатів Keycloak та кабінетів користувачів.

  • Система дозволяє редагувати встановлені раніше SSL-сертифікати та DNS-імена.

  • Адмін-консоль перевіряє, чи завантажений SSL-сертифікат відповідає введеному домену, чи не є самопідписаним, та чи строк його дії ще не сплив.

  • З міркувань безпеки, доступ до HashiCorp Vault для читання сертифікатів здійснюється ЛИШЕ через окремого сервісного (системного) користувача.

  • Якщо реєстр розгортається без порталу (надавача або отримувача послуг), відповідні UI-елементи для налаштування DNS-імен не відображаються.

  • Заданий URL для Keycloak та кабінетів обмежений 63 символами та проходить системну валідацію на правильність.

2. Конфігурація DNS-імен компонента Keycloak для Платформи

Щоб налаштувати власні DNS-імена, а також завантажити SSL-сертифікати для Keycloak, виконайте наступні дії:

  1. Увійдіть до адміністративної панелі Control Plane.

  2. Відкрийте розділ Керування Платформою та перейдіть до пункту Keycloak DNS.

    У цьому розділі ви побачите системне значення DNS за замовчуванням, яке вже заповнене й недоступне для редагування.

    Для додаткових DNS виконайте зовнішню конфігурацію записів у реєстратора доменних імен. Для цього скористайтеся інструкцією Додаткова конфігурація за межами OpenShift-кластера та реєстру, яка також доступна за посиланням на інтерфейсі Control Plane.

    custom dns keycloak platform 1

  3. Натисніть кнопку Додати DNS, щоб відкрити вікно налаштувань. Введіть доменне ім’я для Keycloak, відповідно до підказок під полем, і завантажте SSL-сертифікат для Keycloak.

    Конфігурація DNS за замовчуванням вичитується адмін-консоллю зі специфікації Keycloak CR у компоненті user-management.

  4. У вікні налаштувань натисніть кнопку Підтвердити, щоб зберегти дані та запустити валідаційні перевірки.

    Ви можете також натиснути кнопку Відмінити, щоб закрити вікно без збереження внесених даних.

    custom dns keycloak platform 2

    Всі додані DNS-імена будуть відображатися списком на сторінці Keycloak DNS.

  5. Ви можете відредагувати будь-яке з доданих DNS-імен, натиснувши на іконку олівця поряд з обраним додатковим DNS. У вікні редагування змініть доменне ім’я та сертифікат.

    Дія кнопок "Відмінити" та "Підтвердити" така сама, як і при додаванні нового DNS, і вони виконують ті ж самі валідації при збереженні даних.

  6. Також, ви можете видалити додатковий DNS, якщо він не використовується жодним із реєстрів. Якщо він використовується, спочатку змініть домен в відповідному реєстрі на інший. Для видалення потрібно натиснути на іконку корзини, що розташована навпроти обраного доданого DNS, і у вікні, що з’явиться, підтвердити дію.

  7. Після завершення всіх дій із додатковими DNS, натисніть кнопку Підтвердити для збереження змін. Після виконання валідаційних перевірок, якщо всі дані введені коректно, вони збережуться.

    В результаті сформується запит на оновлення конфігурації реєстру, який можна переглянути у розділі Керування Платформою > Запити на оновлення .

  8. Підтвердьте внесення змін та дочекайтеся виконання Jenkins-процесу MASTER-Build-cluster-mgmt, який і застосує конфігурацію.

3. Конфігурація DNS-імен компонента Keycloak для реєстру

Налаштовані у розділі Конфігурація DNS-імен компонента Keycloak для Платформи DNS-імена можуть використовуватися при створенні або редагуванні реєстру. Для цього:

  1. Увійдіть до інтерфейсу адмін-панелі Control Plane.

  2. Відкрийте розділ Реєстри та оберіть один із реєстрів зі списку для редагування.

  3. Натисніть Редагувати > Налаштування DNS .

  4. Знайдіть секцію Сервіс управління користувачами та ролями (Keycloak) та оберіть DNS-ім’я зі списку доступних.

  5. Натисніть Підтвердити, що зберегти зміни. Після виконання валідаційних перевірок, якщо всі дані введені коректно, вони збережуться.

    В результаті сформується запит на оновлення конфігурації реєстру, який можна переглянути у розділі Реєстри > Запити на оновлення .

  6. Підтвердьте внесення змін та дочекайтеся виконання Jenkins-процесу MASTER-Build-<registry-name>, який і застосує конфігурацію.

custom dns keycloak registry

4. Додаткова конфігурація за межами OpenShift-кластера та реєстру

Виконайте зовнішню конфігурацію за межами OpenShift-кластера та реєстру.

  1. Створіть CNAME-запис у свого постачальника DNS.

    Він має вказувати на Load Balancer прив’язаного до OpenShift роутера (HAProxy). Домен роутера OpenShift відрізняється для кожного кластера. Записи CNAME завжди повинні вказуватися на інше доменне ім’я, а не на IP-адресу.

    CNAME (Запис канонічного імені) — це тип запису ресурсу в системі доменних імен (DNS), який порівнює одне доменне ім’я (псевдонім) з іншим (канонічне ім’я).

    CNAME запис може виглядати так:

    www.example.net. CNAME www.example.com.

    Подивитись на поточні встановлені CNAME записи можна за допомогою сервісу dns.google.

    CNAME не може бути встановлений для apex-доменів (example.com), а піддомен повинен бути вказаний (www.example.com).

  2. Зверніться до служби підтримки технічного адміністратора інстансу Платформи через Ваш канал та залиште запит на додавання нової адреси до тестового віджета eu.iit.com.ua

    Нове DNS-ім’я Keycloak стає доступним після активації додаткової зовнішньої конфігурації.

    Зазвичай оновлення DNS-імен відбувається впродовж однієї години, хоча глобальне оновлення може тривати до 48 годин, а в окремих випадках до 72-х годин.

5. Застосування змін до конфігурації

Коли ви підтверджуєте зміни після налаштувань в адмін-панелі, на рівні Платформи та реєстру відбувається наступне:

Для налаштувань платформи:

  1. SSL-сертифікати, які ви завантажили для власних доменів Keycloak, зберігаються у Підсистемі управління секретами та шифруванням, HashiCorp Vault.

  2. У файлі deploy-templates/values.yaml компонента cluster-mgmt додаються записи із доменами та шляхами до SSL-сертифікатів, що відповідають прикладу:

    keycloak:
  customHosts:
    - host: keycloak.example.com
      certificatePath: registry-kv/....
    - host: keycloak-login.instance.com
      certificatePath: registry-kv/....
Для налаштувань реєстру:

  1. SSL-сертифікати, які ви завантажили для кастомних доменів Кабінетів надавача та отримувача послуг, також зберігаються до HashiCorp Vault.

  2. У файлі deploy-templates/values.yaml відповідного реєстрового репозиторію додаються записи із доменами та шляхами до SSL-сертифікатів, що відповідають прикладу:

    portals:
  officer:
    customHost:
       enabled: true
       host: officer.example.com
       certificatePath: registry-kv/....

Конвенція зберігання SSL-сертифікатів

Конвенція зберігання SSL-сертифікатів у HashiCorp Vault визначає шляхи для платформних та реєстрових сертифікатів.

Платформні сертифікати зберігаються за шляхом:

registry-kv/cluster/domains/<domain-name>

key:caCertificate value:<caValue>
key:certificate value:<certificateValue>
key:key value:<keyValue>

Реєстрові сертифікати зберігаються за шляхом:

registry-kv/registry/<registry-name>/domains/<portal-name>/<domain-name>

key:caCertificate value:<caValue>
key:certificate value:<certificateValue>
key:key value:<keyValue>