ZITADEL项目中OIDC发现端点域名重写问题的解决方案

在ZITADEL身份管理平台从v2.58.0升级到v2.59.5版本后，部分用户遇到了OIDC发现端点域名重写异常的问题。本文将深入分析该问题的技术背景、产生原因及解决方案。

问题现象

在典型的多域名部署场景中：

• 前端UI部署在login-ui.example.com
• ZITADEL核心服务部署在zitadel.example.com

升级前访问前端域名的发现端点时，返回的URL会正确指向核心服务域名：

{
  "issuer": "https://zitadel.example.com",
  "authorization_endpoint": "https://zitadel.example.com/oauth/v2/authorize"
  // 其他端点...
}

升级后却发现返回的URL错误地保留了前端域名：

{
  "issuer": "https://login-ui.example.com",
  "authorization_endpoint": "https://login-ui.example.com/oauth/v2/authorize"
  // 其他端点...
}

技术背景

ZITADEL的域名重写机制主要用于：

1. 支持反向代理部署架构
2. 实现前端与API服务的域名分离
3. 确保OIDC发现端点返回正确的服务端点

在v2.59版本中，项目团队移除了对x-zitadel-forwarded头的支持，这是导致部分现有部署出现兼容性问题的根本原因。

解决方案

经过技术验证，正确的配置方式如下：

1. 移除旧版头信息
   不再使用已被废弃的x-zitadel-instance-host头，否则会触发"unable to set instance using origin"错误。

2. 使用新版头信息
   改用x-zitadel-public-host头，其值为需要重写的目标域名（如zitadel.example.com）。

3. 配置信任域
   必须通过管理API将目标域名添加到系统的信任域列表中，这是安全机制的要求。

4. 环境变量配置
   虽然ZITADEL_INSTANCEHOSTHEADERS和ZITADEL_PUBLICHOSTHEADERS环境变量在某些场景下有用，但在本案例中不是关键配置项。

实现原理

新版的重写机制工作流程：

1. 请求到达反向代理时携带x-zitadel-public-host头
2. ZITADEL验证该域名是否在信任域列表中
3. 通过验证后，系统将发现端点中的所有URL重写为指定域名
4. 返回给客户端的响应中包含重写后的正确端点

最佳实践建议

1. 升级前充分测试：在非生产环境验证所有OIDC相关功能
2. 检查现有代理配置：确保使用正确的HTTP头
3. 维护信任域列表：定期审核系统信任的域名
4. 监控发现端点：建立自动化检查机制验证返回的URL

该解决方案已在实际生产环境中验证有效，特别适用于需要自定义前端域名同时保持后端服务稳定的部署架构。通过正确理解ZITADEL的域名重写机制，可以构建更灵活、更安全的身份管理系统。