基于原生PHP开发REST登录API（用docusign/esign-client ^6.12）求建议

一、环境与依赖准备 #

• 确认PHP版本符合要求：docusign/esign-client 6.12要求PHP 7.4及以上，推荐使用8.0+稳定版本
• 通过Composer安装依赖：执行composer require docusign/esign-client:^6.12，安装完成后确认vendor/autoload.php可正常引入

二、核心登录逻辑实现 #

1. 配置DocuSign认证参数 #

先定义必要的配置项，这些信息可在DocuSign开发者后台获取：

$config = [
    'integrator_key' => '你的集成密钥',
    'client_secret' => '你的客户端密钥',
    'redirect_uri' => 'https://你的域名.com/auth/callback',
    'base_path' => 'https://account-d.docusign.com' // 沙箱环境，生产环境替换为account.docusign.com
];

2. 生成授权URL引导用户登录 #

创建ApiClient实例生成授权链接，引导用户跳转到DocuSign官方登录页面：

require 'vendor/autoload.php';

use DocuSign\eSign\Client\ApiClient;

$apiClient = new ApiClient();
$apiClient->setOAuthBasePath($config['base_path']);

// 生成授权URL，使用授权码模式（适合服务器端应用）
$authUrl = $apiClient->getAuthorizationUri(
    $config['integrator_key'],
    ['signature'], // 仅申请必要的权限，登录场景signature足够
    $config['redirect_uri'],
    'code'
);

// 重定向用户到授权页面
header("Location: " . $authUrl);
exit;

3. 回调处理：换取访问令牌 #

用户完成DocuSign登录授权后，会被重定向到你配置的回调URI并携带授权码，用此代码换取访问令牌：

if (isset($_GET['code'])) {
    $apiClient = new ApiClient();
    $apiClient->setOAuthBasePath($config['base_path']);
    
    try {
        $tokenInfo = $apiClient->generateAccessToken(
            $config['integrator_key'],
            $config['client_secret'],
            $_GET['code'],
            $config['redirect_uri']
        );
        
        // 加密存储令牌信息（推荐存入服务器端session或加密数据库字段）
        $_SESSION['ds_access_token'] = $tokenInfo->getAccessToken();
        $_SESSION['ds_refresh_token'] = $tokenInfo->getRefreshToken();
        $_SESSION['ds_expires_at'] = time() + $tokenInfo->getExpiresIn();
        
        // 跳转到系统内部页面
        header("Location: /dashboard");
        exit;
    } catch (\DocuSign\eSign\ApiException $e) {
        error_log("DocuSign授权错误：" . $e->getMessage());
        header("Location: /login?error=auth_failed");
        exit;
    }
}

三、安全关键注意事项 #

• 令牌存储：访问令牌和刷新令牌必须加密存储，禁止明文写入客户端Cookie，优先存在服务器端session或加密数据库字段
• 权限最小化：申请OAuth权限时只选择必要范围，登录场景仅需signature，避免请求多余权限
• 强制HTTPS：所有涉及授权的接口（包括回调URI）必须使用HTTPS，防止授权码或令牌被窃听
• 密钥保密：客户端密钥绝对不能暴露在前端代码或公开仓库中，建议通过环境变量加载（例如getenv('DOCUSIGN_CLIENT_SECRET')）

四、错误与令牌续期处理 #

• 异常捕获：捕获DocuSign客户端抛出的异常，记录日志并返回用户友好提示
• 令牌续期：提前检查令牌过期时间，在过期前用刷新令牌获取新的访问令牌，避免用户重复登录：

// 提前5分钟刷新令牌
if (time() > $_SESSION['ds_expires_at'] - 300) {
    $apiClient = new ApiClient();
    $apiClient->setOAuthBasePath($config['base_path']);
    
    try {
        $newTokenInfo = $apiClient->generateAccessTokenFromRefreshToken(
            $config['integrator_key'],
            $config['client_secret'],
            $_SESSION['ds_refresh_token']
        );
        
        // 更新令牌信息
        $_SESSION['ds_access_token'] = $newTokenInfo->getAccessToken();
        $_SESSION['ds_refresh_token'] = $newTokenInfo->getRefreshToken();
        $_SESSION['ds_expires_at'] = time() + $newTokenInfo->getExpiresIn();
    } catch (\DocuSign\eSign\ApiException $e) {
        // 刷新失败，引导用户重新登录
        header("Location: /login?error=token_expired");
        exit;
    }
}

五、测试与调试建议 #

• 优先使用DocuSign沙箱环境测试，避免影响生产数据
• 开启调试模式查看请求详情：

$apiClient->getConfig()->setDebug(true);
$apiClient->getConfig()->setDebugFile('docusign_debug.log');

• 用Postman模拟授权流程，验证回调接口是否能正确获取并存储令牌

内容的提问来源于stack exchange，提问作者Manish Kumar Pathak