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

Семёнов Евгений Сергеевич, директор АйТи Фреш. Когда в офисе становится больше 5-7 веб-сервисов (GitLab, Grafana, Nextcloud, Jenkins, Confluence, JIRA, внутренний портал) — управление учётками превращается в кошмар. Каждая система — свои логины, свои пароли, свои забытые и сброшенные. Keycloak решает это одним махом: единая точка аутентификации, сквозной SSO, интеграция с AD. За последние 5 лет я развернул Keycloak в десятке компаний и больше не представляю современную инфраструктуру без него.

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

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

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

• Сотрудник логинится один раз доменным паролем и получает доступ ко всем сервисам.
• Подключение нового сервиса — добавить OIDC-клиент в Keycloak, больше никаких локальных учёток.
• 2FA включается централизованно для всех приложений сразу.
• Уволили сотрудника — отключили в AD, и он теряет доступ ко всему.
• Аудит логинов во всех системах — из одной консоли.
• Самообслуживание пользователей — смена пароля, настройка 2FA в личном кабинете.

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

Я ставлю Keycloak в production из официальных tarball-архивов или Docker-образа. Для корпоративного использования рекомендую отдельный 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 — изолированное пространство пользователей, клиентов, ролей. В корпоративе обычно делают два:

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

Если есть партнёры или клиенты с отдельной учёткой — для них отдельный realm. Realms полностью изолированы: пользователь из 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 (пользователи создаются только в AD)
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. Authentication → Policies → OTP Policy → TOTP, Algorithm SHA1, Digits 6, Period 30.
2. Authentication → Flows → Browser → Add step → OTP Form (Required).
3. Или Conditional OTP — только для группы admins.

После этого при логине сотрудника в первый раз просят привязать Google Authenticator, сканируется QR-код, и далее каждый логин требует 6-значный код.

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

В сентябре 2025 клиент — креативное агентство, 55 сотрудников, работа с десятком веб-сервисов: Nextcloud (файлы), GitLab (код), Grafana (мониторинг), Kimai (учёт времени), Mautic (CRM), Mattermost (чат), Bookstack (вики). На каждом — свои логины, всё из хаоса.

За неделю мы развернули Keycloak на виртуалке 2 vCPU / 4 ГБ RAM в дата-центре МТС с PostgreSQL. Подключили LDAP к существующей AD, создали 7 OIDC-клиентов под каждое приложение, настроили группы доступа (Admins, Developers, Designers, Managers). Включили TOTP для администраторов и чувствительных сервисов.

• Сотрудник логинится утром один раз — получает доступ ко всему.
• Новый сотрудник добавляется в AD — автоматически попадает в нужные сервисы.
• Уволенный блокируется в AD — теряет доступ ко всем приложениям мгновенно.
• 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-редактор.