如何在Next.js应用中通过DocuSign Node.js SDK实现JWT认证

第一步：前置配置准备 #

DocuSign后台配置 #

• 创建集成密钥，开启JWT认证能力，添加本地调试地址和Vercel线上域名到授权重定向列表
• 生成RSA密钥对，私钥单独保存，禁止提交到代码仓库
• 给集成密钥配置所需权限范围，至少包含signature、impersonation两项基础权限

项目侧配置 #

• 安装DocuSign SDK：npm install docusign-esign
• 把所有敏感参数存入环境变量，Vercel后台也要同步配置对应参数，参考变量名：

  DOCUSIGN_INTEGRATION_KEY=你的集成密钥
  DOCUSIGN_USER_ID=模拟操作的用户ID
  DOCUSIGN_ACCOUNT_ID=你的DocuSign账户ID
  DOCUSIGN_PRIVATE_KEY=RSA私钥内容，所有换行替换为\n
  DOCUSIGN_BASE_PATH=https://demo.docusign.net/restapi # 生产环境替换为正式地址
  DOCUSIGN_OAUTH_BASE_PATH=account-d.docusign.com # 生产环境替换为account.docusign.com
  

注意：私钥是多行格式，存入环境变量时必须把所有换行符替换为\n，否则无服务器函数读取时会解析失败。

第二步：编写JWT获取无服务器端点 #

根据你使用的Next.js路由模式选择对应实现：

App Router（Next.js 13+） #

新建文件app/api/docusign/token/route.ts，代码示例：

import { ApiClient } from 'docusign-esign'
import { NextResponse } from 'next/server'

export async function GET() {
  const dsApiClient = new ApiClient()
  dsApiClient.setBasePath(process.env.DOCUSIGN_OAUTH_BASE_PATH!)

  try {
    const res = await dsApiClient.requestJWTUserToken(
      process.env.DOCUSIGN_INTEGRATION_KEY!,
      process.env.DOCUSIGN_USER_ID!,
      ['signature', 'impersonation'], // 可按需扩展权限范围
      Buffer.from(process.env.DOCUSIGN_PRIVATE_KEY!.replace(/\\n/g, '\n')),
      3600 // token有效期最长可设为3600秒
    )

    return NextResponse.json({
      accessToken: res.body.access_token,
      expiresIn: 3600,
      accountId: process.env.DOCUSIGN_ACCOUNT_ID,
      basePath: process.env.DOCUSIGN_BASE_PATH
    })
  } catch (err) {
    console.error('JWT获取失败：', err)
    return NextResponse.json({ error: '签名凭证生成失败' }, { status: 500 })
  }
}

Pages Router #

新建文件pages/api/docusign/token.ts，核心逻辑和上面完全一致，仅返回方式替换为NextApiResponse的对应方法即可。 #

第三步：调试与部署验证 #

• 本地首次调用如果返回consent_required错误，按照DocuSign提示完成一次账号授权即可，授权仅需要操作一次
• 部署到Vercel前确认所有环境变量都已在Vercel项目后台配置完成，环境变量修改后需要重新部署才会生效
• 前端直接请求/api/docusign/token获取凭证即可，所有敏感认证逻辑全部放在无服务器函数侧处理，禁止把私钥、集成密钥等信息暴露到前端代码

常见问题排查 #

• 私钥格式错误：90%以上是换行符处理问题，确认环境变量中私钥的所有换行都已替换为\n
• 权限不足：确认DocuSign后台给集成密钥配置的权限范围和代码中请求的范围一致，同时模拟用户有对应签名操作权限
• Vercel部署后报错：优先检查环境变量是否配置正确，是否有多余的空格或者换行

内容的提问来源于stack exchange，提问作者S.keeb422