This tutorial provides step by step instructions on how to build your rocket ship cybersecurity app using the HacWare Security Awareness API and the PHP programming language.

How to Build a Customer Account using the Awareness API?

Step1: Implement the REDIRECTION_URL PHP REST API

We’ll create a /public/index.php file to serve as our endpoint for the redirection_url after the add-customer endpoint request is complete.

public/index.php

<?php

$subdomain = $_POST['sub_domain'];

$sec = $_POST['sec'];

echo "Add-customer complete.  We have the keys!";
$php -S 127.0.0.1:8000 -t public

Once the secret key and subdomain is returned as a parameter the redirection_url endpoint.

Step 2: Add Authentication to Your PHP REST API

Use the domain and key from the last step to call the API Auth endpoint. This step is required to get the access token to access the customer endpoints and other resources.


$url = 'https://$subdomain/api/v1/auth/';
$appid = 'DEVELOPER_ID';
$sec = $_POST['sec'];

$data = array('appid' => '$appid', 'sec' => '$sec');

$options = array(
    'http' => array(
        'method'  => 'POST',
        'content' => http_build_query($data)
    )
);
$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);

$token = $result['access_token'];
$refresh = $result['refresh_token'];

echo "We have the access token!";

Now that we have the access token you can manage the customer's phishing and training needs.

API Access Flow Diagram

Step 3: Add Users to Your New Customer

Next, import the customer's users for security awareness training using the Add New Users endpoint.


$url = 'https://$subdomain/api/v1/user/add-users/'
$data_users = array(
   'firstname' => 'Jane', 
   'lastname' => 'Doe', 
   'email' => 'jane@company.com'
);
$data_users2 = array(
   'firstname' => 'Jane2', 
   'lastname' => 'Doe2', 
   'email' => 'jane2@company.com'
 );

$data = array('data' => array($data_users, $data_users2));

$options = array(
    'http' => array(
        'header'  => "Authorization : Bearer $token\r\n",
        'header'  => "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => http_build_query($data)
    )
);
$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$result['message'];

Step 4: Implement the Add-Customer REST API  and Test the REDIRECTION_URL PHP code

To test the code in this tutorial, make a post request to the add-customer API endpoint.  Check out the following php code to build a customer programmatically. The key to testing this code is to set the redirection_url parameter.  In this example, we are setting the redirection_url to http://localhost:8000/index.php.  In your example, the redirection_url should be replaced with the developer defined url.

$url = 'https://hacware.com/api/dev/add-customer/'
$data = array(
'fullname' => 'Shane Doe', 
'user_email' => 'shane@company.com', 
'company_name' => 'Company, Inc.', 
'company_alias' => 'Company', 
'ceo_name' => 'Jane Leader', 
'ceo_email' => 'Jane@company.com', 
'so_name' => 'Joe Security', 
'so_email' =>  'security@company.com', 
'so_phone' => '214-555-5555', 
'employee_count' => '1000', 
'redirection_url' => 'http://localhost:8000/index.php');

$developer_email="ENTER_YOUR_DEVELOPER_LOGIN_EMAIL"

$options = array(
    'http' => array(
        'header'  => "appid : $appid\r\n",
        'header'  => "email : $developer_email\r\n",
        'method'  => 'POST',
        'content' => http_build_query($data)
    )
);
$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$result['result'];
Sample test for making a Add Customer request with PHP

Now let's put it all together!  Here is the sample file for the redirection_url to get the secret key, get access token, and add users to the customer account.

<?php

$subdomain = $_POST['sub_domain'];
$sec = $_POST['sec'];
$url = 'https://$subdomain/api/v1/auth/';
$appid = 'DEVELOPER_ID';
$data = array('appid' => '$appid', 'sec' => '$sec');

$options = array(
    'http' => array(
        'method'  => 'POST',
        'content' => http_build_query($data)
    )
);
$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);

$token = $result['access_token']
$refresh = $result['refresh_token']

$url = 'https://$subdomain/api/v1/user/add-users/'
$data_users = array(
   'firstname' => 'Jane', 
   'lastname' => 'Doe', 
   'email' => 'jane@company.com'
);

$data_users2 = array(
   'firstname' => 'Jane2', 
   'lastname' => 'Doe2', 
   'email' => 'jane2@company.com'
);

$data = array('data' => array($data_users, $data_users2));

$options = array(
    'http' => array(
        'header'  => "Authorization : Bearer $token\r\n",
        'header'  => "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => http_build_query($data)
    )
);
$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$result['message'];

Full Sample code of PHP REST API for Redirection_URL

Don't forget to start the server!

php -S 127.0.0.1:8000 -t public

That’s it!  Happy Building!


Learn more about HacWare at hacware.com. We would love to automate your security education needs, click here to learn more about our developer program.