接入前准备

  • 申请应用client_id 和 client_secret，需提供如下信息进行申请
    应用名称：xxxx
应用回调地址：https://xxxx  OR http://xxxx
应用退出接口地址：https://xxxx  OR http://xxxx
  • 申请SSO接口文档权限，了解企业 SSO 服务支持的协议及参数
  • 明确自身应用类型（Web、前后端分离、无服务端）

第一步：获取 code

web授权登录接口

接口地址

域名：https://login.mindoffice.cn/

请求方式

GET

请求参数

参数名称 是否必须 示例 备注
client_id 是 客户端ID
response_type 是 code 授权类型
redirect_uri 是 应用重定向地址，在用户授权成功后会跳转至该地址，同时会携带 code 以及 state 参数（如有传递 state 参数）。请注意：该地址需经过 URL 编码
scope 否 openid 授权范围
state 是 用来维护请求和回调之间状态的附加字符串，在授权完成回调时会原样回传此参数。应用可以根据此字符串来判断上下文关系，同时该参数也可以用以防止 CSRF 攻击，请务必校验 state 参数前后是否一致。
codeChallenge 否 用于通过 PKCE（Proof Key for Code Exchange）流程增强授权码的安全性。pkce接入指南
platform 是 平台ID, 用户设备所属平台：1：Android 2：iOS, 3:windows 4:xos 5：Web 6：mini_web 7：linux 8：android_pad, 9：ipad 0：其他平台

返回值

{
    "code": 0,
    "data": {},
    "msg": "操作成功",
    "req_id": "vpl8r3raz1752651380681bskj3qdn93d73mft"
}

第二步：换取access_token

接口地址

域名：https://login.mindoffice.cn/

uri：/account/api/token

请求方式

POST

请求参数

Body:

名称 类型 是否必须 默认值 备注 其他信息
client_id string 必须 客户端appid
client_secret string 必须 客户端秘钥
grant_type string 必须 获取token：authorization_code；刷新token: refresh_token
code string 必须 授权码
refresh_token string 非必须 刷新access_token时使用
redirect_uri string 非必须 应用重定向地址，在用户授权成功后会跳转至该地址，同时会携带 code 以及 state 参数（如有传递 state 参数）。请注意：该地址需经过 URL 编码
code_verifier string 非必须 PKCE pkce接入指南
code_challenge string 非必须 PKCE pkce接入指南
code_challenge_method null 非必须 PKCE pkce接入指南

返回值

{
    "code": 0,
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJVc2VySUQiOiI4NnBvbno3aHB0Zmg5ZXhzX2FpcG50c2pmaHRnY3Rlcm0iLCJUb2tlblR5cGUiOiJhY2Nlc3NfdG9rZW4iLCJOb25jZSI6IiIsIkJ1ZmZlclRpbWUiOjAsImlzcyI6InNzbyIsImF1ZCI6WyI0ZGYxMzkwYzJiNWU5MGUzYzc4MiJdLCJleHAiOjE3MDQ4NTIwODMsIm5iZiI6MTcwMjI2MDA4M30.mOcbUnMs5cVdqPrI21JOpYA13MsnxTW2gl5enHbG384",
        "token_type": "Bearer",
        "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJVc2VySUQiOiI4NnBvbno3aHB0Zmg5ZXhzX2FpcG50c2pmaHRnY3Rlcm0iLCJUb2tlblR5cGUiOiJpZF90b2tlbiIsIk5vbmNlIjoiIiwiQnVmZmVyVGltZSI6MCwiaXNzIjoic3NvIiwiYXVkIjpbIjRkZjEzOTBjMmI1ZTkwZTNjNzgyIl0sImV4cCI6MTcwNDg1MzQ2OSwibmJmIjoxNzAyMjYxNDY5fQ.KJz-LzwSSR-7h0E9UABRtJdIxE-wS3dC_wtMMv4MgoU",
        "expires_in": 2592000,
        "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJVc2VySUQiOiI4NnBvbno3aHB0Zmg5ZXhzX2FpcG50c2pmaHRnY3Rlcm0iLCJUb2tlblR5cGUiOiJyZWZyZXNoX3Rva2VuIiwiTm9uY2UiOiIiLCJCdWZmZXJUaW1lIjowLCJpc3MiOiJzc28iLCJhdWQiOlsiNGRmMTM5MGMyYjVlOTBlM2M3ODIiXSwiZXhwIjoxNzAyODM2MDgzLCJuYmYiOjE3MDIyNjAwODN9.5OCKOaFwlnDSIDhjn-jP9SL4-_LCRpyUVXWalwEfZGQ",
        "scope": "read",
        "uid": "86ponz7hptfh9exs_aipntsjfhtgcterm"
    },
    "msg": "操作成功",
    "trace_id": "018c56b0-b175-7c19-88c8-fc1c94ff93f6"
}

第三步：获取用户信息

接口地址

域名：https://login.mindoffice.cn/

uri：/account/api/userInfo

请求方式

POST

请求参数

Headers：

参数名称 参数值 是否必须 示例 备注
Content-Type application/json 是
Authorization 是 Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJVc2VySUQiOiIxYXNkZmpxMzlyODl3ZXVmMTFfOTF0 access_token

body：

{
  "userId": ""
}

返回值

{
    "code": 0,
    "data": {
        "user_center_id": 40130193230351740,
        "team_id": 44,
        "code": "xqqauj9gyffc7ed6",
        "base_user_id": "tj6q4yx7i3dzdccg",
        "team_user_id": "6uxcg4ebnbbc3yowxyugpx55io",
        "icon": "https://s1-imfile.im30.net/6uxcg4ebnbbc3yowxyugpx55io?r=1707028838",
        "name": "哈尔",
        "nick_name": "哈尔",
        "phone_number": "17606210507",
        "email": "haer@test.com",
        "is_owner": 2,
        "status": 1,
        "last_login_at": 0,
        "client_last_login_at": 1753762819714,
        "session_token": "B7XrKo6DhgkFqOu3h4FV-N1EkVsZHUV5IS5IYJt2wQeOY8O9qnKSDpkHzo8PB2x7",
        "device_id": ""
    },
    "msg": "success",
    "trace_id": "35825a94-d0c0-4937-95c1-b4ae753766eb"
}

标准接入流程

  1. 应用信息登记，申请应用client_id和client_secret
    1. 接入方需向SSO平台管理员提供：
      1. 应用名称（App Name）
      2. 回调地址（redirect_uri，前后端分离请提供前端地址） （可选）
      3. 退出回调接口（实现同步登出，可选）
    2. IdP管理员配置SSO平台
      1. 创建应用，获取唯一Client ID/Secret（安全性考虑，建议client_secret仅后端保管）
      2. 注册回调地址（redirect_uri），保障白名单安全
      3. OAuth2.0/OIDC 流程下，前端建议使用授权码流（需PKCE）
  2. 登录授权流程（以OAuth2.0/OIDC为例）
    1. 用户访问应用
    2. 应用检测未登录，跳转至SSO平台授权端点，附带如下参数：
      1. client_id
      2. redirect_uri
      3. response_type=code
      4. scope=openid（OIDC）
      5. state（防CSRF攻击）
      6. code_challenge、code_challenge_method（PKCE）
      7. 用户在SSO平台登录/认证
      8. 认证成功，SSO平台重定向回redirect_uri，附带授权码code、state等参数
      9. **后端（安全环境）**携带code/code_verifier（PKCE）等向SSO平台换取token（含id_token、access_token）
      10. 前端持有业务token，可用作后续接口调用
  3. 获取用户信息
    1. 前端或后端可用token向SSO平台userinfo端点拉取用户 profile 数据
      1. 请求方式：GET /oauth/userinfo
      2. 请求头：Authorization: Bearer
  4. 同步退出/单点注销(目前仅支持mind服务退出调用，其他业务暂不支持，mind应用退出会同步推出其他应用，其他应用退出仅应用自身退出)
    如需同步登出：
    1. 前端调用应用后端 POST /api/logout（业务自定义）
    2. 后端调用SSO注销接口（如 /logout 或 /connect/endsession），传递相应id_token_hint/logout_token
    3. SSO IdP通知所有接入应用执行退出（如支持BackChannelLogout）

接口规范（示例）

  1. 登录回调接口
    1. 建议路径：/callback
    2. 输入参数：code, state（可选更多）
    3. 处理逻辑：
      1. 同步向SSO平台换token
      2. 校验PKCE参数
  2. 退出接口（同步退出用）,SSO在主应用退出后会调用应用申请时填写的退出接口地址

七、安全要求

  1. callback/redirect_uri必须与登记一致，否则请求拒绝
  2. 客户端所有敏感参数（如client_secret）仅后端持有，前端禁止暴露
  3. 无服务端服务，建议强制使用PKCE（授权码流程），防止授权码拦截
  4. HTTPS全域加密通信，禁用HTTP明文

八、参考文档与扩展

如需详细接入示例（各类协议/实现/退出流程），可联系企业统一身份平台负责人或查阅相应开发文档。