The generic HTTP API integration enables Border0 administrators to use external sources for evaluating access to services in their Border0 organization. In other words, Border0 organization administrators can use the HTTP API integration to configure Border0 to make HTTP requests to any public HTTP service, and use the HTTP response (status code and/or response body) to determine whether access should be granted or denied for a given client.

Example use cases:

• Use an IP reputation HTTP service to block access from well-known bad IPs
• Use your company's custom evaluation service to evaluate access based on your own custom logic

To integrate with a generic HTTP API, you will first need to gather certain parameters.

HTTP Integration Configuration

👍

Important: injectable parameters

The HTTP integration configuration fields http method, url, headers, and body can all have certain parameters injected at the time the integration is evaluated/used by Border0. These parameters include protocol, email, and ip of a connecting client and the target socket_id and socket_name.

This can be achieved by including the following in your configuration fields:

• ${inject::protocol}
• ${inject::email}
• ${inject::ip}
• ${inject::socket_id}
• ${inject::socket_name}

(1) Name (required)

The integration's "name" is a unique identifier for the integration within your Border0 organization. In other words, no two integrations for the same Border0 organization can have the same name.

Name must start with an alphanumeric character [a-zA-Z0-9] and can only consist of alphanumeric characters and dashes ('-') - it must not include spaces.

🚧

Note

Name is the only parameter which can not be changed after creation-time.

(2) Description

The integration's "description" is a short phrase describing what the integration does or what its purpose is.

(3) HTTP Method (required)

The integration's "HTTP method" is the HTTP method with which HTTP requests will be made. Some examples include GET, POST, PUT, DELETE, ...

(4) URL (required)

The integration's "URL" is the URL (including any query parameters) for which the HTTP request will be made. Some examples:

• https://myserver.com/access_request
• https://myserver.com/access_request?source=border0
• https://myserver.com/access_request?protocol=${inject::protocol}&email=${inject::email}&ip=${inject::ip}
• https://api.abuseipdb.com/api/v2/check?ipAddress=${inject::ip}

(5) Headers

The integration's "headers" are the HTTP headers that will be included in the HTTP request. Note that repeated HTTP header keys are allowed - when the HTTP request is made, values for the same header key will be separated by a comma (,) as per HTTP RFC 2616.

Examples:

• With unique keys and injected IP parameter

• With repeated header keys

(6) Body

The integration's "HTTP Body" is the raw payload that will be sent as the body of the HTTP request. This can be JSON or ASCII-text. For example

{
   "ip":"${inject::ip}",
   "email":"${inject::email}",
   "protocol":"${inject::protocol}",
   "socket_id":"${inject::socket_id}",
   "socket_name":"${inject::socket_name}"
}

The example below shows how we're creating a body, that injects the IP address of the user, the email address and the protocol. The HTTP policy integration will now have access to these variables.

HTTP Integration Policy Usage

Currently the HTTP integration can only be used as a policy-integration. In other words, http integrations are used for Border0 to determine whether a given client should be granted or denied access to a Border0 service in your organization.

In order to configure an HTTP integration for use within a policy, you must first configure at least one HTTP integration within your Border0 organization.

Once you have an integration in your organization, the policy editor (in the policies page in the portal) will expose the option to add an integration to any given policy.

HTTP Integration Policy Configuration

(1) require_response_status_code

The require_response_status_code field may be populated with an HTTP response status code that the HTTP API will respond with to when a Border0 service client's connection should be allowed.

If the require_response_status_code check is set and the HTTP API responds with a status code that does not match this value, the client's connection request will not fulfil the policy integration.

(2) require_response_body_expression

The require_response_body_expression field may be populated with a JQ query expression to compare against the HTTP response body returned by the HTTP API. The JQ query must return true for the client's connection to be allowed by the policy integration.

🚧

Heads-up!

Neither the require_response_status_code nor the require_response_body_expression checks are required as long as at least one of them is populated (otherwise your policy integration is a NO-OP).

📘

Note

You may want to use the policy tester to determine whether your policy configuration behaves as expected!

Example

Assume you have configured the following HTTP integration in your Border0 organization.

More context:

https://www.abuseipdb.com/ is a crowd-sourced IP reputation service. In the following example we add an HTTP integration representing the AbuseIPDB API, and we will use it to check the source IP of client connections against its data to determine whether the connection is coming from a well-known bad IP.

Important things to note are that:

• we will be making an HTTP request to the check endpoint https://docs.abuseipdb.com/#check-endpoint and using an injected parameter for the client IP address in the ipAddress query parameter, where the AbuseIPDB API expects the IP to be provided
• The Key header is populated with an API key gotten from the AbuseIPDB service by signing up for a free account

Then we can proceed to add our HTTP integration to a policy:

👍

Note

The integration name and type will be pre-populated for you based on the integration you select from the dropdown.

More context:

The documentation of the check endpoint demonstrates what the expected response payload looks like. It also describes that the status code of a successful request will be 200, and that API clients should pay attention to the abuseConfidenceScore returned in the JSON response to make decisions about access control.

The documentation goes on to describe that the abuseConfidenceScore is a score between 0 and 100, where 100 means that AbuseIPDB is 100% confident that the IP provided is malicious or has been reported to engage in abuse recently.

Below we use a JQ query expression that will return true whenever the abuseConfidenceScore is less than 5.