跳到主要内容

dingtalk-auth

dingtalk-auth 插件基于钉钉开放平台的 OAuth 2.0 协议实现身份认证，通过验证请求中的钉钉授权码（code）获取用户信息，并将用户信息注入请求头或上下文，同时支持会话缓存避免重复认证，对接钉钉企业内部应用的访问控制。

插件时序流程​

使用示例​

前提条件​

  1. 在钉钉开放平台创建企业内部应用，获取 app_key 和 app_secret；
  2. 配置钉钉授权页面 URI；其中携带的实际回调地址需在钉钉开放平台登记为可信回调地址；
  3. 确保网关能访问钉钉开放平台的 HTTPS 接口（api.dingtalk.com、oapi.dingtalk.com）。

在路由上配置钉钉认证插件​

以下示例演示如何在路由上实现钉钉认证。

创建路由并启用 dingtalk-auth 插件，具体插件配置如下：

curl "http://127.0.0.1:9180/apisix/admin/routes/dingtalk-auth-route" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '
{
  "uri": "/get",
  "plugins": {
    "dingtalk-auth": {
      "app_key": "dingxxxxxx",
      "app_secret": "xxxxxx",
      "secret": "session-secret-12345678",
      "redirect_uri": "https://login.dingtalk.com/oauth2/auth?appid=dingxxxxxx&response_type=code&scope=openid&redirect_uri=https%3A%2F%2Fyour-domain.com%2Fcallback",
      "cookie_expires_in": 86400,
      "set_userinfo_header": true
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

❶ 替换为你的 app key。

❷ 替换为你的 app secret。

❸ 替换为你的 secret，该值应为随机字符串。

❹ 替换为钉钉授权页面 URI，并将其中的实际回调地址参数替换为已在钉钉开放平台登记的可信回调地址。

  1. 首次请求（无 code）： 访问 http://127.0.0.1:9080/get 时，响应状态码为 302 Found，响应头 Location 指向配置的 redirect_uri（钉钉授权页）。

  2. 携带 code 的请求：

    为了便于测试，这里可以通过 JSAPI Explorer 获取授权码，在实际的生产环境中，用户会在浏览器中完成钉钉授权流程后自动获得授权码。

    从钉钉授权页获取 code 后，携带 code 发起请求：http://127.0.0.1:9080/get?code=xxxx。验证成功时，响应包含会话 Cookie dingtalk_session，状态码为 200，上游服务可读取 X-Userinfo 请求头获取用户信息。

  3. 会话缓存验证： 携带会话 Cookie 发起请求 http://127.0.0.1:9080/get，此时网关验证 Cookie 中的用户信息，并注入 X-Userinfo 头转发到上游服务。

解码用户信息​

用户身份认证成功后，插件会在请求中添加包含 Base64 编码用户信息的 X-Userinfo 请求头。

上游服务可解码 X-Userinfo 头获取用户信息：

import base64
import json

# 示例：使用 Python 解码 X-Userinfo
userinfo_header = "eyJ1c2VyaWQiOiJkaW50YWxsaW5lLXVzZXJpZCJ9"
userinfo = json.loads(base64.b64decode(userinfo_header).decode('utf-8'))
print(userinfo)  # 输出：{"userid": "dingtalk-userid"}