集成应用免登对接说明

概述

本文档面向开发者，介绍如何通过集成应用接入简道云，实现账户免登功能。

简道云提供两种免登授权流程，两者均为必做对接，但面向的使用场景不同：

两种流程的核心逻辑一致：均通过 code 换取用户信息，但触发方式和实现细节不同。请根据实际使用场景分别对接。

本文仅讲解接口理论，具体实现示例请参考：集成应用免登对接示例

接入准备

客户平台技术要求

对接简道云集成应用 SSO，客户平台需要具备以下能力：

创建集成应用并获取凭证

请先参考文档创建集成应用，获取凭证，配置可信域名与应用主页：集成应用功能说明

免登授权流程

简道云提供两种免登授权流程，两者均为必做对接，面向的使用场景不同：

主页跳转流程

适用场景：从简道云「管理后台 > 产品中心 > 进入应用」登录第三方系统。

在简道云产品中心可以为应用配置主页地址。用户点击进入产品时，简道云自动跳转到应用的主页地址，并携带一个 code 参数。

客户产品端需要实现以下逻辑：

1）接收并解析 code 参数：从简道云跳转回调中获取 code，注意 code 为一次性凭证，需在回调后立即使用。

2）调用 auth_info 接口：在服务端调用，请求头中携带 Authorization: Bearer {app_secret} 换取用户信息。

3）用户登录：根据 username + tenant_id 在自有系统中查找对应用户，建立映射关系。

4）维护登录态：自行生成 Token/Session/Cookie 管理登录状态，简道云不负责应用登录态管理。

5）访问业务系统：重定向到业务首页。

完整交互流程如下图所示：（其中橙色高亮区域为客户产品端需要自行实现的内容。）

OAuth 授权流程

适用场景：从「仪表盘/表单页面 > 嵌入页面」登录第三方系统。

如需从产品端发起授权，需构造以下 URL 地址引导用户访问：

参数说明：

客户产品端需要实现以下逻辑：

1）构造授权 URL 并发起重定向：拼接 app_id、state、redirect_uri 参数构造简道云授权页 URL，引导用户跳转。

2）生成并校验 state：每次授权生成随机 state，在回调时校验是否匹配，防止 CSRF 攻击。

3）接收 code 参数：从简道云回调中获取 code，注意 code 为一次性凭证，需在回调后立即使用。

4）调用 auth_info 接口：在服务端调用，请求头中携带 Authorization: Bearer {app_secret} 换取用户信息。

5）用户登录：根据 username + tenant_id 在自有系统中查找对应用户，建立映射关系。

6）维护登录态：自行生成 Token/Session/Cookie 管理登录状态，简道云不负责应用登录态管理。

完整交互流程如下图所示：（其中橙色高亮区域为客户产品端需要自行实现的内容。）

扩展推荐：统一回调接口

两种流程虽然触发方式不同，但获取 code 后的逻辑完全一致。推荐用一个 URL 同时处理两种情况，减少维护成本：

伪代码参考：（python版）

def handle_callback(request):
    code = request.query.get("code")
    # 情况 2：没有 code → 主动发起 OAuth 跳转
    if not code:
        state = generate_random_string(32)
        save_state(session, state)
        auth_url = "https://www.jiandaoyun.com/open/user/oauth/login"
                + "?app_id=" + APP_ID
                + "&state=" + state
                + "&redirect_uri=" + url_encode(YOUR_CALLBACK_URL)
        return redirect(auth_url)
    # 情况 1：有 code → 换取用户身份
    if request.query.get("state"):
        validate_state(session, request.query["state"])  # OAuth 流程下校验
    response = http_post(
        url="https://api.jiandaoyun.com/api/v3/user/oauth/auth_info",
        headers={
            "Authorization": "Bearer " + APP_SECRET,
            "Content-Type": "application/json"
        },
        body={"code": code},
        timeout=10
    )
    if response.status != 200:
        return error("SSO 失败: " + response.body)
    username  = response.json["username"]
    tenant_id = response.json["tenant_id"]
    user    = find_or_create_user(username, tenant_id)
    session = create_session(user)
    return redirect("/your-business-home", session)

获取简道云登录用户信息接口

两种流程在获取 code 后，均调用同一个接口换取用户身份信息。

接口信息

请求说明

请求头：

请求体：

{
     "code": "xxxxx"
}

响应说明

成功响应字段：

成功响应示例：

{
    "tenant_id": "620a31c23e7c5a00081e7acf",
    "username": "jdy-developer"
}

完整调用示例（cURL）

curl --location 'https://api.jiandaoyun.com/api/v3/user/oauth/auth_info' \
--header 'Authorization: Bearer YOUR_SUITE_SECRET' \
--header 'Content-Type: application/json' \
--data '{
    "code": "USER_CODE"
}'

其中：

注意事项与接口限制

FAQ

code 有效期多久？

code 为一次性使用凭证，建议在回调后立即调用接口换取用户信息。

回调地址需要配置吗？

暂无配置入口，请在集成应用中配置可信域名，系统会校验请求来源的合法性。后续迭代可能会开放更灵活的重定向地址配置入口。

支持哪些开发语言？

本接口为标准 HTTP API，任何支持发送 HTTP 请求的语言均可调用，包括 Java、Python、JavaScript、Go 等。

如何维持登录状态？

简道云仅提供用户身份信息，应用需要在本地生成并维护登录态（如 Session、Token、Cookie 等）。建议在首次获取用户信息后，将登录态写入应用域下的 Cookie 或 Storage 中。

iframe 嵌入场景下遇到第三方 Cookie 问题怎么办？

Chrome 无痕模式、钉钉/企微内置浏览器会阻止第三方 Cookie。建议：