Есть несколько вариантов.
Вариант 1
client ↓ HTTPS Keycloak
Keycloak сам использует сертификат и слушает HTTPS.
Вариант 2
client ↓ HTTPS reverse proxy ↓ HTTP Keycloak
Такой вариант часто называют edge termination.
Например:
Internet ↓ 443 nginx ↓ 8080 Keycloak
Тогда Keycloak может запускаться с включённым HTTP:
http-enabled=true
но порт 8080 должен быть доступен только reverse proxy, а не всему миру.
Вариант 3
client ↓ HTTPS reverse proxy ↓ HTTPS Keycloak
Это TLS re-encryption.
Какой вариант выбрать — зависит от требований инфраструктуры.
Главное:
решить это до настройки Keycloak и reverse proxy, а не независимо друг от друга.
12. Reverse proxy и Keycloak должны одинаково понимать внешний запрос
Представим:
user ↓ https://sso.example.ru ↓ nginx ↓ http://keycloak01:8080
Для пользователя запрос был:
HTTPS host=sso.example.ru port=443
Но Keycloak физически получает:
HTTP host=keycloak01 port=8080
Если ничего больше не настроить, он может неправильно сформировать внешние URL.
Поэтому reverse proxy передаёт информацию о первоначальном запросе через заголовки:
Forwarded
или:
X-Forwarded-*
а Keycloak нужно явно настроить на их обработку.
Например:
proxy-headers=xforwarded
При этом reverse proxy должен перезаписывать эти заголовки, а не слепо доверять значениям от клиента.
Иначе конфигурация превращается уже в проблему безопасности.
13. Один из самых частых источников проблем — неправильный hostname
Симптомы могут выглядеть совершенно по-разному:
- Invalid redirect URI;
- неправильный issuer;
- ссылки ведут не на тот адрес;
- HTTP вместо HTTPS;
- неверный порт;
- Admin Console открывается некорректно;
- после reverse proxy появляются ошибки origin check.
На первый взгляд кажется:
проблема в OIDC или клиенте.
А первопричина может быть в модели:
external URL
↓
reverse proxy
↓
hostname / proxy headers
Поэтому hostname — один из первых параметров, который стоит проектировать.
14. Не публикуйте management interface наружу
У современного Keycloak есть отдельный management interface.
По умолчанию его порт:
9000
Там могут находиться:
/health /metrics
Это удобно для monitoring и load balancer.
Но схема должна быть примерно такой:
monitoring
↓
:9000
Internet
X
:9000
То есть management interface относится к внутренней инфраструктуре.
Reverse proxy обычно не должен публиковать его наружу.
15. Health checks лучше предусмотреть сразу
Keycloak умеет публиковать разные health endpoints.
Например:
/health/started /health/live /health/ready
Они отвечают на разные вопросы.
started
процесс завершил начальную фазу старта?
live
экземпляр вообще жизнеспособен?
ready
готов ли он принимать пользовательский трафик?
Особенно полезен:
/health/ready
для load balancer.
Потому что:
Java process running
≠
Keycloak готов обслуживать login requests
Это снова наш привычный принцип ИНФРАСКОПИИ.
16. Metrics тоже лучше включить до появления проблемы
Keycloak умеет предоставлять метрики для систем мониторинга.
Например:
metrics-enabled=true health-enabled=true
Тогда мониторинг можно строить не только вокруг:
systemd active
но и вокруг:
- JVM;
- HTTP;
- database pool;
- cache;
- состояния самого Keycloak.
Гораздо полезнее увидеть деградацию до момента:
пользователи массово перестали входить.
Это снова наш привычный принцип ИНФРАСКОПИИ.
17. Перед установкой нужно решить судьбу reverse proxy
Не:
«потом поставим nginx».
А заранее определить:
Internet?
Corporate LAN?
VPN?
↓
reverse proxy / load balancer
↓
Keycloak
И ответить:
- кто принимает
443; - где лежит TLS certificate;
- каким портом proxy ходит к Keycloak;
- какие headers передаются;
- доступна ли Admin Console публично;
- какие URL публикуются клиентам;
- кто имеет доступ к management port.