观测云集成钉钉 SSO 最佳实践

钉钉 SSO 介绍

钉钉 SSO（Single Sign-On）是钉钉提供的企业级身份认证服务，允许员工使用钉钉账号直接登录观测云平台,实现企业统一身份管理。

核心价值:

• 统一身份管理：员工无需记忆多套账号密码，一个钉钉账号即可访问观测云
• 提升安全性：基于企业已有的钉钉组织架构进行身份认证，降低账号泄漏风险
• 简化运维：员工入/离职时，通过钉钉统一管控即可同步变更观测云访问权限
• 协议适配：钉钉未提供标准 OIDC 协议，本方案通过自定义适配层实现对接

观测云

观测云是一款专为 IT 工程师打造的全链路可观测产品，它集成了基础设施监控、应用程序性能监控和日志管理，为整个技术栈提供实时可观察性。这款产品能够帮助工程师全面了解端到端的用户体验追踪，了解应用内函数的每一次调用，以及全面监控云时代的基础设施。此外，观测云还具备快速发现系统安全风险的能力，为数字化时代提供安全保障。

钉钉开放平台配置

第 1 步：创建钉钉应用

1、登录钉钉开放平台

2、进入应用开发 → 钉钉应用 ，点击创建应用

3、填写应用基本信息：

• 应用名称：建议命名为"观测云"或类似名称
• 应用描述：可描述为"用于观测云的单点登录应用"

4、点击确定完成创建

5、创建完成后会自动跳转应用管理页面，点击添加应用能力 ，选择网页应用 ，点击添加

6、点击版本管理与发布 ，点击创建新版本 ，输入版本号和描述，应用可用范围按需选择员工范围，然后点击保存完成应用发布

第 2 步：获取 Client ID 和 Client Secret

1、应用创建完成后，进入应用详情页面

2、在凭证与基础信息页面，找到以下信息：

• AppID（Client ID） ：应用的唯一标识
• AppSecret（Client Secret） ：应用的密钥

3、妥善保管这两个信息，后续在观测云中需要配置

第 3 步：配置回调地址（Redirect URI）

1、在钉钉应用的配置页面中，点击安全设置

2、在重定向 URI（Redirect URI）字段中添加对应的回调地址

SaaS 版：

https://auth.guance.com

部署版：

https://your-domain.com/oidc/callback

注意： 将 your-domain.com 替换为你的实际访问域名

3、点击添加完成保存

第 4 步：配置权限范围

1、在应用的权限管理中，确保申请或授予以下权限:

• Contact.User.Read：通讯录个人信息读权限
• Contact.User.mobile：个人手机号信息

2、确保这些权限已通过审核

SaaS 版配置

SaaS 版的 OIDC 配置通过管理控制台进行，无需修改配置文件。

第 1 步：访问管理控制台

1、登录观测云 SaaS 控制台

2、进入管理 → 成员管理 → SSO 管理

第 2 步：添加 OIDC 配置

1、点击 OIDC → 添加身份提供商

2、填写以下信息并点击保存：

字段	说明
身份提供商	SSO 服务商名称,可自定义
配置文件	上传配置文件（配置内容见下文）
访问限制	填写本公司的邮箱域名，用于 SaaS 登录时识别正确的 SSO 入口
角色授权	可选，新用户第一次登录时的默认角色

第 3 步：配置文件内容

配置文件模板如下，只需修改 clientId 和 clientSecret 为实际值即可：

{
    "wellKnowURL": "",
    "sslVerify": true,
    "clientId": "<clientId>",
    "clientSecret": "<clientSecret>",
    "grantType": "authorization_code",
    "scope": [
        "openid"
    ],
    "authSet": {
        "url": "https://login.dingtalk.com/oauth2/auth",
        "verify": true,
        "paramMapping": {
            "response_type": "code",
            "redirect_uri": "$redirect_uri",
            "client_id": "$client_id",
            "scope": "openid"
        }
    },
    "getTokenSet": {
        "url": "https://api.dingtalk.com/v1.0/oauth2/userAccessToken",
        "verify": true,
        "method": "post",
        "authMethod": "basic",
        "paramMapping": {
            "code": "$code",
            "state": "$state",
            "grant_type": "$grant_type",
            "redirect_uri": "$redirect_uri",
            "client_id": "$client_id",
            "client_secret": "$client_secret"
        }
    },
    "verifyTokenSet": {
        "url": "",
        "verify": true,
        "method": "get",
        "keys": []
    },
    "getUserInfoSet": {
        "url": "https://api.dingtalk.com/v1.0/contact/users/me",
        "method": "get",
        "authMethod": "bearer",
        "source": "origin",
        "responseInfoPath": "",
        "paramMapping": {}
    },
    "claimMapping": {
        "username": "nick",
        "email": "email",
        "mobile": "mobile"
    }
}

第 4 步：测试 SSO 登录

在观测云登录页面进行 SSO 登录验证：

登录成功后看到对应用户信息，即表示配置完成：

部署版配置

第 1 步：创建 Well-Known 接口

由于钉钉不提供标准 OIDC 协议，需要使用 Func 平台提供 Well-Known 接口。

登录 Func 平台，创建如下脚本，并创建 API 服务，获取请求地址作为 OIDC Well-Known 接口，具体 Func 使用方法参考 Func 官方文档 。

@DFF.API("wellknown")
def wellknown():
    return {
      "authorization_endpoint": "https://login.dingtalk.com/oauth2/auth", 
      "token_endpoint": "https://api.dingtalk.com/v1.0/oauth2/userAccessToken",
      "userinfo_endpoint": "https://api.dingtalk.com/v1.0/contact/users/me"
    }

第 2 步：配置 forethought-core/core

在 Launcher 中进入命名空间： forethought-core → core，为 config.yaml 增加或修改如下配置：

OIDCClientSet:
  # 开启自定义 OIDC
  enableCustomOIDC: true

  # 指向 Func 中 well_know 函数的 API 地址
  wellKnowURL: "<Func well_know API 地址>"

  mapping:
    username: nick
    mobile: mobile
    email: email
    exterId: openId

第 3 步：配置前端登录入口

在 Launcher 中进入命名空间： forethought-webclient → front-web-config，修改 config.js：

window.DEPLOYCONFIG = {
  ...
  paasCustomLoginInfo: [
    {
      label: "OIDC 登录",
      url: "https://<部署版 Web 域名>/oidc/login",
      desc: "自定义 OIDC 登录"
    }
  ],
  paasCustomLoginUrl: "https://<IdP 登出地址>?redirect_url=https://<部署版 Web 域名>/oidc/login"
}

第 4 步：配置 Web Nginx 转发规则

在命名空间： forethought-webclient → front-web-config 中修改 nginx.conf，将 OIDC 登录和回调请求转发到 inner 服务。

location /oidc/login {
    proxy_connect_timeout 5;
    proxy_send_timeout 5;
    proxy_read_timeout 300;
    proxy_http_version 1.1;
    proxy_set_header Connection "keep-alive";
    add_header Access-Control-Allow-Origin *;
    add_header Access-Control-Allow-Headers X-Requested-With;
    add_header Access-Control-Allow-Methods GET,POST,OPTIONS;
    proxy_pass http://inner.forethought-core:5000/api/v1/inner/oidc/login;
}

location /oidc/callback {
    proxy_connect_timeout 5;
    proxy_send_timeout 5;
    proxy_read_timeout 300;
    proxy_http_version 1.1;
    proxy_set_header Connection "keep-alive";
    add_header Access-Control-Allow-Origin *;
    add_header Access-Control-Allow-Headers X-Requested-With;
    add_header Access-Control-Allow-Methods GET,POST,OPTIONS;
    proxy_pass http://inner.forethought-core:5000/api/v1/inner/oidc/callback;
}

这一步的目的是让浏览器访问的 /oidc/login 和 /oidc/callback 最终进入部署版内部的 OIDC 处理逻辑。

等待服务重启完成,然后验证配置。

常见问题与故障排查

Q1：回调地址不匹配错误

现象： 登录时显示 redirect_uri mismatch 或相似错误

排查步骤：

1. 确认钉钉应用配置中的回调地址与平台中的 Redirect URI 完全相同
2. 检查是否有多余的 / 或大小写差异
3. 确认使用的是 HTTPS（如平台配置为 HTTPS）
4. 对于部署版，确认 launcher.yaml 中的 redirectUrl 与钉钉应用配置一致

Q2：Invalid Client ID 或认证失败

现象： 登录时提示客户端无效或认证失败

排查步骤：

1. 验证 Client ID 和 Client Secret 是否正确复制(避免多余空格)
2. 确认钉钉应用未被禁用或删除
3. 检查 Client Secret 是否过期(某些情况下需要重新生成)
4. 确认应用权限配置无问题

Q3：用户信息获取失败

现象： 登录时无法获取用户邮箱或其他信息

排查步骤：

1. 确认钉钉应用已申请获取成员详情的权限
2. 检查字段映射是否正确（字段名是否拼写错误）
3. 验证钉钉账号是否完善（如邮箱是否已填写）
4. 检查平台日志,查看具体的错误信息

Q4：登录后仍无权限访问

现象： 登录成功但无法访问平台资源

排查步骤：

1. 确认用户已被添加到对应组织中
2. 检查用户是否拥有正确的角色和权限
3. 如使用了新用户名,确认权限是否已分配给新用户名

Q5：部署版重启后配置丢失

现象： 重启服务后 OIDC 配置消失

排查步骤：

1. 确认配置已写入 ConfigMap（Kubernetes）或配置文件（Docker）
2. 检查文件权限是否正确
3. 查看启动日志中是否有配置加载错误
4. 验证 YAML 格式是否正确（缩进、语法等）

Q6：不同用户使用同一邮箱导致冲突

现象： 多个钉钉用户有相同的邮箱，导致 SSO 异常

排查步骤：

1. 确保字段映射中使用 sub 或 uid 作为唯一标识，而不是邮箱
2. 在钉钉管理后台检查并修正重复邮箱
3. 必要时手动在平台中合并或管理用户账号

总结

本方案通过自定义 OIDC 协议适配层，解决了钉钉不提供标准 OIDC 协议的问题。部署版需在 Func 平台创建 Well-Known 接口映射钉钉 OAuth 端点，并修改 Core 配置及 Nginx 转发规则，SaaS 版则通过管理控制台上传配置文件完成适配。核心流程包括：在钉钉开放平台创建应用获取 Client ID 和 Client Secret、配置回调地址和权限，在平台端完成 OIDC 参数映射（将钉钉的 nick、mobile、email 字段映射为平台标准字段），最终实现企业员工使用钉钉账号一键登录，达成统一身份认证管理。