После обновления 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 и Keycloakhostname, path, TLS termination, health узла
Пароль принят, затем снова форма входаRealm Events: LOGIN_ERRORcookie domain, SameSite, sticky session, user storage
Ошибка invalid_redirect_uriClient settings и URL запросаredirect URI посимвольно, scheme, host и path
Callback получил code, tokens не выданыCODE_TO_TOKEN event и backend logclient type, secret, PKCE и issuer
Вход успешен, приложение отвергает tokenJWT 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 не заменяет тест существующих сессий.

Возврат трафика начинайте с одного клиента

  1. На canary-узле пройти login, refresh token и logout тестовой учётной записью.
  2. Повторить через каждый внешний IdP и хотя бы один confidential и public client.
  3. Сравнить LOGIN_ERROR по realm, clientId и error до и после переключения.
  4. Подать малую долю трафика и наблюдать code-to-token errors и latency базы.
  5. Откатывать образ вместе с совместимой схемой и конфигурацией только по заранее проверенному runbook.

Для предметного разбора подготовьте старую и новую версии, обезличенный startup command, discovery endpoints, один event error, client type и схему proxy. Export realm, база, cookies, authorization code и токены в переписку не нужны. По этим данным можно понять, безопасна ли правка конфигурации или потребуется восстановление тестовой копии перед повторной миграцией.

Проверенные источники