如何在Keycloak中配置Azure PostgreSQL的强制SSL连接

我之前帮朋友解决过一模一样的问题，Keycloak对接Azure PostgreSQL因为强制SSL卡壳太常见了，下面给你分步讲怎么搞定：

问题根源 #

Azure PostgreSQL默认强制开启SSL连接，但Keycloak默认的PostgreSQL数据源配置没包含SSL相关参数，所以启动时就会抛出这个错误：

ERROR [org.jboss.msc.service.fail] (ServerService Thread Pool -- 49) MSC000001: Failed to start service jboss.undertow.deployment.default-server.default-host./auth: Caused by: org.postgresql.util.PSQLException: FATAL: SSL connection is required. Please specify SSL options and retry

咱们只需要给Keycloak的数据库连接添加上SSL参数就能解决。

方法一：直接通过docker run环境变量配置 #

这是最快的方式，启动容器时添加KC_DB_URL_PARAMS环境变量，把SSL参数传进去：

docker run -d \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  -e KC_DB=postgres \
  -e KC_DB_URL=jdbc:postgresql://你的Azure PostgreSQL主机名:5432/keycloak \
  -e KC_DB_USERNAME=你的数据库用户名 \
  -e KC_DB_PASSWORD=你的数据库密码 \
  -e KC_DB_URL_PARAMS=ssl=true&sslmode=require \
  quay.io/keycloak/keycloak:latest start-dev

重点就是KC_DB_URL_PARAMS=ssl=true&sslmode=require，这个参数正好匹配Azure PostgreSQL的强制SSL要求。

方法二：在自定义Dockerfile中固化SSL配置 #

如果你的自定义Dockerfile需要把配置固定下来，不用每次启动都输参数，可以在Dockerfile里预设环境变量：

FROM quay.io/keycloak/keycloak:latest

# 预设SSL连接参数
ENV KC_DB_URL_PARAMS="ssl=true&sslmode=require"

# 这里可以加你的其他自定义配置，比如复制主题、安装插件等

然后构建镜像并启动：

docker build -t my-custom-keycloak .
docker run -d \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  -e KC_DB=postgres \
  -e KC_DB_URL=jdbc:postgresql://你的Azure PostgreSQL主机名:5432/keycloak \
  -e KC_DB_USERNAME=你的数据库用户名 \
  -e KC_DB_PASSWORD=你的数据库密码 \
  my-custom-keycloak start-dev

特殊情况：需要SSL根证书的场景 #

有些Azure PostgreSQL实例会要求验证SSL根证书，这时候你需要先从Azure控制台下载对应的根证书（一般是BaltimoreCyberTrustRoot.crt.pem），然后挂载到容器里，再修改连接参数：

1. 下载证书到本地目录，比如./certs/
2. 启动时挂载证书并更新KC_DB_URL_PARAMS：

docker run -d \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  -e KC_DB=postgres \
  -e KC_DB_URL=jdbc:postgresql://你的Azure PostgreSQL主机名:5432/keycloak \
  -e KC_DB_USERNAME=你的数据库用户名 \
  -e KC_DB_PASSWORD=你的数据库密码 \
  -e KC_DB_URL_PARAMS=ssl=true&sslmode=require&sslrootcert=/opt/keycloak/certs/BaltimoreCyberTrustRoot.crt.pem \
  -v $(pwd)/certs/BaltimoreCyberTrustRoot.crt.pem:/opt/keycloak/certs/BaltimoreCyberTrustRoot.crt.pem \
  quay.io/keycloak/keycloak:latest start-dev

验证步骤 #

启动容器后，查看容器日志：

docker logs -f <容器ID>

如果看到类似Keycloak 22.0.5 (WildFly Core 18.0.4.Final) started in 1234ms的日志，说明连接成功了。如果还是报错，先检查：

• Azure PostgreSQL的防火墙规则是否允许容器所在的IP访问
• KC_DB_URL里的主机名、端口、数据库名是否正确
• 用户名和密码有没有输错
• SSL参数的格式是否正确（比如&符号有没有被转义，如果用的是Windows命令行，可能需要换成^&）

内容的提问来源于stack exchange，提问作者Sathya