2.4. Cross-Domain API

Although cookie and client certificate integration methods work well under most scenarios, however, both methods heavily depend on browser applications and sometimes require end-users interaction which could introduce usability issues. MetaAccess now offers a cross-domain API for you to integrate with your solution. This method leverages JSONP technology to overcome the cross-domain restrictions imposed by browsers' same-origin policy that limits access to resources retrieved from origins other than the one the page was served by.

The cross-domain API can be enabled on MetaAccess console as the screenshot below.

images/download/attachments/31845527/Integrations-3.PNG

Once the cross-domain API setting is enabled, MetaAccess agent tries to open a cross-domain API at the configured port on an endpoint. Please make sure that the configured port is valid and not used by any existing applications running on the same endpoint.

Whenever MetaAccess agent is uninstalled, the cross-domain API will be closed and the configured port will be released on the endpoint.

API Description

Request

 

Description

URL path

https://eapi.opswatgears.com:[configured port]/opswat/devinfo

Method

GET

In which:

  • configured port: the port you configured for the cross-domain API settings on MetaAccess account which the endpoint is reporting to.

  • eapi.opswatgears.com is resolved as 127.0.0.1. If endpoints are running proxy, you need to add exception on the proxy settings to ignore queries to eapi.opswatgears.com.

For example:

https://eapi.opswatgears.com:11369/opswat/devinfo

Success response

The response json will be padded by the value of "callback" parameter

{
"code": number,
"description": string,
"info": {
"hwid": string
}
}

Error response

{
"code": number,
"description": string
}


Key

DataType

Definition

code

number

Status code. Values could be:

  • 0: success

  • -30: Timeout

  • -31: API not found

  • -41: Failed to get hardware id

description

string

result details

info

object

device information

info.hwid

string

device id of the device. This information is used to query device information from the cloud.

Sample code


Client sample (you can download from here)

<html>
<head>
</head>
<body>
<div style="margin-top: 25px; margin-bottom: 25px"> THIS IS A DEMO TO RETRIVE DEVICE ID OF THE LOCAL DEVICE</div>
<div id="loader" style="display: none; position: fixed;left: 0px;top: 0px;width: 100%;height: 100%;z-index: 9999;background: url('page-loader.gif') 50% 50% no-repeat rgb(249,249,249);"></div>
Server Port: <input type="text" id="server_port" value="11369" placeholder="11369"/><p>
 
<div>
<input type="button" value="Get Agent Info" onClick="submitGetAgentInfo()">
<div id="error_msg" style="color: red; margin-top: 10px;"> </div>
</div>
 
<div id="hwid_field"> </div>
<script type="text/javascript" src="jquery-3.1.1.min.js"></script>
<script type="text/javascript" src="opswat.jsonp.js"></script>
<script type="text/javascript">
function myCallback( data_back ){
$('#loader').hide();
// callback function to handle response from cloud
if ( data_back.code < 0 ) {
$('#error_msg').html("Error: " + data_back.description );
return;
}
$('#hwid_field').text('Device ID: '+ data_back.info.hwid);
}
function submitGetAgentInfo()
{
$('#hwid_field').text('');
$('#error_msg').html('');
$('#loader').show();
// Using Opswat lib prototype to make a request to cloud
var server_port = $('#server_port').val();
var casb = new OpswatJSONP();
casb.jsonp({
'serverPort': server_port,
'callback' : myCallback
});
}
</script>
</body>
</html>

Note: you can find jquery-3.1.1.min.js and opswat.jsonp.js in the sample package.

Success response:

{
"code": 0,
"description": "Success",
"info": {
"hwid": "7EF012F7AB8E454FA37B0D2E9A2E812C"
}
}

Error response:

{
"code": -41,
"description": "Hardware ID failed to get"
}

Support chart

As of November 10th, 2016, Cross-Domain API solution is only supported on persistent agents.

 

Persistent agent

On-demand agent

Windows

images/download/attachments/31845527/Yes.PNG

images/download/attachments/31845527/No.PNG

macOS

images/download/attachments/31845527/Yes.PNG

images/download/attachments/31845527/No.PNG

Linux

images/download/attachments/31845527/No.PNG

 

Android

images/download/attachments/31845527/No.PNG

 

iOS

images/download/attachments/31845527/No.PNG

 

Legend

Description

images/download/attachments/31845527/Yes.PNG

Supported

images/download/attachments/31845527/No.PNG

Not yet supported

As Septempber 27, 2017, MetaAccess releases a new agent version which supports https protocol for the cross-domain API.

  • Windows persistent agent version: 7.6.121.0+

  • macOS persistent agent version: 10.4.147.0+