统一认证端点
网关自带 OAuth2 / OIDC 授权服务器。第三方应用按「标准 / OIDC」一列对接即可;
「MaxKey 兼容」一列是给那些照抄 MaxKey 文档配好了 URL 的应用准备的别名:路径不同,响应格式对齐 MaxKey
(令牌为裸对象、用户信息扁平字段),改一处地址就能切过来。
接入方式一:应用自己做 OAuth2 客户端
适合 Grafana、GitLab、自研 Web 应用这类本身就支持 OIDC 的系统。它们只关心三件事:
Discovery 地址、client_id、client_secret(公开客户端用 PKCE 代替)。
- 在「OAuth 应用」页新建接入方,填好回调地址与 scope,复制返回的客户端密钥。
- 把应用的 OIDC 配置指向
/.well-known/openid-configuration,
或分别填授权 / 令牌 / 用户信息三个端点。
- 首次访问时应用会把浏览器送到授权端点;网关侧未登录会让用户登录,登录成功后带
code 回跳,应用用 code 换令牌。
- 令牌是 JWT(HS256)。校验方式二选一:调
/oauth/introspect(需客户端鉴权),
或对 id_token 用 client_secret 本地验签。
接入方式二:IAP 零改造接入
应用完全不写认证代码,只读网关注入的请求头。适合内部系统、遗留系统。网关在 access 阶段
完成门禁:无身份直接 401 并由 error_page 跳登录页;有身份则注入五个头,且覆盖客户端伪造的同名头。
location / {
sso_iap on; # 开启身份感知代理
proxy_pass http://127.0.0.1:8080; # 你的应用
proxy_set_header Host $host;
# 身份注入:客户端自己发的这几个头会被覆盖
proxy_set_header X-Auth-User $auth_user; # 登录账号
proxy_set_header X-Auth-Sub $auth_sub; # OIDC sub(同 User)
proxy_set_header X-Auth-Email $auth_email;
proxy_set_header X-Auth-Groups $auth_groups; # 逗号分隔的用户组
proxy_set_header X-Auth-Token $auth_token; # 可再次验签的 access_token
error_page 401 = @oauth_login; # 未登录 → 跳统一登录页并回跳
}
location @oauth_login {
return 302 "https://sso.example.com/login?redirect=$scheme://$host$request_uri";
}
注意:注入头只在经过网关的请求上可信。应用若可被直连(绕过网关),
任何人都能伪造这几个头——生产上必须让应用只监听内网,或只接受来自网关的连接。
跨子域 SSO
同一个 SSO 会话要给多个子站用(a.example.com、b.example.com),
必须把 SSO Cookie 的 Domain 设成带点的父域,否则第二个站点拿不到 Cookie,表现为「刚登录又被弹回登录页」。
env OAUTH_COOKIE_DOMAIN; # nginx 会剥掉环境变量,必须显式声明
export OAUTH_COOKIE_DOMAIN=.example.com
export OAUTH_SIGNING_SECRET=$(openssl rand -hex 32) # 生产必设;不设则每次重启令牌全失效
export OAUTH_ISSUER=https://sso.example.com
接入方式三:CAS 1.0 / 2.0(老系统单点登录)
老一代应用(多为 Java 遗留系统)走 CAS 协议接入:应用把浏览器送到
/cas/login?service=回调地址,网关完成登录后带一次性票据 ST-… 回跳;
应用再用 /cas/serviceValidate 把票据换成账号名即可。票据是单次有效的,
用完即废,不能被重放。
接入方式四:SCIM 2.0(供第三方 IdP 自动供给账号)
若上游身份源(如 Okta、阿里 IDaaS、飞书)支持 SCIM,可把网关登记为一个 SCIM 服务:
由 IdP 负责「建号 / 改号 / 停用」,无需人工维护。这些端点需要管理员会话,
也不应直接暴露到公网——生产建议走内网或加白名单。
认证源:LDAP / AD
把企业目录(OpenLDAP / Active Directory)作为兜底认证源:只有在本地口令校验
失败时才去 LDAP 试一次,因此不影响已有账号;未启用时行为完全不变。
该能力由网关环境变量配置(不在此页维护);启用且开自动建号后,LDAP 认证成功但本地无账号时会建号。
env LDAP_ENABLED; # 1 = 启用 LDAP 兜底认证
env LDAP_SERVER; # 如 ldap://127.0.0.1
env LDAP_PORT; # 缺省 389
env LDAP_BASE_DN; # 如 dc=example,dc=com
env LDAP_USER_DN_TEMPLATE; # 如 uid={user},ou=people,dc=example,dc=com
env LDAP_AUTO_CREATE; # 1 = LDAP 认证成功后自动建号