Keycloak — Identity & Access Management
Назначение сервиса
Keycloak обеспечивает аутентификацию и авторизацию (OIDC) для всех компонентов системы мониторинга (Grafana, Traefik Forward-Auth, Portainer и т.д.).
Структура каталогов
config/services/keycloak/deployment/docker/
├─ docker-compose.yaml # запуск Postgres + Keycloak
├─ .env_example # переменные окружения
└─ config/
├─ keycloak-restrict-client-auth.jar # custom SPI
└─ realm-export.json # (опц.) импорт realm
.env параметры
| Переменная | Описание |
|---|---|
POSTGRES_VERSION |
Образ Postgres (14, 15 ...) |
POSTGRES_PASSWORD |
Пароль для БД Keycloak |
KC_VERSION |
Тег контейнера Keycloak (21.x) |
KC_HOSTNAME / KC_PORT |
Домен/порт, которые увидят клиенты |
KC_REALM_NAME |
Название основного Realm |
KEYCLOAK_ADMIN / KEYCLOAK_ADMIN_PASSWORD |
учётка админа |
KC_LOG_LEVEL |
INFO,DEBUG |
Если домен доступен только через Traefik, оставьте секцию
ports:закомментированной.
Первый запуск
cd config/services/keycloak/deployment/docker
cp .env_example .env
# заполните версии и пароли
docker compose up -d keycloak-postgres keycloak
Время инициализации зависит от скорости сети (загрузка образов) и может занять до 2-3 минут.
Импорт realm
Если файл realm-export.json существует и смонтирован в /opt/keycloak/data/import/, Keycloak импортирует его при первом старте.
- Сгенерируйте экспорт:
bash /opt/keycloak/bin/kc.sh export --dir /tmp/export --realm <realm> - Поместите JSON в
config/realm-export.json. - Раскомментируйте volume в compose-файле.
Подключение клиентов
Для каждого сервиса создайте OIDC client с типом confidential и включите Standard Flow.
| Сервис | Redirect URI |
|---|---|
| Grafana | https://grafana.<domain>/login/generic_oauth |
| Traefik Forward-Auth | https://auth.<domain>/oauth2/callback |
| Portainer | https://portainer.<domain>/oauth/callback |
Обновление
docker compose pull keycloak keycloak-postgres
docker compose up -d
Backup базы данных
docker exec -t keycloak-postgres pg_dump -U keycloak keycloak > keycloak_$(date +%F).sql
Troubleshooting
- 404 Not Found после логина — убедитесь, что
KC_HOSTNAMEсовпадает с реальным доменом. - Invalid grant — проверьте secret клиента и clock skew.
- Java OutOfMemory — добавьте
-e KC_HEAP=1024в секцию environment.