Server Setup

The Insight Agent download contains an agent binary executable for various operating systems and architectures. Run the command ./agent help for more information on how to use it.

The main function of the agent executable is to start the Insight Agent that receives Insight data from connected apps. It can run directly on an on-premises server, or be deployed to a cloud environment. Use the following command to start the agent:

./agent run --keys keys.json --conf conf.yaml

Note that a keys.json and conf.yaml file are needed to start the agent.

You can optionally add the --log-mode DEBUG or --log-mode DEBUG_JSON flag when starting the agent to see more debugging information. The DEBUG_JSON mode is useful for viewing structured logs in a cloud environment.

Keys

The Insight Agent uses public and private keys to securely communicate with an app. The agent executable can generate these keys for you. Running the command ./agent genkey prints the following information:

1). Add this private key the server's keys.json.
Ensure the keyGen entropy is the same for all instances.
Optionally, add client public key to 'allowed_clients' list.
***
The server public key for the Shielder configuration.xml is: R6Ebzldq24J3M4SKFLdjavW4y4S0Ruh046z28LDQ62M=
The client public key is: G+k4bs0xuPeCG0OgD1cALgFU0kqSYmC1X6M0NDJLCwc=
***
-----keys.json-----
{
 "server_keys": [
  {
   "comment": "Main Key",
   "private_key": "pHmuKDuNHRn34SNhH3tbRt4q2e+9sb8SEgkwXqB0OxE=","allowed_clients": [
    "G+k4bs0xuPeCG0OgD1cALgFU0kqSYmC1X6M0NDJLCwc="
   ]
  }
 ],"key_gen_entropy": "k5LdhODZZdb9uAxID2T+uFsVJ0WEL9f80Uk8+/zuoq7EwSf+dWoqKLI//cNB3irhV+lwJMJzqJt5kifBU77S/Q=="
}
-----END OF keys.json-----

2). Add the client private and server public keys in the Shielder configuration.xml.
-----configuration.xml-----
<?xml version="1.0" encoding="UTF-8"?>
<shield>
 <config>
  ...
  <insightServerPublicKey v="R6Ebzldq24J3M4SKFLdjavW4y4S0Ruh046z28LDQ62M="/>
  <insightClientPrivateKey v="m28J17YFOdeWGMnAKWRNC6xanbwV/J/CDszxSucDQAI="/>
  ...
 </config>
</shield>
-----END OF configuration.xml-----

You are expected to copy and paste the first block of text into a keys.json file. This file needs to be discoverable by the agent when the server is started. For reference, the keys.json file looks like the following example:

{
  "server_keys": [
    {
      "comment": "Main Key",
      "private_key": "pHmuKDuNHRn34SNhH3tbRt4q2e+9sb8SEgkwXqB0OxE=","allowed_clients": [
        "G+k4bs0xuPeCG0OgD1cALgFU0kqSYmC1X6M0NDJLCwc="
      ]
    }
  ],"key_gen_entropy": "k5LdhODZZdb9uAxID2T+uFsVJ0WEL9f80Uk8+/zuoq7EwSf+dWoqKLI//cNB3irhV+lwJMJzqJt5kifBU77S/Q=="
}

If the allowed_clients property is set to null or an empty list (i.e., []), then any app with a valid key can connect to the agent. If you want to limit access to certain clients, then add their public key (as seen in the ./agent genkey output) in a list here.

The genkey command generates different keys each time. Make sure you update the server and client configurations at the same time to avoid a mismatch.

Server Configuration

The Insight Agent download includes a conf.yaml file that is needed when running ./agent run. The provided configuration file looks like the following example:

serverConf:
  bindAddress: 0.0.0.0:8080
  agentId: ${AGENT_ID}

httpSinks:
   - name: theHub
     endpoint: https://insight.hub.app-analytic.com/${AGENT_ID}/ingest/v2
     encoding: PROTOBUF
     headers:
       X-Promon-API-Key: ${AGENT_TOKEN}

The ${ } syntax denotes a substitution placeholder for an environment variable. The AGENT_ID and AGENT_TOKEN are credentials specific to your license and should be set in the OS’s environment.

The httpSinks configuration is already set up to communicate with the Insight Cloud (i.e., theHub) with the appropriate credentials.

The serverConf is configured to start the Insight Agent on the default host (0.0.0.0) of your server and port 8080, but these can be changed per your needs. The actual agent endpoint becomes available on the path /insight. The Insight Client makes POST and GET requests to this endpoint, so both connections must be opened.

The Insight Agent only exposes an HTTP endpoint, not an HTTPS endpoint. You will need to configure the HTTPS protocol yourself. When setting up a new server, be mindful that you might need to explicitly install the ca-certificates package to ensure proper SSL/TLS functionality.

After you have deployed the agent, you should report the host address and server region to OneSpan. This helps OneSpan perform health checks and minimize network latency. In the Download Portal, under Insight > Agent, fill in the fields for Agent Host and Agent Region. Note that only Admin users have access to this page.

Downstream Endpoints

The Insight Agent is able to forward messages to other endpoints and not just the Insight Cloud. These downstream endpoints are defined in the agent YAML config file as additional httpSinks. For example:

httpSinks:
  - name: my-server
    endpoint: https://my-downstream-server.com/events
    encoding: PROTOBUF
    forwardCustomData: true
  - name: third-party-server
    endpoint: https://some-other-server.com/api
    encoding: JSON
    forwardCustomData: true
    headers:
      X-Custom-Header: abcdefg

The Insight Agent then makes a POST request to each HTTP sink. HTTP sinks support the following configuration options:

It is recommended to use Protocol Buffers instead of JSON, as they are generally faster, but doing so requires the receiving server to implement the libshield.proto specification to properly decode the messages. See the Protocol Buffer documentation for examples of compiling and parsing Protocol Buffers in various server-side languages.

The overall performance of message delivery is also affected by concurrency, though the relationship between the number of threads and latency is non-linear. Increasing the concurrency setting will not necessarily improve throughput, as latency is often limited by a single thread. However, reducing the number of connections can be useful for measuring single-thread performance or limiting server load.