SSO

使用者以企业账号登录。Caddy 经 oauth2-proxy 对接客户 IdP，角色由 IdP 组映射，审计记录到人。企业版功能。

标准部署用网关自带的口令登录，账号在用户页管理。有 IdP 的企业改用 docker-compose.sso.yml，账号由 IdP 管理，网关不保存口令，每个人按 IdP 组获得角色。SSO 是企业版功能，试用许可也包含。

链路为：浏览器 → Caddy（TLS）→ oauth2-proxy → 网关 → Zabbix。oauth2-proxy 是 OIDC 反向代理：未登录的请求重定向到 IdP，登录成功后把身份写入请求头交给网关。网关只信任这些请求头，前提有三个：许可包含 SSO；请求带有 Caddy 注入的 RST_GATEWAY_SHARED_SECRET；请求来自 RST_TRUSTED_PROXIES 中的地址。任何能注入身份头的前置代理都可以替换 oauth2-proxy，以此对接 SAML 或 LDAP。

许可不包含 SSO 时（例如没有企业版许可，或许可过期），网关忽略身份头，退回产品自带的账号密码登录：使用者通过 oauth2-proxy 后还要以网关账号登录。因此 SSO 部署的 .env 中也要设置 RST_ADMIN_PASSWORD_HASH；没有设置时 admin 是出厂密码，只能从网关主机本机登录。

SSO 只决定谁能登录网关。网关对 Zabbix 的读写仍使用同一个 API token。在 Zabbix 侧，网关发起的确认、维护窗口和脚本执行记在该 Zabbix 账号名下，具体操作人记录在网关的调用审计中。

对接 IdP

前提条件

企业版或试用许可。
主机上有 oauth2-proxy 镜像 quay.io/oauth2-proxy/oauth2-proxy:v7.7.1。交付包不含该镜像：联网主机执行 docker pull；离线主机在联网机器上 docker pull 并 docker save，拷贝后 docker load。
已按交付包安装加载交付包中的镜像并生成 state/machine-id。deploy.sh 不配置 SSO，以下步骤手动完成。

步骤

在 IdP 中注册一个机密客户端（confidential client），回调 URI 为 https://<域名>/oauth2/callback。记录 client id、client secret 和 issuer URL。

在安装目录的 .env 中填写：

OIDC_ISSUER_URL=https://login.microsoftonline.com/<tenant>/v2.0
OIDC_CLIENT_ID=<client id>
OIDC_CLIENT_SECRET=<client secret>
OAUTH2_PROXY_SKIP_OIDC_DISCOVERY=false
OAUTH2_PROXY_COOKIE_SECRET=<openssl rand -base64 32 的输出>
OAUTH2_PROXY_REDIRECT_URL=https://<域名>/oauth2/callback
OAUTH2_PROXY_COOKIE_SECURE=true
OAUTH2_PROXY_REVERSE_PROXY=true
RST_RBAC_ADMIN_GROUPS=noc-admins

CADDY_SITE_ADDRESS、RST_GATEWAY_SHARED_SECRET、ZABBIX_URL、ZABBIX_TOKEN、LLM_API_KEY、LLM_MODEL 与标准部署相同。

启动 SSO 部署：
```
docker compose -f docker-compose.prod.yml down
docker compose -f docker-compose.sso.yml up -d
```
不要加 --profile bundled-idp，该 profile 只用于演示环境。不要加 --build，交付包中没有 Dockerfile。
打开 https://<域名>/v2/，确认跳转到 IdP 登录页，登录后右上角显示当前用户。

SSO 部署使用自己的状态卷 sso_gateway_state，与标准部署的 gateway_state 不是同一个卷。从标准部署切换到 SSO 时，设置、审计和许可激活记录不会带过去，许可需要重新激活。需要保留数据时，先用 scripts/backup.sh 备份，再以 COMPOSE_FILE=docker-compose.sso.yml 执行 scripts/restore.sh 恢复到新卷。

OAUTH2_PROXY_SKIP_OIDC_DISCOVERY 必须设为 false。compose 中的默认值 true 和默认端点只适用于演示环境的 Keycloak。

docker-compose.sso.yml 还把 oauth2-proxy 的 4180 端口发布在主机的 18180 端口上（明文 HTTP，演示用）。生产环境不要在防火墙上放通 18180，使用者只经 443 访问。

角色映射

IdP 的 groups claim 随身份传给网关，按下表映射为产品角色。用户属于多个已映射的组时，按管理员、分析员、审计员、查看者的顺序取第一个。不属于任何已映射组的用户按查看者处理，只读。

配置项	角色
`RST_RBAC_ADMIN_GROUPS`	管理员
`RST_RBAC_ANALYST_GROUPS`	分析员
`RST_RBAC_AUDITOR_GROUPS`	审计员
`RST_RBAC_VIEWER_GROUPS`	查看者

各角色的权限见用户。

docker-compose.sso.yml 把 .env 中的全部配置项传入网关，四个 RST_RBAC_*_GROUPS 都写在 .env 中。只配置管理员组时，其他人都是查看者。

配置项

配置项	说明
`OIDC_ISSUER_URL`、`OIDC_CLIENT_ID`、`OIDC_CLIENT_SECRET`	IdP 的 issuer 与客户端凭据
`OAUTH2_PROXY_SKIP_OIDC_DISCOVERY`	对接客户 IdP 时为 `false`
`OAUTH2_PROXY_COOKIE_SECRET`	会话 cookie 的加密密钥，用 `openssl rand -base64 32` 生成
`OAUTH2_PROXY_REDIRECT_URL`	与 IdP 中注册的回调 URI 一致
`OAUTH2_PROXY_COOKIE_SECURE`、`OAUTH2_PROXY_REVERSE_PROXY`	生产环境为 `true`
`RST_RBAC_ADMIN_GROUPS` 等	映射为各角色的 IdP 组，逗号分隔，见上文
`RST_SSO_ENFORCE`	默认 `true`，缺少身份的请求返回 401
`RST_SSO_USER_HEADER`、`RST_SSO_GROUPS_HEADER`	可选。更换前置代理时指定身份头名称

对接 AD 域和 SAML

使用者以 AD 或 LDAP 域账号登录时，在 Keycloak 中配置用户联邦：登录时通过 LDAP 绑定校验账号，再以 OIDC 交给 oauth2-proxy。微软 AD 的关键字段：vendor=ad、connectionUrl=ldaps://dc.corp.local:636、usernameLDAPAttribute=sAMAccountName、rdnLDAPAttribute=cn、uuidLDAPAttribute=objectGUID、userObjectClasses=person, organizationalPerson, user，bindDn 使用一个服务账号。再添加一个 group-ldap-mapper，把 AD 安全组映射到 groups claim，用于角色映射。

已有 SAML 2.0 IdP（例如 ADFS）时，在 Keycloak 的 Identity Providers 中添加 SAML v2.0，从客户 IdP 的元数据导入。生产环境开启签名校验并导入 IdP 签名证书。Keycloak 校验断言后以 OIDC 交给 oauth2-proxy，下游链路不变。

演示环境

docker-compose.sso.yml 的 bundled-idp profile 内置 Keycloak 与 OpenLDAP，只用于演示，打开 http://localhost:18180/。测试账号为 analyst / analyst123（Keycloak 本地账号）、analyst.ldap / Ldap123!（LDAP 联邦）和 saml.user / Saml123!（SAML 代理）。其中的 client secret、redirectUris: ["*"] 和 sslRequired: none 都是演示值，投产前改用客户 IdP。

登录后的差异

审计事件的 user 字段取自 SSO 身份，role 字段记录角色。
页面右上角显示当前用户，登出经 /oauth2/sign_out。
密码由 IdP 管理，网关不提供修改密码。
限流按用户计，不按来源 IP 计。

对接 IdP

角色映射

配置项

对接 AD 域和 SAML

演示环境

登录后的差异

本页内容