Laravel集成无需客户登录同意的Docusign JWT OAuth2嵌入式签署咨询

1. 令牌方法选择 #

你应该使用 PHP SDK 中的requestJWTUserToken方法：

• requestJWTApplicationToken生成的是应用级令牌，仅支持账号配置、用户管理等不涉及签署流程的操作，无法用来创建签署任务、生成嵌入式签署链接
• requestJWTUserToken生成的是模拟指定用户身份的用户级令牌，完全匹配你需要用开发者账号身份为无账号客户提供签署服务的场景，不需要客户做任何授权操作

2. 权限范围配置 #

要完全避免弹出授权/登录窗口，需要做两处配置：

• 首先在 DocuSign 后台的集成应用配置中，添加signature和impersonation两个权限范围
• 必须使用你的开发者账号（即令牌要模拟的账号）对集成应用做一次性同意授权，授权完成后后续所有JWT请求都不会再触发授权弹窗，客户侧完全无感知

3. 具体实现步骤 #

3.1 前期准备 #

• 提前在 DocuSign 后台获取以下参数：集成应用客户端ID（Integration Key）、开发者账号用户ID（API Username）、账号ID、RSA私钥
• 安装 DocuSign PHP SDK：composer require docusign/esign-client

3.2 项目配置 #

在.env文件中添加相关配置：

DOCUSIGN_CLIENT_ID=你的集成应用客户端ID
DOCUSIGN_USER_ID=你的开发者账号用户ID
DOCUSIGN_ACCOUNT_ID=你的DocuSign账号ID
# 沙箱环境路径，生产环境替换为https://www.docusign.net/restapi
DOCUSIGN_BASE_PATH=https://demo.docusign.net/restapi
# 沙箱OAuth路径，生产环境替换为account.docusign.com
DOCUSIGN_OAUTH_BASE_PATH=account-d.docusign.com
DOCUSIGN_RSA_KEY_PATH=存储RSA私钥的本地文件路径

3.3 生成JWT令牌 #

封装令牌生成方法：

use DocuSign\eSign\Client\ApiClient;

public function generateJwtToken()
{
    $apiClient = new ApiClient();
    $apiClient->getOAuth()->setOAuthBasePath(config('docusign.oauth_base_path'));
    
    $jwtScope = ['signature', 'impersonation'];
    $privateKey = file_get_contents(config('docusign.rsa_key_path'));
    
    $response = $apiClient->requestJWTUserToken(
        config('docusign.client_id'),
        config('docusign.user_id'),
        $jwtScope,
        $privateKey,
        3600 // 令牌有效期，最长1小时
    );
    
    return $response[0]['access_token'];
}

3.4 创建嵌入式签署任务并生成签署链接 #

use DocuSign\eSign\Api\EnvelopesApi;
use DocuSign\eSign\Model\EnvelopeDefinition;
use DocuSign\eSign\Model\Document;
use DocuSign\eSign\Model\Signer;
use DocuSign\eSign\Model\SignHere;
use DocuSign\eSign\Model\Tabs;
use DocuSign\eSign\Model\RecipientViewRequest;

public function createEmbeddedSigning()
{
    $accessToken = $this->generateJwtToken();
    $accountId = config('docusign.account_id');
    $apiClient = new ApiClient();
    $apiClient->setAccessToken($accessToken);
    $apiClient->setConfig($apiClient->getConfig()->setHost(config('docusign.base_path')));
    
    // 构造签署文档
    $document = new Document([
        'document_base64' => base64_encode(file_get_contents(public_path('待签署文档.pdf'))),
        'name' => '签署文档名称',
        'file_extension' => 'pdf',
        'document_id' => '1'
    ]);
    
    // 构造签署人信息，仅需填写客户姓名邮箱，不需要客户有DocuSign账号
    $signer = new Signer([
        'email' => 'customer@example.com',
        'name' => '客户姓名',
        'recipient_id' => '1',
        'client_user_id' => '1001' // 自定义客户标识，用来关联嵌入式签署视图，必填
    ]);
    
    // 配置签署位置
    $signHere = new SignHere([
        'anchor_string' => '文档内签署位置锚点文字',
        'anchor_units' => 'pixels',
        'anchor_x_offset' => '10',
        'anchor_y_offset' => '20'
    ]);
    $signer->setTabs(new Tabs(['sign_here_tabs' => [$signHere]]));
    
    // 构造并发送签署信封
    $envelopeDefinition = new EnvelopeDefinition([
        'email_subject' => '请签署文档',
        'documents' => [$document],
        'recipients' => ['signers' => [$signer]],
        'status' => 'sent'
    ]);
    
    $envelopesApi = new EnvelopesApi($apiClient);
    $envelope = $envelopesApi->createEnvelope($accountId, $envelopeDefinition);
    
    // 生成嵌入式签署链接
    $recipientViewRequest = new RecipientViewRequest([
        'return_url' => route('sign.success'), // 签署完成后跳转的你的应用地址
        'authentication_method' => 'none', // 无需客户登录验证
        'email' => 'customer@example.com',
        'user_name' => '客户姓名',
        'client_user_id' => '1001' // 和之前填写的自定义标识保持一致
    ]);
    
    $viewUrl = $envelopesApi->createRecipientView($accountId, $envelope->getEnvelopeId(), $recipientViewRequest);
    
    // 返回链接给前端嵌入iframe或直接跳转即可，客户打开直接签署，无任何登录授权步骤
    return redirect($viewUrl->getUrl());
}

注意事项 #

• 首次配置集成应用后必须做一次手动授权，否则第一次调用JWT接口会返回授权错误，手动授权仅需操作一次，后续不会再触发
• 生产环境使用前需要将集成应用提交DocuSign审核通过，沙箱环境无需审核可直接使用

内容的提问来源于stack exchange，提问作者Jacob k