查看 Markdown
POST/api/sso/createTicket

创建免登票据

在客户自有登录体系验密成功后调用,换取一次性免登地址 loginUrl,交给浏览器顶层跳转(新窗口或当前窗口)即可免登进入控制台。

票据一次性有效且默认 60 秒过期,请在用户点击进入时实时换票,不要缓存或复用 loginUrl;过期或已被使用的地址访问时会提示「登录链接已失效」,此时引导用户回到原系统重新点击入口即可。

externalUserId 必须是客户体系内稳定不可变的用户唯一标识(禁止手机号、邮箱等可变信息),且在租户内全局唯一;首次出现的标识平台会自动开户并创建独立身份主体,无需预先同步用户名单。

响应中的 principalId 建议留存:作为 OpenAPI 调用的 X-Principal-Id 传入,即可与用户页面操作共享同一主体、同一份会话与记忆。

注意:受「一个用户仅归属一个应用空间」的约束,若该 externalUserId 已归属本租户下的其他应用,接口返回 409 错误。

请求参数

请求体(JSON)4 个字段

externalUserIdstringrequired

客户自有登录体系内的用户唯一标识。必须是稳定且不可变的标识(如自增ID、UUID),禁止使用手机号、邮箱等可变信息;需在租户内全局唯一。首次出现时平台自动为该用户开户,后续换票复用同一身份、同一份会话与记忆

nicknamestringnullable

用户昵称,选填。每次换票携带最新值即可覆盖平台侧昵称;首次开户不传时默认取 externalUserId

returnPathstringnullable

登录成功后跳转的站内相对路径,选填,不传则进入首页。必须以 / 开头的站内相对路径(不支持绝对 URL,也不能以 // 开头)

homeUrlstringnullable

客户系统首页地址,选填。用户在点金内点击「退出登录」后,会落到「已退出」提示页,该页展示一个指向本地址的「返回原系统」按钮;不传则展示「重新登录」。支持 http:// 与 https://(客户内网系统常为 http)。注意:点金侧登出只结束点金的会话,不会影响您自有系统的登录态,用户返回原系统后再次点击入口会立即免登进入

响应

200

httpStatusCodeintegernullable

HTTP状态码

messagestringnullable

响应消息

响应数据

successbooleannullable

是否成功

requestIdstringnullable

上游请求ID,用于跨系统链路追踪排查问题

errCodestringnullable

上游错误码,前端可据此做特殊UI处理

查看 Markdown
GET/api/sso/login

免登入口

本接口由浏览器顶层跳转访问,不是服务端调用接口:客户后端拿到换票响应的 loginUrl 后, 直接让用户浏览器打开该地址即可,无需自行解析或转发。

访问后消费票据、建立会话,并 302 跳转到控制台页面(换票时指定了 returnPath 则落在该路径,否则进入首页)。 票据无效、已过期或已被使用时返回 403「登录链接已失效,请从原系统重新进入」,此时应引导用户回原系统重新进入。

请求参数

Query 参数1 个字段

ticketstringrequired

换票接口签发的一次性票据