04 Jun 15:08

cstruman

23c4286

v1.5.0 Latest

Latest

Set version

Assets 2

04 Jun 14:55

cstruman

1.4.1

71d265c

Set the version at 1.4.1

Update account and document status
Enable ack negative for documents

Assets 2

26 Sep 18:16

joaomrodrigues

1.4.0

635200f

v1.4.0

Supports the new SCA API v2.0
Refactored tests to have a single file with all tests

Assets 2

15 Jul 11:29

joaomrodrigues

1.3.0

0c703c4

v1.3.0

Merge pull request #2 from HeyOctave/new-states

add missing sync state details codes

Assets 2

04 Feb 11:27

joaomrodrigues

1.2.0

97edeae

1.2.0

Corrected JWT generation and documented the webview url generation

Assets 2

04 Feb 01:17

joaomrodrigues

1.1.9

1ba63c5

1.1.9

cloudagents-php

A PHP client library for the Securibox Cloud Agents API

Install Package

Securibox Cloud Agent PHP wrapper is installed via Composer.
Simply run the following command:

composer require securibox/cloudagents

Alternative: Install package from zip

If you are not using Composer, simply download and install the latest packaged release of the library as a zip.

Authentication

In order to secure the Securibox Cloud Agents API, three mechanisms have been implemented. Here is a brief overview of the three mechanisms as well as code snippets to help you integrate the correct mechanism in order to call the APIs.

Basic API Authentication w/ TLS

Basic API authentication is the easiest of the three to implement offering the lowest security options of the common protocols.
This mechanism is usually advised for testing purposes in order to test the APIs and only requires Securibox to provide a username and password.

use Securibox\CloudAgents\Documents\ApiClient;

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

SSL Client Certificate Authentication

The SSL client certification is a mechanism allowing your application to authenticate itself with the Securibox Cloud Agents (SCA) servers. In this case, your application will send its SSL certificate after verifing the SCA server identity. Then, the client and server use both certificates to generate a unique key used to sign requests sent between them.

This kind of authentication is implemented when the customer call your servers that will then call the Securibox Cloud Agents API.

In order to use this type of authentication, Securibox will provide a PEM certificate file containing a passphrase protected private key and a public key.

use Securibox\CloudAgents\Documents\ApiClient;

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

JSON Web Token Authentication

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a public/private key pair using RS256 (RSA PKCS#1 signature with SHA-256).

This kind of authentication is implemented when the customer calls directly the Securibox Cloud Agents API together with cross-origin resource sharing (CORS).

In order to use this type of authentication, Securibox will provide a passphrase protected RSA private key in PEM file (.pem).

use Securibox\CloudAgents\Documents\ApiClient;

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

Getting started

The following is the minimum needed code to list all agent details and fields:

<?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/CloudAgents.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");
    }
}

The following code is the minimum code needed to configure an agents and launch a synchronization:

<?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/CloudAgents.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());