README

Securibox云代理API的PHP客户端库

安装包

Securibox云代理PHP包装器通过Composer安装。只需运行以下命令

composer require securibox/cloudagents

替代方案：从zip包中安装包

如果您不使用Composer，只需下载并安装库的最新打包版本（zip）。

身份验证

为了保护Securibox云代理API，已实施三种机制。以下是三种机制的简要概述以及代码片段，以帮助您集成正确的机制以调用API。

基本API身份验证（TLS）

基本API身份验证是最容易实现的，提供的是三种常见协议中安全性最低的选项。此机制通常建议用于测试目的，以便测试API，并且只需要Securibox提供用户名和密码。

use Securibox\CloudAgents\Documents\ApiClient;

$client = ApiClient::AuthenticationBasic("username", "password");

SSL客户端证书身份验证

SSL客户端证书是一种允许您的应用程序通过Securibox云代理（SCA）服务器进行身份验证的机制。在这种情况下，您的应用程序将在验证SCA服务器身份后发送其SSL证书。然后，客户端和服务器使用这两个证书生成一个用于在它们之间发送请求的唯一密钥。

此类身份验证是在客户调用您的服务器，然后调用Securibox云代理API时实施的。

为了使用此类型身份验证，Securibox将提供包含带有密码保护的私钥和公钥的PEM证书文件的文件。

use Securibox\CloudAgents\Documents\ApiClient;

$client = ApiClient::SslClientCertificate("C:\Path\to\PEM Certificate", "PEM pass phrase");

JSON Web Token身份验证

JSON Web Token（JWT）是一种开放标准（RFC 7519），它定义了一种紧凑且自包含的方式来安全地在各方之间传输信息作为JSON对象。由于它是数字签名的，因此可以验证和信任此信息。JWT可以使用RS256（RSA PKCS#1签名与SHA-256）使用公钥/私钥对进行签名。

此类身份验证是在客户直接调用Securibox云代理API并使用跨源资源共享（CORS）时实施的。

为了使用此类型身份验证，Securibox将提供包含密码保护的RSA私钥的PEM文件（.pem）。

use Securibox\CloudAgents\Documents\ApiClient;

$client = ApiClient::Jwt("C:\Path\to\PEM private key", "PEM pass phrase");

入门

以下是最小化代码，用于列出所有代理的详细信息字段

<?php 
// If you are using Composer (recommended)
require 'vendor/autoload.php';
use Securibox\CloudAgents\Documents\ApiClient;
use Securibox\CloudAgents\Documents\Entities;

// If you are not using Composer
// require("path/to/cloudagents-php/src/autoload.php");

$client = ApiClient::AuthenticationBasic("Basic Username", "Basic Password");
$agents = $client->GetAgents();
foreach($agents as $agent){
    print("\n\n\n------ Agent Details ------\n");
    print("ID: ".$agent->id."\n");
    print("Name: ".$agent->name."\n");
    print("Periodicity: ".$agent->agentPeriodicity."\n");
    print("Current Status: ".$agent->agentCurrentState."\n");
    print("Category: ".$agent->category."\n");
    foreach($agent->fields as $field){
        print("   Field[". $field->position ."]: ".$field->name."\n");
    }
}

以下是最小化代码，用于配置代理并启动同步

<?php
// If you are using Composer (recommended)
require 'vendor/autoload.php';
use Securibox\CloudAgents\Documents\ApiClient;
use Securibox\CloudAgents\Documents\Entities;

// If you are not using Composer
// require("path/to/cloudagents-php/src/autoload.php");

//Configure account properties
$account = new Entities\Account();
$account->agentId = 'c42f0150d2eb47ee8fa56bce25e49b8d';
$account->customerAccountId = 'Account201708082';
$account->customerUserId = 'User123';
$account->name = 'Test Account 1';
$account->credentials = array();

//Configure credentials
$username = new Entities\Credential();
$username->position = 0;
$username->value = 'username@test.com';

//Configure credentials
$password = new Entities\Credential();
$password->position = 1;
$password->value = '###password###';

array_push($account->credentials, $username, $password);

//Setup client
$client = new ApiClient::AuthenticationBasic("Basic Username", "Basic Password");

//Create the account which automatically launches a synchronization
$returnedAccount = $client->CreateAccount($account);

//Let's wait until the synchronization has reached a final status
$synchronization = $client->GetLastSynchronizationByAccount($returnedAccount->customerAccountId);
while($synchronization->synchronizationState != "PendingAcknowledgement" &&
      $synchronization->synchronizationState != "Completed" &&
      $synchronization->synchronizationState != "ReportFailed"){
        sleep(5);
        $synchronization = $client->GetLastSynchronizationByAccount($returnedAccount->customerAccountId);
}

//Let's get the newly downloaded documents and save them locally
$documents = $client->GetDocumentsByAccount($account->customerAccountId, 'true','true');
$receivedFiles = array();
foreach($documents as $document){
    $file = fopen("C:\\Temp\\".$document->name, "wb");
    $content =  base64_decode($document->base64Content);
    fwrite($file, $content);
    fclose($file);
    array_push($receivedFiles, $document->id);   
}
$client->AcknowledgeSynchronizationForAccount($account->customerAccountId, $receivedFiles, array());

Webview URL

为了使用webview并避免实现列出和配置账户的API，已经开发了一个webview。在这个webview中，客户可以

浏览和搜索所有代理
快速访问预定义的收藏夹代理
列出配置的代理
配置、修改或删除代理账户
查看每个账户的同步列表

要使用webview，请在CloudAgents后台办公室中激活它，并使用提供的PEM私钥对令牌进行签名。

webview接受以下URL参数

token：使用PEM证书签名的JSON Web Token
callback：用户登出时被发送到的URL _{^{（例如：https://www.myapp.com - 如果已提供状态： https://www.myapp.com?state={state}）}}
lang ^可选：显示页面的文化 - 默认为fr-FR

示例

https://sca-webview.azurewebsites.net?token={token}&callback={callback_url}&state={stateData}
https://sca-webview.azurewebsites.net?token={token}&callback={callback_url}&state={stateData}&lang=en-us

有关使用PHP生成令牌的示例，请参阅测试。

许可

GNU GPL

securibox / cloudagents

维护者

详细信息