После обновления Keycloak не меняйте сразу пароли и client secrets. Сначала проведите один вход тестовой учётной записью и отметьте последнюю успешную точку: открылась ли страница авторизации, принялся ли пароль, вернулся ли браузер на callback и обменял ли backend code на tokens. Так проблема сужается до одного участка, а пользователи не теряют рабочие учётные данные.
Для этого же запроса запишите время с часовым поясом, realm, client_id, фактический redirect_uri и ошибку из Events. Значения access token, authorization code и cookies сохранять не нужно. Если старый и новый узлы ещё работают параллельно, добавьте к записи hostname узла: смешение версий во время неподдерживаемого rolling update способно дать плавающий симптом.
Последняя успешная точка определяет владельца ошибки
| Что увидел пользователь | Где искать подтверждение | Что сравнить после обновления |
|---|---|---|
| Страница Keycloak не открылась | Access log proxy и Keycloak | hostname, path, TLS termination, health узла |
| Пароль принят, затем снова форма входа | Realm Events: LOGIN_ERROR | cookie domain, SameSite, sticky session, user storage |
| Ошибка invalid_redirect_uri | Client settings и URL запроса | redirect URI посимвольно, scheme, host и path |
| Callback получил code, tokens не выданы | CODE_TO_TOKEN event и backend log | client type, secret, PKCE и issuer |
| Вход успешен, приложение отвергает token | JWT header/claims без подписи токена | issuer, audience, ключи и adapter/library |
HTTP 200 у главной страницы Keycloak доказывает только доступность процесса. Он не проверяет конкретный realm, клиент, внешний IdP и обмен code на token. Поэтому health endpoint используйте как первый фильтр, а не как заключение о работоспособности SSO.
Discovery-документ показывает фактический внешний адрес
curl -sS https://sso.example.com/realms/acme/.well-known/openid-configuration
# Сравнить в ответе:
# issuer
# authorization_endpoint
# token_endpoint
# jwks_uriКоманда безопасна для общедоступного discovery endpoint и не содержит credential. Если issuer или endpoints указывают внутренний host, HTTP вместо HTTPS либо старый context path, исправляйте модель внешнего адреса и proxy headers. Подмена issuer только в приложении маскирует рассогласование и обычно ломает следующего клиента.
Обновление включает схему базы, расширения и клиентские библиотеки
Официальный upgrade guide требует сначала прочитать migration changes, затем обновлять сервер и отдельно оценивать adapters и client libraries. Перед миграцией базы старые узлы должны быть остановлены, если выбранный переход не поддерживает rolling update. Зафиксируйте образ, startup options, JDBC driver, custom provider JAR и checksum темы: бинарник Keycloak редко является единственной переменной.
- Проверить, завершилась ли миграция схемы и нет ли database exception до первого LOGIN_ERROR.
- Сопоставить версии всех pod или VM, а не только узла, открытого в административной консоли.
- Временно исключить custom authenticator на копии realm, если ошибка возникает до проверки credential.
- Проверить внешний IdP отдельно: его callback и подпись metadata могли остаться на старом адресе.
- Не удалять пользовательские сессии до фиксации события: это стирает важный признак, но не исправляет конфигурацию.
Reverse proxy должен сообщать Keycloak правдивую схему и host
За TLS-терминатором Keycloak строит ссылки по hostname и доверенным Forwarded либо X-Forwarded-* headers. Proxy обязан перезаписывать эти заголовки, а не принимать их от внешнего клиента. Если публичный путь отличается от внутреннего, согласуйте hostname с полным URL, X-Forwarded-Prefix или http-relative-path по одной схеме. Иначе login page может открыться, но callback и cookie получат другой origin.
Сравнивайте полный URL запроса до и после обновления. Ошибку часто выдаёт одна деталь: лишний /auth, другой порт, смена http на https или новый hostname-admin. Проверяйте в отдельном окне без расширений, но обязательно оставьте обычный сценарий в приёмке: incognito не заменяет тест существующих сессий.
Возврат трафика начинайте с одного клиента
- На canary-узле пройти login, refresh token и logout тестовой учётной записью.
- Повторить через каждый внешний IdP и хотя бы один confidential и public client.
- Сравнить LOGIN_ERROR по realm, clientId и error до и после переключения.
- Подать малую долю трафика и наблюдать code-to-token errors и latency базы.
- Откатывать образ вместе с совместимой схемой и конфигурацией только по заранее проверенному runbook.
Для предметного разбора подготовьте старую и новую версии, обезличенный startup command, discovery endpoints, один event error, client type и схему proxy. Export realm, база, cookies, authorization code и токены в переписку не нужны. По этим данным можно понять, безопасна ли правка конфигурации или потребуется восстановление тестовой копии перед повторной миграцией.