Конфигурация Keycloak при проблемах с HTTPS и сертификатами

Вопрос:

При попытке входа в веб-интерфейс возникают проблемы с доступом или происходят некорректные редиректы.

Возможные варианты проявления проблемы:

• Пустая страница веб-интерфейса с ошибкой «SSL_ERROR_BAD_CERT_DOMAIN» или «NET::ERR_CERT_COMMON_NAME_INVALID».
• Ссылка веб-страницы начинается с «http://», а не с «https://».
• Возникает ошибка «502».
• Возникает бесконечный редирект.

В чем причина данной проблемы и как ее можно решить?

Ответ:

Данная ситуация характерна для тестовых или нестандартизированных окружений, где отсутствует единая настройка SSL-сертификатов и проксирования.

Наиболее частые причины возникновения проблемы:

• некорректная настройка reverse proxy (nginx);
• отсутствие или недоверие к SSL-сертификату в окружении;
• неправильная передача заголовков X-Forwarded-*;
• несоответствие схемы HTTP/HTTPS между proxy и Keycloak;
• некорректная настройка hostname/URL параметров Keycloak.

Для обеспечения запуска Keycloak и доступа к интерфейсу в проблемных окружениях можно использовать упрощённую proxy-конфигурацию.

Перед настройкой упрощённой proxy-конфигурации рекомендуется проверить:

• открывается ли Keycloak напрямую по HTTP/HTTPS;
• корректно ли настроен reverse proxy (nginx);
• какие URL формируются в браузере (http или https);
• логи Keycloak на ошибки, связанные с hostname / proxy;
• наличие и корректность сертификатов.

Внимание! Данная конфигурация предназначена для тестового запуска и диагностики. Используется при проблемах с HTTPS, сертификатами или reverse proxy. Позволяет запустить Keycloak даже в не стандартизированной инфраструктуре.

В файле docker-compose.yml (блок keycloak – параметр environment) при необходимости (в зависимости от окружения) добавить или проверить переменные:

• KC_PROXY=edge
  
• KC_HTTP_ENABLED=true
  
• KC_PROXY_HEADERS=xforwarded

Если наблюдаются проблемы с редиректами или URL, то добавить или проверить следующие переменные:

• KC_HOSTNAME=${KEYCLOAK_DOMAIN}
  
• KC_HOSTNAME_URL=https://${KEYCLOAK_DOMAIN}
  
• KC_HOSTNAME_STRICT=false
  
• KC_HOSTNAME_STRICT_HTTPS=true

Также убедитесь, что nginx/reverse proxy корректно передаёт HTTPS-схему. Для изменений nginx нужно перейти в директорию ./DockerCompose/Nginx/conf.d и открыть файл nginx.conf.template.

В нем нужно добавить или проверить следующие параметры:

proxy_set_header X-Forwarded-Proto https;

proxy_set_header X-Forwarded-Port 443;

После внесения изменений нужно выполнить перезапуск сервиса указанной далее командой, после чего проверить повторно доступ к Keycloak через браузер:

./bs.sh --restart

После стабилизации окружения рекомендуется настроить:

• корректные SSL-сертификаты;
• reverse proxy;
• строгую конфигурацию hostname и HTTPS в Keycloak;
• единый стандарт обработки X-Forwarded-* заголовков.