Keycloak: развёртывание SSO и централизованное управление идентификацией

Привет, я Евгений Семёнов, директор ITFresh. Управлять учётными записями, когда в офисе развёрнуто 5-7 и более веб-сервисов, становится настоящим кошмаром, верно? Представьте: GitLab, Grafana, Nextcloud, Jenkins, Confluence, JIRA, да ещё и наш внутренний портал. Куча логинов, миллион паролей, постоянные просьбы сбросить доступ… Но Keycloak стирает эту головную боль! Он даёт единую точку аутентификации, настоящий сквозной SSO и великолепно дружит с Active Directory. За последние пять лет я лично развернул Keycloak в десятке компаний, и знаете, современную IT-инфраструктуру без него мы уже просто не мыслим.

Что такое Keycloak и зачем он нужен

Так что же это за зверь — Keycloak? Это мощнейшая open-source IAM-система от Red Hat. Она понимает и поддерживает все современные стандарты: OIDC (OpenID Connect), OAuth 2.0, SAML 2.0. Думайте о Keycloak как о надёжном посреднике. Он связывает ваши приложения со всеми мыслимыми источниками идентификации — будь то наш Active Directory, LDAP, какая-то база данных или даже привычные социальные сети.

Выгоды для корпоративного офиса:

• Представьте идеальную картину: ваш сотрудник логинится всего один раз. Да, используя свой привычный доменный пароль, и — вуаля! — получает бесшовный доступ ко всем необходимым сервисам. Никаких лишних вводов, никаких забытых комбинаций.
• Подключить новый сервис к вашей системе? Проще простого! Больше не нужно плодить локальные учётки, которые потом вечно теряются или забываются. Просто добавьте OIDC-клиент прямо в Keycloak — и готово. Это же гениально, не так ли?
• Хотите усилить безопасность? Запросто. Двухфакторная аутентификация (2FA) у нас включается централизованно. Один клик — и она активирована сразу для абсолютно всех ваших приложений. Больше никаких отдельных настроек для каждого сервиса.
• Когда сотрудник покидает компанию? Отлично, не забудьте отключить его учётную запись в Active Directory. Сразу после этого он моментально потеряет доступ ко всем корпоративным сервисам. Никаких рисков, никаких задержек.
• Забудьте о том, чтобы часами искать логи в разных системах! Весь аудит логинов, абсолютно по всем сервисам, доступен вам прямо из одной центральной консоли. Удобно, быстро и невероятно эффективно, согласитесь?
• Ваши пользователи больше не будут отвлекать IT-отдел по каждой мелочи. Теперь они могут самостоятельно, в удобном личном кабинете, поменять свой пароль или настроить двухфакторную аутентификацию. Мы же даём им контроль, верно? И снимаем лишнюю нагрузку с поддержки.

Установка Keycloak на Debian 12

Когда мы разворачиваем Keycloak для production, всегда берём официальные tarball-архивы или Docker-образ. Это проверено, это надёжно. И вот вам конкретный совет: если речь идёт о серьёзном корпоративном внедрении, не пожалейте выделить под Keycloak отдельный PostgreSQL. Он отлично справится с хранением данных.

# Установка Java 21 (требование Keycloak 24+)
sudo apt install -y openjdk-21-jre-headless postgresql-15

# PostgreSQL база
sudo -u postgres psql <<EOF
CREATE USER keycloak WITH PASSWORD 'ВашСтойкийПароль';
CREATE DATABASE keycloak OWNER keycloak ENCODING 'UTF8';
GRANT ALL PRIVILEGES ON DATABASE keycloak TO keycloak;
EOF

# Keycloak
sudo useradd -r -s /bin/false keycloak
sudo mkdir -p /opt/keycloak
cd /opt
sudo wget https://github.com/keycloak/keycloak/releases/download/26.0.0/keycloak-26.0.0.tar.gz
sudo tar xzf keycloak-26.0.0.tar.gz -C /opt/keycloak --strip-components=1
sudo chown -R keycloak:keycloak /opt/keycloak

Настройка конфигурации и systemd

# /opt/keycloak/conf/keycloak.conf
db=postgres
db-username=keycloak
db-password=ВашСтойкийПароль
db-url=jdbc:postgresql://localhost:5432/keycloak
hostname=sso.corp.ru
http-enabled=true
proxy-headers=xforwarded
http-relative-path=/auth

# Первый запуск в bootstrap-режиме
cd /opt/keycloak
sudo -u keycloak bin/kc.sh build
sudo KEYCLOAK_ADMIN=admin KEYCLOAK_ADMIN_PASSWORD=ПарольАдмина \
  -u keycloak bin/kc.sh start --optimized &

# systemd-юнит
sudo tee /etc/systemd/system/keycloak.service << EOF
[Unit]
Description=Keycloak Identity Server
After=network.target postgresql.service
[Service]
User=keycloak
Group=keycloak
ExecStart=/opt/keycloak/bin/kc.sh start --optimized
Restart=always
[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now keycloak

Имейте в виду: перед Keycloak обязательно ставится Nginx с TLS. Сам Keycloak никогда не должен быть напрямую доступен в открытый интернет. Это вопрос безопасности.

Realms: логическое разделение

Realm, что это такое? Это как отдельный, совершенно изолированный мир, где обитают пользователи, клиенты и их роли. В большинстве корпоративных проектов мы обычно создаём как минимум два таких Realm'а:

• master — служебный, только для администрирования Keycloak.
• corp — основной, с сотрудниками и приложениями компании.

Если у вас есть партнёры или клиенты, которым нужны свои отдельные учётные записи, для них создаётся отдельный Realm. Важно помнить: Realm'ы абсолютно изолированы. Пользователь из Realm A просто не сможет войти в Realm B. Всё чётко и раздельно.

Интеграция с Active Directory через LDAP

В любой компании наша главная задача — обеспечить сотрудникам вход в системы, используя их привычные доменные учётные записи. Мы делаем это просто, через User Federation. Никаких лишних паролей!

1. Чтобы настроить интеграцию, начните с простого пути: откройте Realm corp, затем перейдите в раздел User Federation и там выберите "Add LDAP provider". Всё по шагам, ничего сложного.
2. Vendor: Active Directory.
3. Connection URL: ldaps://dc01.corp.ru:636
4. Users DN: OU=Users,DC=corp,DC=ru
5. Bind DN: CN=keycloak-sync,OU=Service,DC=corp,DC=ru
6. В поле "Bind credentials" укажите пароль вашей служебной учётной записи. Это ключевой момент для безопасного подключения.
7. Обязательно установите параметр "Sync Registrations" в положение OFF. Почему? Потому что мы предполагаем, что пользователи должны создаваться и управляться исключительно в Active Directory, а не где-либо ещё.
8. Edit mode: READ_ONLY

Как только вы нажмёте 'Save', а потом 'Synchronize all users', то увидите, что уже через считанные секунды все доменные учётные записи появятся в Keycloak. При этом сама аутентификация при каждом входе пользователя будет делегироваться прямо в AD. Удобно!

# Дополнительный mapper для групп AD
# User Federation → ldap → Mappers → Add:
# - Name: groups
# - Mapper Type: group-ldap-mapper
# - LDAP Groups DN: OU=Groups,DC=corp,DC=ru
# - Group Object Classes: group
# - Membership LDAP Attribute: member
# - Membership User LDAP Attribute: sAMAccountName
# - User Groups Retrieve Strategy: LOAD_GROUPS_BY_MEMBER_ATTRIBUTE_RECURSIVELY

Подключение первого приложения: Grafana

Вот вам типичный сценарий: Grafana в роли OIDC-клиента. Что мы делаем? Просто создаём клиент прямо в Keycloak, а потом прописываем его параметры в Grafana. Всё.

# В Keycloak: Clients → Create → openid-connect
# Client ID: grafana
# Client Protocol: openid-connect
# Access Type: confidential
# Valid Redirect URIs: https://grafana.corp.ru/login/generic_oauth
# Web Origins: https://grafana.corp.ru
# Получаем Client Secret из вкладки Credentials

# В /etc/grafana/grafana.ini
[auth.generic_oauth]
enabled = true
name = Corp SSO
allow_sign_up = true
client_id = grafana
client_secret = xxxxx-xxxxx-xxxxx
scopes = openid profile email
auth_url = https://sso.corp.ru/auth/realms/corp/protocol/openid-connect/auth
token_url = https://sso.corp.ru/auth/realms/corp/protocol/openid-connect/token
api_url = https://sso.corp.ru/auth/realms/corp/protocol/openid-connect/userinfo
role_attribute_path = contains(groups[*], 'Grafana-Admins') && 'Admin' || 'Viewer'

После обычного рестарта grafana-server, на странице логина вдруг появляется новая кнопка: 'Log in with Corp SSO'. Кликаем. Нас перебрасывает на Keycloak. Если мы ещё не вошли, вводим наши доменные учётки — и вуаля! Сразу же возвращаемся в Grafana, уже полностью залогиненными. Быстро и без проблем.

Таблица: типовые клиенты для офиса

Двухфакторная аутентификация (2FA)

Keycloak — это про безопасность. Он поддерживает TOTP, WebAuthn, email-коды, Freeotp. На нашей практике мы всегда включаем двухфакторную аутентификацию (2FA) для всех администраторов. А для остальных сотрудников предлагаем её опционально, но настоятельно советуем.

1. Для настройки политики OTP пройдите по пути: Authentication, затем Policies, и там выберите OTP Policy. Какие параметры выставить? Мы обычно рекомендуем: тип TOTP, алгоритм SHA1, 6 цифр (Digits 6) и период 30 секунд (Period 30).
2. Теперь добавим сам шаг аутентификации. Следуем сюда: Authentication → Flows → Browser. А там найдите кнопку "Add step" и добавьте OTP Form, установив её как "Required". Вот так мы делаем 2FA обязательной.
3. А что, если вам не нужна обязательная 2FA для всех? Нет проблем! Вместо этого можно использовать Conditional OTP. Это очень удобно, если, например, вы хотите, чтобы двухфакторная аутентификация была обязательной только для вашей группы администраторов.

Как это всё работает? Очень просто. При первом входе в систему сотрудника попросят привязать Google Authenticator: нужно лишь отсканировать QR-код. После этого каждый последующий вход будет запрашивать 6-значный код из приложения. Надёжно и быстро.

Кейс: SSO для креативного агентства

Давайте рассмотрим конкретный пример. В сентябре 2025-го к нам обратилось одно креативное агентство. У них 55 сотрудников, и они активно пользуются десятком веб-сервисов: Nextcloud для хранения файлов, GitLab для контроля версий кода, Grafana для мониторинга, Kimai для учёта рабочего времени, Mautic в качестве CRM, Mattermost для внутренних чатов и Bookstack как внутренняя вики. Можете себе представить? На каждом сервисе были свои отдельные логины, свои пароли… Это был просто натуральный хаос, никаких нервов не хватит!

Что мы сделали? Всего за одну неделю развернули Keycloak. Он 'поднялся' на виртуалке с 2 vCPU и 4 ГБ RAM в дата-центре МТС, используя PostgreSQL для данных. Мы подключили LDAP к их существующей Active Directory, затем создали семь OIDC-клиентов — по одному для каждого приложения. Конечно, настроили группы доступа: Admins, Developers, Designers, Managers. И, разумеется, включили TOTP для всех администраторов и для наиболее чувствительных сервисов.

• У нас в ITFresh мы верим в простоту. Сотрудник один раз логинится утром – и всё! Получает мгновенный доступ ко всему, что нужно для работы. Никаких лишних телодвижений.
• Пришёл новый специалист? Нам достаточно добавить его в Active Directory. И знаете что? Он сразу автоматически попадает во все нужные ему сервисы. Меньше головной боли, больше продуктивности с первого дня.
• Безопасность прежде всего. Как только сотрудник увольняется, мы немедленно блокируем его учётную запись в Active Directory. Мгновенно? Да, именно так! Человек тут же теряет доступ ко всем приложениям. Никаких рисков утечки данных.
• Наш Helpdesk теперь дышит свободнее! Мы смогли сократить количество заявок на целых 60%, и это не шутка. Представьте, сколько раз люди раньше спрашивали: «Ой, а я опять забыл пароль от Nextcloud!» Теперь таких проблем стало в разы меньше. Реальное облегчение для ребят.
• И знаете, что самое приятное? Даже наш директор не остался в стороне. Он лично отметил: «Впервые у нас порядок с учётками». Это дорогого стоит, когда даже высшее руководство замечает результат нашей работы. Наконец-то всё разложено по полочкам!

В итоге, весь проект обошёлся клиенту в 180 000 рублей. И что важно: нам потребовалось всего 7 рабочих дней, при этом в стоимость уже было включено полноценное обучение их администраторов. Быстро, эффективно и с заботой о будущем.

Высокая доступность (HA)

Когда дело доходит до действительно больших инсталляций, мы всегда рекомендуем ставить Keycloak в кластере. Что это значит? Минимум два узла, а то и больше, которые работают с одной общей базой данных PostgreSQL. Перед ними обязательно ставим HAProxy, настроенный на sticky session по ключу — это важно! И вот зачем: если вдруг один из узлов неожиданно "упадёт", пользователи даже не заметят подмены. Они просто продолжат работать, переключившись на другой узел, и им не придётся повторно вводить свои данные.

# На каждом узле в keycloak.conf
cache-stack=kubernetes  # или tcp для standalone
cache-config-file=cache-ispn.xml

# Infinispan cache-конфигурация — общая для узлов
# cache-ispn.xml настраивает replicated cache для sessions
# Перед узлами HAProxy с sticky cookie KEYCLOAK_SESSION_HASH

Мониторинг и резервное копирование

Хотите знать, как поживает ваш Keycloak? Он сам с радостью расскажет! Система отлично экспортирует все нужные метрики, причём сразу в привычном формате Prometheus. Включить эту функцию — дело одной строчки в конфиге, серьёзно! А потом просто добавьте её в ваш scrape-список, и вся информация будет как на ладони.

# В keycloak.conf
metrics-enabled=true
health-enabled=true

# В prometheus.yml
- job_name: 'keycloak'
  metrics_path: '/metrics'
  static_configs:
    - targets: ['sso.corp.ru:8080']

# Бэкап — exports realms и dump PostgreSQL
sudo -u keycloak /opt/keycloak/bin/kc.sh export \
  --dir /var/backups/keycloak/$(date +%F) --realm corp
pg_dump -U keycloak keycloak | gzip > /var/backups/keycloak.sql.gz

FAQ — частые вопросы по Keycloak

Зачем корпоративному офису нужен Keycloak?

Keycloak даёт Single Sign-On для всех веб-приложений, которые поддерживают OIDC или SAML. Сотрудник логинится один раз доменным аккаунтом и имеет доступ к Grafana, GitLab, Nextcloud, Jenkins, JIRA без повторного ввода пароля.

Keycloak или ADFS?

ADFS — часть Microsoft, работает только на Windows Server, поддерживает в основном SAML и WS-Federation. Keycloak — кроссплатформенный, OIDC/SAML, бесплатный, с богатым веб-UI и возможностью кастомизации.

Нужен ли свой сервер под Keycloak?

Для small и medium офиса хватает виртуалки 2 vCPU / 4 ГБ RAM с PostgreSQL. Для больших инсталляций делается HA-кластер из 2+ узлов и отдельный PostgreSQL-кластер.

Как синхронизировать пользователей с Active Directory?

В Keycloak добавляется LDAP-провайдер, указываются DN и сервисная учётка для чтения. Пользователи и группы синхронизируются автоматически с заданным интервалом, аутентификация делегируется в AD.

Поддерживает ли Keycloak двухфакторную аутентификацию?

Да, через TOTP (Google Authenticator, Aegis), Webauthn (ключи YubiKey, Passkeys), SMS (через провайдера), email-код. Настраивается политиками через flow-редактор.