如何将对接Google Workspace的Keycloak SSO URL自定义为自有域名

1. 配置DNS解析 #

别纠结CNAME了，直接给子域名sso.domain.com添加A记录，指向你的Keycloak服务器公网IP。可以用nslookup sso.domain.com命令验证解析是否生效。

2. 部署反向代理（以Nginx为例） #

Keycloak默认用8443端口，需要通过反向代理把sso.domain.com:443的请求转发到Keycloak的8443端口，同时配置SSL证书（推荐用Let's Encrypt免费证书）。

下面是Nginx配置示例，保存到/etc/nginx/sites-available/sso.domain.com：

server {
    listen 443 ssl;
    server_name sso.domain.com;

    # 替换成你的SSL证书路径
    ssl_certificate /etc/letsencrypt/live/sso.domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/sso.domain.com/privkey.pem;

    location / {
        proxy_pass https://localhost:8443;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

server {
    listen 80;
    server_name sso.domain.com;
    # 强制跳转HTTPS
    return 301 https://$host$request_uri;
}

配置完成后启用站点并重启Nginx：

ln -s /etc/nginx/sites-available/sso.domain.com /etc/nginx/sites-enabled/
nginx -t
systemctl restart nginx

3. 修改Keycloak服务器配置 #

Keycloak默认会用自身绑定的IP和端口生成URL，必须修改配置让它识别反向代理的域名：

传统非容器部署

找到Keycloak安装目录下的standalone/configuration/standalone.xml（集群部署用standalone-ha.xml），修改两处配置：

• 找到<subsystem xmlns="urn:jboss:domain:undertow:12.0">下的<server name="default-server">，添加proxy-address-forwarding="true"：

<server name="default-server" proxy-address-forwarding="true">

• 找到<spi name="hostname">，设置frontendUrl为你的域名：

<spi name="hostname">
    <default-provider>default</default-provider>
    <providers>
        <provider name="default">
            <properties>
                <!-- Keycloak 17及以上版本不需要加/auth路径 -->
                <property name="frontendUrl" value="https://sso.domain.com/auth"/>
            </properties>
        </provider>
    </providers>
</spi>

修改完成后重启Keycloak服务。

Docker/Kubernetes容器部署

启动容器时添加环境变量：

# Keycloak 17+使用quay.io/keycloak/keycloak镜像
docker run -e KEYCLOAK_FRONTEND_URL=https://sso.domain.com/auth -e PROXY_ADDRESS_FORWARDING=true ... jboss/keycloak:latest

4. 验证Realm的SAML端点 #

登录Keycloak后台，进入demo Realm，点击左侧菜单的SAML 2.0 Identity Provider Metadata，查看XML里的SingleSignOnService和SingleLogoutService地址，确认已变为https://sso.domain.com/auth/realms/demo/protocol/saml（对应新版本路径则去掉/auth）。

5. 更新Google Workspace配置 #

把Google Workspace中原有的SSO登录/退出URL替换为新的域名地址，保存后测试登录流程即可。

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