Laravel应用对接QuickBooks Web Connector时遭遇认证错误

问题现象 #

Laravel日志显示认证成功，但QuickBooks Web Connector（QBWC）抛出QBWC1012认证失败错误，具体日志如下：

20240719.22:00:39 UTC   : QBWebConnector.SOAPWebService.instantiateWebService() : Initiated connection to the following application.
20240719.22:00:39 UTC   : QBWebConnector.SOAPWebService.instantiateWebService() : AppName: Your Laravel App Name
20240719.22:00:39 UTC   : QBWebConnector.SOAPWebService.instantiateWebService() : AppUniqueName (if available): Your Laravel App Name
20240719.22:00:39 UTC   : QBWebConnector.SOAPWebService.instantiateWebService() : AppURL: https://clients-ama.test/quickbooks
20240719.22:00:39 UTC   : QBWebConnector.SOAPWebService.do_serverVersion() : *** Calling serverVersion().
20240719.22:00:42 UTC   : QBWebConnector.SOAPWebService.do_serverVersion() : Received from serverVersion() following parameter:<serverVersionRet="">
20240719.22:00:42 UTC   : QBWebConnector.SOAPWebService.do_serverVersion() : This application sent a null for server version. Allowing update operation.
20240719.22:00:42 UTC   : QBWebConnector.SOAPWebService.do_clientVersion() : *** Calling clientVersion() with following parameter:<productVersion="34.0.1001.27">
20240719.22:00:45 UTC   : QBWebConnector.SOAPWebService.do_clientVersion() : Received from clientVersion() following parameter:<clientVersionRet="">
20240719.22:00:45 UTC   : QBWebConnector.SOAPWebService.do_clientVersion() : This application agrees with the current version of QBWebConnector. Allowing update operation.
20240719.22:00:45 UTC   : QBWebConnector.SOAPWebService.do_authenticate() : Authenticating to application 'Your Laravel App Name', username = 'admin'
20240719.22:00:45 UTC   : QBWebConnector.SOAPWebService.do_authenticate() : *** Calling authenticate() with following parameters:<userName="admin"><password=<MaskedForSecurity>
20240719.22:00:48 UTC   : QBWebConnector.SOAPWebService.do_authenticate() : QBWC1012: Authentication failed due to following error message.
Object reference not set to an instance of an object.
More info:
StackTrace =    at QBWebConnector.WebService.do_authenticate(String& ticket, String& companyFileName)
Source = QBWebConnector
20240719.22:00:48 UTC   : QBWebConnector.RegistryManager.setUpdateLock() : HKEY_CURRENT_USER\Software\Intuit\QBWebConnector\UpdateLock has been set to False
20240719.22:00:48 UTC   : QBWebConnector.RegistryManager.setUpdateLock() : ********************* Update session unlocked *********************
20240719.22:00:48 UTC   : QBWebConnector.WebServiceManager.DoUpdate() : Update completed with errors. See log (QWClog.txt) for details.
20240719.22:00:48 UTC   : UpdateThisScheduledApp() : QBWC1031: Update completed with some error. Application has been notified of the error accordingly. See QWCLog for further information.

Laravel端相关代码 #

请求处理器方法 #

public function handleRequest(Request $request)
{
    Log::info('QuickBooks request received', [
        'content' => $request->getContent(),
        'headers' => $request->headers->all()
    ]);

    $server = new SoapServer(public_path('QuickBooks.wsdl'), [
        'uri' => 'http://developer.intuit.com/',
        'soap_version' => SOAP_1_1
    ]);

    $server->setClass(QuickBooksService::class);

    ob_start();
    try {
        $server->handle();
    } catch (\Exception $e) {
        Log::error('SOAP Error: ' . $e->getMessage(), [
            'exception' => $e,
            'trace' => $e->getTraceAsString(),
            'request' => $request->getContent()
        ]);
        $fault = new \SoapFault('Server', $e->getMessage());
        $server->fault($fault->faultcode, $fault->faultstring);
    }
    $response = ob_get_clean();

    Log::info('QuickBooks response sent', ['content' => $response]);

    return response($response, 200, [
        'Content-Type' => 'text/xml; charset=utf-8',
    ]);
}

原认证方法 #

public function authenticate($strUserName, $strPassword)
{
    Log::info("authenticate called with username: $strUserName");
    if ($strUserName === 'mendy' && $strPassword === 'password') {
        $ticket = md5(uniqid());
        $companyFile = '';
        $waitTime = 0;
        $minVersion = '';  // 或根据需要指定最低版本
        $responseArray = [$ticket, $companyFile, $waitTime, $minVersion];
        $responseString = implode('|', $responseArray);
        Log::info("Authentication successful. Returning: $responseString");
        return $responseString;
    } else {
        Log::warning("Authentication failed for username: $strUserName");
        return 'nvu';
    }
}

问题根源与修复方案 #

1. 用户名不匹配 #

从QBWC日志可见，实际发起请求的用户名是admin，但原认证方法中校验的是mendy，需保持两者一致。

2. SOAP方法签名不匹配（核心问题） #

QuickBooks Web Connector的authenticate方法要求通过引用传递参数返回ticket和companyFileName，而非直接返回拼接字符串。原方法的签名不符合QBWC的要求，导致出现Object reference not set to an instance of an object错误。

修正后的认证方法 #

public function authenticate($strUserName, $strPassword, &$ticket, &$companyFileName)
{
    Log::info("authenticate called with username: $strUserName");
    // 匹配QBWC使用的用户名和正确密码
    if ($strUserName === 'admin' && $strPassword === 'your-actual-password') {
        $ticket = md5(uniqid());
        $companyFileName = ''; // 若需指定公司文件路径则填写，否则留空
        // 返回0表示认证成功
        return 0;
    } else {
        Log::warning("Authentication failed for username: $strUserName");
        // 返回3表示无效用户（对应原代码的'nvu'）
        return 3;
    }
}

补充说明 #

QBWC的authenticate方法返回值为整数，对应含义：

• 0：认证成功，继续后续流程
• 1：需要更新QBWC版本
• 2：需要更新应用程序
• 3：无效用户/密码

同时需确保QuickBooks.wsdl文件中authenticate方法的定义与PHP方法签名完全一致，参数顺序和引用传递规则必须匹配。

内容的提问来源于stack exchange，提问作者Ihtisham Khan