Skip to content

Commit 97edeae

Browse files
joaomrodriguesjoaomrodrigues
committed
Corrected JWT generation and documented the webview url generation
1 parent 1ba63c5 commit 97edeae

4 files changed

Lines changed: 186 additions & 150 deletions

File tree

‎README.md‎

Lines changed: 168 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -1,144 +1,169 @@
1-
# cloudagents-php
2-
[![Packagist Version][packagist-image]][packagist-url]
3-
4-
A PHP client library for the [Securibox Cloud Agents API][1]
5-
6-
## Install Package
7-
Securibox Cloud Agent PHP wrapper is installed via [Composer](http://getcomposer.org).
8-
Simply run the following command:
9-
```bash
10-
composer require securibox/cloudagents
11-
```
12-
13-
#### Alternative: Install package from zip
14-
If you are not using Composer, simply download and install the **[latest packaged release of the library as a zip](https://github.com/Securibox/cloudagents-php/archive/master.zip)**.
15-
16-
## Authentication
17-
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.
18-
19-
## Basic API Authentication w/ TLS
20-
Basic API authentication is the easiest of the three to implement offering the lowest security options of the common protocols.
21-
This mechanism is usually advised for testing purposes in order to test the APIs and only requires Securibox to provide a username and password.
22-
```php
23-
use Securibox\CloudAgents\Documents\ApiClient;
24-
25-
$client = ApiClient::AuthenticationBasic("username", "password");
26-
```
27-
28-
### SSL Client Certificate Authentication
29-
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.
30-
31-
This kind of authentication is implemented when the customer call your servers that will then call the Securibox Cloud Agents API.
32-
33-
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.
34-
```php
35-
use Securibox\CloudAgents\Documents\ApiClient;
36-
37-
$client = ApiClient::SslClientCertificate("C:\Path\to\PEM Certificate", "PEM pass phrase");
38-
```
39-
40-
### JSON Web Token Authentication
41-
[JSON Web Token (JWT)](https://jwt.io) 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).
42-
43-
This kind of authentication is implemented when the customer calls directly the Securibox Cloud Agents API together with [cross-origin resource sharing (CORS)](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing).
44-
45-
In order to use this type of authentication, Securibox will provide a passphrase protected RSA private key in PEM file (.pem).
46-
```php
47-
use Securibox\CloudAgents\Documents\ApiClient;
48-
49-
$client = ApiClient::Jwt("C:\Path\to\PEM private key", "PEM pass phrase");
50-
```
51-
52-
## Getting started
53-
The following is the minimum needed code to list all agent details and fields:
54-
```php
55-
<?php
56-
// If you are using Composer (recommended)
57-
require 'vendor/autoload.php';
58-
use Securibox\CloudAgents\Documents\ApiClient;
59-
use Securibox\CloudAgents\Documents\Entities;
60-
61-
// If you are not using Composer
62-
// require("path/to/cloudagents-php/src/CloudAgents.php");
63-
64-
$client = ApiClient::AuthenticationBasic("Basic Username", "Basic Password");
65-
$agents = $client->GetAgents();
66-
foreach($agents as $agent){
67-
print("\n\n\n------ Agent Details ------\n");
68-
print("ID: ".$agent->id."\n");
69-
print("Name: ".$agent->name."\n");
70-
print("Periodicity: ".$agent->agentPeriodicity."\n");
71-
print("Current Status: ".$agent->agentCurrentState."\n");
72-
print("Category: ".$agent->category."\n");
73-
foreach($agent->fields as $field){
74-
print(" Field[". $field->position ."]: ".$field->name."\n");
75-
}
76-
}
77-
```
78-
79-
The following code is the minimum code needed to configure an agents and launch a synchronization:
80-
```php
81-
<?php
82-
// If you are using Composer (recommended)
83-
require 'vendor/autoload.php';
84-
use Securibox\CloudAgents\Documents\ApiClient;
85-
use Securibox\CloudAgents\Documents\Entities;
86-
87-
// If you are not using Composer
88-
// require("path/to/cloudagents-php/src/CloudAgents.php");
89-
90-
//Configure account properties
91-
$account = new Entities\Account();
92-
$account->agentId = 'c42f0150d2eb47ee8fa56bce25e49b8d';
93-
$account->customerAccountId = 'Account201708082';
94-
$account->customerUserId = 'User123';
95-
$account->name = 'Test Account 1';
96-
$account->credentials = array();
97-
98-
//Configure credentials
99-
$username = new Entities\Credential();
100-
$username->position = 0;
101-
$username->value = 'username@test.com';
102-
103-
//Configure credentials
104-
$password = new Entities\Credential();
105-
$password->position = 1;
106-
$password->value = '###password###';
107-
108-
array_push($account->credentials, $username, $password);
109-
110-
//Setup client
111-
$client = new ApiClient::AuthenticationBasic("Basic Username", "Basic Password");
112-
113-
//Create the account which automatically launches a synchronization
114-
$returnedAccount = $client->CreateAccount($account);
115-
116-
//Let's wait until the synchronization has reached a final status
117-
$synchronization = $client->GetLastSynchronizationByAccount($returnedAccount->customerAccountId);
118-
while($synchronization->synchronizationState != "PendingAcknowledgement" &&
119-
$synchronization->synchronizationState != "Completed" &&
120-
$synchronization->synchronizationState != "ReportFailed"){
121-
sleep(5);
122-
$synchronization = $client->GetLastSynchronizationByAccount($returnedAccount->customerAccountId);
123-
}
124-
125-
//Let's get the newly downloaded documents and save them locally
126-
$documents = $client->GetDocumentsByAccount($account->customerAccountId, 'true','true');
127-
$receivedFiles = array();
128-
foreach($documents as $document){
129-
$file = fopen("C:\\Temp\\".$document->name, "wb");
130-
$content = base64_decode($document->base64Content);
131-
fwrite($file, $content);
132-
fclose($file);
133-
array_push($receivedFiles, $document->id);
134-
}
135-
$client->AcknowledgeSynchronizationForAccount($account->customerAccountId, $receivedFiles, array());
136-
```
137-
## License
138-
[GNU GPL][3]
139-
140-
[1]: https://sca.securibox.eu
141-
[2]: https://sca.securibox.eu/doc.html
142-
[3]: https://github.com/Securibox/cloudagents-phpblob/master/LICENSE
143-
[packagist-image]: https://img.shields.io/badge/packagist-1.0.2-blue.svg
1+
# cloudagents-php
2+
[![Packagist Version][packagist-image]][packagist-url]
3+
4+
A PHP client library for the [Securibox Cloud Agents API][1]
5+
6+
## Install Package
7+
Securibox Cloud Agent PHP wrapper is installed via [Composer](http://getcomposer.org).
8+
Simply run the following command:
9+
```bash
10+
composer require securibox/cloudagents
11+
```
12+
13+
#### Alternative: Install package from zip
14+
If you are not using Composer, simply download and install the **[latest packaged release of the library as a zip](https://github.com/Securibox/cloudagents-php/archive/master.zip)**.
15+
16+
## Authentication
17+
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.
18+
19+
## Basic API Authentication w/ TLS
20+
Basic API authentication is the easiest of the three to implement offering the lowest security options of the common protocols.
21+
This mechanism is usually advised for testing purposes in order to test the APIs and only requires Securibox to provide a username and password.
22+
```php
23+
use Securibox\CloudAgents\Documents\ApiClient;
24+
25+
$client = ApiClient::AuthenticationBasic("username", "password");
26+
```
27+
28+
### SSL Client Certificate Authentication
29+
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.
30+
31+
This kind of authentication is implemented when the customer call your servers that will then call the Securibox Cloud Agents API.
32+
33+
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.
34+
```php
35+
use Securibox\CloudAgents\Documents\ApiClient;
36+
37+
$client = ApiClient::SslClientCertificate("C:\Path\to\PEM Certificate", "PEM pass phrase");
38+
```
39+
40+
### JSON Web Token Authentication
41+
[JSON Web Token (JWT)](https://jwt.io) 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).
42+
43+
This kind of authentication is implemented when the customer calls directly the Securibox Cloud Agents API together with [cross-origin resource sharing (CORS)](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing).
44+
45+
In order to use this type of authentication, Securibox will provide a passphrase protected RSA private key in PEM file (.pem).
46+
```php
47+
use Securibox\CloudAgents\Documents\ApiClient;
48+
49+
$client = ApiClient::Jwt("C:\Path\to\PEM private key", "PEM pass phrase");
50+
```
51+
52+
## Getting started
53+
The following is the minimum needed code to list all agent details and fields:
54+
```php
55+
<?php
56+
// If you are using Composer (recommended)
57+
require 'vendor/autoload.php';
58+
use Securibox\CloudAgents\Documents\ApiClient;
59+
use Securibox\CloudAgents\Documents\Entities;
60+
61+
// If you are not using Composer
62+
// require("path/to/cloudagents-php/src/CloudAgents.php");
63+
64+
$client = ApiClient::AuthenticationBasic("Basic Username", "Basic Password");
65+
$agents = $client->GetAgents();
66+
foreach($agents as $agent){
67+
print("\n\n\n------ Agent Details ------\n");
68+
print("ID: ".$agent->id."\n");
69+
print("Name: ".$agent->name."\n");
70+
print("Periodicity: ".$agent->agentPeriodicity."\n");
71+
print("Current Status: ".$agent->agentCurrentState."\n");
72+
print("Category: ".$agent->category."\n");
73+
foreach($agent->fields as $field){
74+
print(" Field[". $field->position ."]: ".$field->name."\n");
75+
}
76+
}
77+
```
78+
79+
The following code is the minimum code needed to configure an agents and launch a synchronization:
80+
```php
81+
<?php
82+
// If you are using Composer (recommended)
83+
require 'vendor/autoload.php';
84+
use Securibox\CloudAgents\Documents\ApiClient;
85+
use Securibox\CloudAgents\Documents\Entities;
86+
87+
// If you are not using Composer
88+
// require("path/to/cloudagents-php/src/CloudAgents.php");
89+
90+
//Configure account properties
91+
$account = new Entities\Account();
92+
$account->agentId = 'c42f0150d2eb47ee8fa56bce25e49b8d';
93+
$account->customerAccountId = 'Account201708082';
94+
$account->customerUserId = 'User123';
95+
$account->name = 'Test Account 1';
96+
$account->credentials = array();
97+
98+
//Configure credentials
99+
$username = new Entities\Credential();
100+
$username->position = 0;
101+
$username->value = 'username@test.com';
102+
103+
//Configure credentials
104+
$password = new Entities\Credential();
105+
$password->position = 1;
106+
$password->value = '###password###';
107+
108+
array_push($account->credentials, $username, $password);
109+
110+
//Setup client
111+
$client = new ApiClient::AuthenticationBasic("Basic Username", "Basic Password");
112+
113+
//Create the account which automatically launches a synchronization
114+
$returnedAccount = $client->CreateAccount($account);
115+
116+
//Let's wait until the synchronization has reached a final status
117+
$synchronization = $client->GetLastSynchronizationByAccount($returnedAccount->customerAccountId);
118+
while($synchronization->synchronizationState != "PendingAcknowledgement" &&
119+
$synchronization->synchronizationState != "Completed" &&
120+
$synchronization->synchronizationState != "ReportFailed"){
121+
sleep(5);
122+
$synchronization = $client->GetLastSynchronizationByAccount($returnedAccount->customerAccountId);
123+
}
124+
125+
//Let's get the newly downloaded documents and save them locally
126+
$documents = $client->GetDocumentsByAccount($account->customerAccountId, 'true','true');
127+
$receivedFiles = array();
128+
foreach($documents as $document){
129+
$file = fopen("C:\\Temp\\".$document->name, "wb");
130+
$content = base64_decode($document->base64Content);
131+
fwrite($file, $content);
132+
fclose($file);
133+
array_push($receivedFiles, $document->id);
134+
}
135+
$client->AcknowledgeSynchronizationForAccount($account->customerAccountId, $receivedFiles, array());
136+
```
137+
138+
## Webview url
139+
In order to use the webview and avoid having to implement the APIs to list and configure accounts, a webview has been developped.
140+
In this webview, a customer can:
141+
- Browse and search all agents
142+
- Have quick access to predefined favorite agents
143+
- List the configured agents
144+
- Configure, modify or delete an agent account
145+
- See the list of synchronizations for each account
146+
147+
To use the webview, activate it in the CloudAgents backoffice and use the provided PEM private key to sign the token.
148+
149+
The webview accepts the following url arguments:
150+
- token: json web token signed with the PEM certificate
151+
- callback: url where the user is sent on logging out <sub><sup>(ex: https://www.myapp.com - if a state has been provided: https://www.myapp.com?state={state})</sup></sub>
152+
- lang <sup>optional</sup>: culture to display the page - By default, in fr-FR
153+
154+
Example:
155+
```
156+
https://sca-webview.azurewebsites.net?token={token}&callback={callback_url}&state={stateData}
157+
https://sca-webview.azurewebsites.net?token={token}&callback={callback_url}&state={stateData}&lang=en-us
158+
```
159+
For examples in php to generate the token, [please refer to the test][4].
160+
161+
## License
162+
[GNU GPL][3]
163+
164+
[1]: https://sca.securibox.eu
165+
[2]: https://sca.securibox.eu/doc.html
166+
[3]: https://github.com/Securibox/cloudagents-phpblob/master/LICENSE
167+
[4]: https://github.com/Securibox/cloudagents-php/blob/master/test/WebView.php
168+
[packagist-image]: https://img.shields.io/badge/packagist-1.0.2-blue.svg
144169
[packagist-url]: https://packagist.org/packages/securibox/cloudagents

‎composer.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
"description": "API wrapper for Securibox Cloud Agents.",
55
"homepage": "https://github.com/Securibox/cloudagents-php",
66
"keywords": ["cloud","agents","connectors","securibox","sca","sbx","cloudagents"],
7-
"version": "1.1.9",
7+
"version": "1.2.0",
88
"license": "GPL-3.0-only",
99
"authors": [
1010
{

‎src/Documents/ApiClient.php‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -80,11 +80,11 @@ public static function Jwt($privateKey, $privateKeyPassPhrase, $apiEndpoint = "h
8080
*
8181
* @param string $privateKey private key file path or content
8282
* @param string $privateKeyPassPhrase private key file passphrase
83-
* @param string $apiEndpoint the base url (e.g. https://sca-multitenant.securibox.eu/api/v1)
84-
* @param string $customerUserId if used, an additional 'cuid' claim is included in the token.
83+
* @param string $customerUserId if used, an additional 'uid' claim is included in the token.
84+
* @param string $apiEndpoint the base url (e.g. https://sca-multitenant.securibox.eu)
8585
* This claim limits resource access to the ones owned by the specified user
8686
*/
87-
public static function BuildJwt($privateKey, $privateKeyPassPhrase, $apiEndpoint = "https://sca-multitenant.securibox.eu/api/v1", $customerUserId = null){
87+
public static function BuildJwt($privateKey, $privateKeyPassPhrase, $customerUserId = null, $apiEndpoint = "https://sca-multitenant.securibox.eu"){
8888
$key = new Http\JWT\Key($privateKey, $privateKeyPassPhrase);
8989
$signer = new Http\JWT\Signer\Sha256();
9090
$url_components = \parse_url($apiEndpoint);
@@ -96,7 +96,7 @@ public static function BuildJwt($privateKey, $privateKeyPassPhrase, $apiEndpoint
9696
->issuedAt(time())
9797
->expiresAt(time() + 3600);
9898
if ($customerUserId !== null) {
99-
$builder->withClaim('cuid', $customerUserId);
99+
$builder->withClaim('uid', $customerUserId);
100100
}
101101
return $builder->getToken($signer, $key);
102102
}

‎test/WebView.php‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,21 @@
88

99
class CloudAgentsWebView extends TestCase{
1010

11+
/**
12+
* Example to generate webview url
13+
*
14+
* This is an example to generate the webview URL with the needed arguments:
15+
* - state: data that is sent in argument to the callback url.
16+
* - callback: url where the user is sent on logging out (ex: https://www.myapp.com - if a state has been provided: https://www.myapp.com?state={state})
17+
* - lang [optional: by default fr-fr]: culture to display the page
18+
* URL examples:
19+
* https://sca-webview.azurewebsites.net?token={token}&callback={callback_url}&state={stateData} => Displays page in french
20+
* https://sca-webview.azurewebsites.net?token={token}&callback={callback_url}&state={stateData}&lang=en-us => Displays page in english
21+
*/
1122
public function testGenerateWebViewLink(){
1223
$pem = file_get_contents("C:\\Temp\\JWT\\key.pem");
13-
$token = ApiClient::BuildJwt($pem, "password","https://sca-multitenant.securibox.eu", "asdasdasd");
14-
$url = "https://sca-webview.azurewebsites.net?token=".$token;
24+
$token = ApiClient::BuildJwt($pem, "private_key_password", "customer1234");
25+
$url = "https://sca-webview.azurewebsites.net?token=".$token."&callback=https://www.myapp.com&state=customerData";
1526
var_dump($url);
1627
}
1728

0 commit comments

Comments
 (0)