Policies are used to control who has access to what Sockets and under what conditions. Think of policies as advanced, Identity-, application-aware, and context-aware firewall rules. Unlike traditional firewalls or access control list (ACL) rules, Border0 policies allow you to define access rules based on Identity, time of day, application type, and location.

Each time a user tries to access a Socket through Border0, our platform will evaluate all policies that are attached to the Socket. The verdict is the cumulative result of all policies. If no policies match or no policies are attached to a Socket, no access will be granted.

📘
Two types of policies
A policy can, optionally, be marked as an Organization wide policy. This means it will automatically be applied to all Sockets in your organization. Where-as a regular policy needs to explicitly linked to a Socket.

Policy Components

high level, a Policy consists of two sections:

Action
Condition

In addition it requires a version number, called version, which should be set to "v1".
Below is an example policy.

{
    "action": [
      "database:*",
      "ssh:*",
    	"http:*"
    ],
    "condition": {
        "who": {
            "domain": [
                "example.com",
                "foo.io"
            ],
            "email": [
                "[email protected]",
                "[email protected]"
            ]
        },
        "where": {
            "allowed_ip": [
                "0.0.0.0/0"
            ],
            "country": [
                "NL",
                "CA",
                "US",
                "BR",
                "FR"
            ]
        },
        "when": {
            "after": "2021-12-31T00:00Z",
            "before": null,
            "time_of_day_after": "00:00 UTC",
            "time_of_day_before": "23:59 UTC"
        }
    },
    "version": "v1"
}

Action

The action section defines what types of actions are allowed on a Socket. Three types of activities are supported

http
ssh
database
*

Multiple actions are allowed. For example, the action type "http" will allow any http action. So as a result, this will allow you access to an HTTP-based socket but not a database or SSH-based socket.
The * value indicates a wildcard, so all types of socket actions.

Condition

Conditions control under what conditions the action is allowed. This policy component is divided into 3 sections.

Who
Where
When

All condition sections are individually evaluated using the rules outlined below. All properties in the Condition section are optional. All Sections need to match before a user is allowed in, i.e. this is a logical AND.

Who

The who section defines what identities have access to the Socket service. You can specify zero or more domain or email address values. During the policy evaluation, these values are evaluated as a Logical OR. This means at least one of the emails or domains needs to match the user's identity to pass this section.
The domain is the last part of the users' identity. For example, in the case of [email protected], example.com would be the domain.

🚧
Define at least one property in the Who section
If no email or domain is defined, no one will be able to access your Sockets.

Where

The where section allows you to control where the user should be located. This can be either a list of IP addresses, countries, or countries that are not allowed.
Accepted properties are:

allowed_ip
This is a list of IP addresses in the CIDR format.
country
This is a list of two-letter country codes. The country code will be evaluated based on GEO IP values. Adding a country code means the user must come from that country to be allowed in.
country_not
This is a list of two-letter country codes. The country code will be evaluated based on GEO IP values. Adding a value as a country_not means that access will be denied if the user visits from that country.

All properties in the Where section are optional. You can leave them all empty or use one or two.
All properties in the Where section with a value need to match before a user is allowed in, i.e. this is a logical AND.

When

The when section allows an admin to control between which dates or what time of day access is permitted.
The following properties are supported:

after
during evaluation, we compare the current time and date against the date in the after value. The current time should be after the value defined here. This allows you to create only valid policies after a specific date.
before
during evaluation, we compare the current time and date against the date in the before value. The current time should be before the value defined here. This allows you to create policies that are valid before a specific date. Effectively, giving a policy an end or expiry date.
time_of_day_after
using the time_of_day_after property, you can control the time of day users have access. During evaluation, we compare the current time against the time in the time_of_day_after value. The current time should be after the value defined here.
time_of_day_before
using the time_of_day_before property, you can control the time of day users have access. During the evaluation, we compare the current time against the time in the time_of_day_before value. The current time should be before the value defined here.

You can control when a policy is active using the before and after properties. These properties are optional; you can define none, one, or both.

Using the time of day properties, administrators can control during what time of day users have access. For example, the following values will allow users access only between 7 am and 6 pm UTC.

            "time_of_day_after": "07:00:00 UTC",
            "time_of_day_before": "18:00:00 UTC"

These properties are optional, and you can define none, one, or both.

All properties in the When section are optional. You can leave them all empty or use one or two.
All properties in the When section with a value need to match before a user is allowed access, i.e., this is a logical AND.

Version

Currently the version should be set to "v1"

Valid date examples

📘
Time and Date format
We're fairly liberal in accepting date and time formats and will do our best to parse and guess the correct values. Below are a few examples of valid date and time formats we accept

+-------------------------------------------------------+-----------------------------------------+
| User Input                                            | Will result in                          |
+-------------------------------------------------------+-----------------------------------------+
| May 8, 2009 5:57:51 PM                                | 2009-05-08 17:57:51 +0000 UTC           |
| oct 7, 1970                                           | 1970-10-07 00:00:00 +0000 UTC           |
| oct 7, '70                                            | 1970-10-07 00:00:00 +0000 UTC           |
| oct. 7, 1970                                          | 1970-10-07 00:00:00 +0000 UTC           |
| oct. 7, 70                                            | 1970-10-07 00:00:00 +0000 UTC           |
| Mon Jan  2 15:04:05 2006                              | 2006-01-02 15:04:05 +0000 UTC           |
| Mon Jan  2 15:04:05 MST 2006                          | 2006-01-02 15:04:05 +0000 MST           |
| Mon Jan 02 15:04:05 -0700 2006                        | 2006-01-02 15:04:05 -0700 -0700         |
| Monday, 02-Jan-06 15:04:05 MST                        | 2006-01-02 15:04:05 +0000 MST           |
| Mon, 02 Jan 2006 15:04:05 MST                         | 2006-01-02 15:04:05 +0000 MST           |
| Tue, 11 Jul 2017 16:28:13 +0200 (CEST)                | 2017-07-11 16:28:13 +0200 +0200         |
| Mon, 02 Jan 2006 15:04:05 -0700                       | 2006-01-02 15:04:05 -0700 -0700         |
| Mon 30 Sep 2018 09:09:09 PM UTC                       | 2018-09-30 21:09:09 +0000 UTC           |
| Mon Aug 10 15:44:11 UTC+0100 2015                     | 2015-08-10 15:44:11 +0000 UTC           |
| Thu, 4 Jan 2018 17:53:36 +0000                        | 2018-01-04 17:53:36 +0000 UTC           |
| Fri Jul 03 2015 18:04:07 GMT+0100 (GMT Daylight Time) | 2015-07-03 18:04:07 +0100 GMT           |
| Sun, 3 Jan 2021 00:12:23 +0800 (GMT+08:00)            | 2021-01-03 00:12:23 +0800 +0800         |
| September 17, 2012 10:09am                            | 2012-09-17 10:09:00 +0000 UTC           |
| September 17, 2012 at 10:09am PST-08                  | 2012-09-17 10:09:00 -0800 PST           |
| September 17, 2012, 10:10:09                          | 2012-09-17 10:10:09 +0000 UTC           |
| October 7, 1970                                       | 1970-10-07 00:00:00 +0000 UTC           |
| October 7th, 1970                                     | 1970-10-07 00:00:00 +0000 UTC           |
| 12 Feb 2006, 19:17                                    | 2006-02-12 19:17:00 +0000 UTC           |
| 12 Feb 2006 19:17                                     | 2006-02-12 19:17:00 +0000 UTC           |
| 14 May 2019 19:11:40.164                              | 2019-05-14 19:11:40.164 +0000 UTC       |
| 7 oct 70                                              | 1970-10-07 00:00:00 +0000 UTC           |
| 7 oct 1970                                            | 1970-10-07 00:00:00 +0000 UTC           |
| 03 February 2013                                      | 2013-02-03 00:00:00 +0000 UTC           |
| 1 July 2013                                           | 2013-07-01 00:00:00 +0000 UTC           |
| 2013-Feb-03                                           | 2013-02-03 00:00:00 +0000 UTC           |
| 06/Jan/2008:15:04:05 -0700                            | 2008-01-06 15:04:05 -0700 -0700         |
| 06/Jan/2008 15:04:05 -0700                            | 2008-01-06 15:04:05 -0700 -0700         |
| 3/31/2014                                             | 2014-03-31 00:00:00 +0000 UTC           |
| 03/31/2014                                            | 2014-03-31 00:00:00 +0000 UTC           |
| 08/21/71                                              | 1971-08-21 00:00:00 +0000 UTC           |
| 8/1/71                                                | 1971-08-01 00:00:00 +0000 UTC           |
| 4/8/2014 22:05                                        | 2014-04-08 22:05:00 +0000 UTC           |
| 04/08/2014 22:05                                      | 2014-04-08 22:05:00 +0000 UTC           |
| 4/8/14 22:05                                          | 2014-04-08 22:05:00 +0000 UTC           |
| 04/2/2014 03:00:51                                    | 2014-04-02 03:00:51 +0000 UTC           |
| 8/8/1965 12:00:00 AM                                  | 1965-08-08 00:00:00 +0000 UTC           |
| 8/8/1965 01:00:01 PM                                  | 1965-08-08 13:00:01 +0000 UTC           |
| 8/8/1965 01:00 PM                                     | 1965-08-08 13:00:00 +0000 UTC           |
| 8/8/1965 1:00 PM                                      | 1965-08-08 13:00:00 +0000 UTC           |
| 8/8/1965 12:00 AM                                     | 1965-08-08 00:00:00 +0000 UTC           |
| 4/02/2014 03:00:51                                    | 2014-04-02 03:00:51 +0000 UTC           |
| 03/19/2012 10:11:59                                   | 2012-03-19 10:11:59 +0000 UTC           |
| 03/19/2012 10:11:59.3186369                           | 2012-03-19 10:11:59.3186369 +0000 UTC   |
| 2014/3/31                                             | 2014-03-31 00:00:00 +0000 UTC           |
| 2014/03/31                                            | 2014-03-31 00:00:00 +0000 UTC           |
| 2014/4/8 22:05                                        | 2014-04-08 22:05:00 +0000 UTC           |
| 2014/04/08 22:05                                      | 2014-04-08 22:05:00 +0000 UTC           |
| 2014/04/2 03:00:51                                    | 2014-04-02 03:00:51 +0000 UTC           |
| 2014/4/02 03:00:51                                    | 2014-04-02 03:00:51 +0000 UTC           |
| 2012/03/19 10:11:59                                   | 2012-03-19 10:11:59 +0000 UTC           |
| 2012/03/19 10:11:59.3186369                           | 2012-03-19 10:11:59.3186369 +0000 UTC   |
| 2014:3:31                                             | 2014-03-31 00:00:00 +0000 UTC           |
| 2014:03:31                                            | 2014-03-31 00:00:00 +0000 UTC           |
| 2014:4:8 22:05                                        | 2014-04-08 22:05:00 +0000 UTC           |
| 2014:04:08 22:05                                      | 2014-04-08 22:05:00 +0000 UTC           |
| 2014:04:2 03:00:51                                    | 2014-04-02 03:00:51 +0000 UTC           |
| 2014:4:02 03:00:51                                    | 2014-04-02 03:00:51 +0000 UTC           |
| 2012:03:19 10:11:59                                   | 2012-03-19 10:11:59 +0000 UTC           |
| 2012:03:19 10:11:59.3186369                           | 2012-03-19 10:11:59.3186369 +0000 UTC   |
| 2014年04月08日                                        | 2014-04-08 00:00:00 +0000 UTC           |
| 2006-01-02T15:04:05+0000                              | 2006-01-02 15:04:05 +0000 UTC           |
| 2009-08-12T22:15:09-07:00                             | 2009-08-12 22:15:09 -0700 -0700         |
| 2009-08-12T22:15:09                                   | 2009-08-12 22:15:09 +0000 UTC           |
| 2009-08-12T22:15:09.988                               | 2009-08-12 22:15:09.988 +0000 UTC       |
| 2009-08-12T22:15:09Z                                  | 2009-08-12 22:15:09 +0000 UTC           |
| 2017-07-19T03:21:51:897+0100                          | 2017-07-19 03:21:51.897 +0100 +0100     |
| 2019-05-29T08:41-04                                   | 2019-05-29 08:41:00 -0400 -0400         |
| 2014-04-26 17:24:37.3186369                           | 2014-04-26 17:24:37.3186369 +0000 UTC   |
| 2012-08-03 18:31:59.257000000                         | 2012-08-03 18:31:59.257 +0000 UTC       |
| 2014-04-26 17:24:37.123                               | 2014-04-26 17:24:37.123 +0000 UTC       |
| 2013-04-01 22:43                                      | 2013-04-01 22:43:00 +0000 UTC           |
| 2013-04-01 22:43:22                                   | 2013-04-01 22:43:22 +0000 UTC           |
| 2014-12-16 06:20:00 UTC                               | 2014-12-16 06:20:00 +0000 UTC           |
| 2014-12-16 06:20:00 GMT                               | 2014-12-16 06:20:00 +0000 UTC           |
| 2014-04-26 05:24:37 PM                                | 2014-04-26 17:24:37 +0000 UTC           |
| 2014-04-26 13:13:43 +0800                             | 2014-04-26 13:13:43 +0800 +0800         |
| 2014-04-26 13:13:43 +0800 +08                         | 2014-04-26 13:13:43 +0800 +0800         |
| 2014-04-26 13:13:44 +09:00                            | 2014-04-26 13:13:44 +0900 +0900         |
| 2012-08-03 18:31:59.257000000 +0000 UTC               | 2012-08-03 18:31:59.257 +0000 UTC       |
| 2015-09-30 18:48:56.35272715 +0000 UTC                | 2015-09-30 18:48:56.35272715 +0000 UTC  |
| 2015-02-18 00:12:00 +0000 GMT                         | 2015-02-18 00:12:00 +0000 UTC           |
| 2015-02-18 00:12:00 +0000 UTC                         | 2015-02-18 00:12:00 +0000 UTC           |
| 2015-02-08 03:02:00 +0300 MSK m=+0.000000001          | 2015-02-08 03:02:00 +0300 +0300         |
| 2015-02-08 03:02:00.001 +0300 MSK m=+0.000000001      | 2015-02-08 03:02:00.001 +0300 +0300     |
| 2017-07-19 03:21:51+00:00                             | 2017-07-19 03:21:51 +0000 UTC           |
| 2014-04-26                                            | 2014-04-26 00:00:00 +0000 UTC           |
| 2014-04                                               | 2014-04-01 00:00:00 +0000 UTC           |
| 2014                                                  | 2014-01-01 00:00:00 +0000 UTC           |
| 2014-05-11 08:20:13,787                               | 2014-05-11 08:20:13.787 +0000 UTC       |
| 2020-07-20+08:00                                      | 2020-07-20 00:00:00 +0800 +0800         |
| 3.31.2014                                             | 2014-03-31 00:00:00 +0000 UTC           |
| 03.31.2014                                            | 2014-03-31 00:00:00 +0000 UTC           |
| 08.21.71                                              | 1971-08-21 00:00:00 +0000 UTC           |
| 2014.03                                               | 2014-03-01 00:00:00 +0000 UTC           |
| 2014.03.30                                            | 2014-03-30 00:00:00 +0000 UTC           |
| 20140601                                              | 2014-06-01 00:00:00 +0000 UTC           |
| 20140722105203                                        | 2014-07-22 10:52:03 +0000 UTC           |
| 171113 14:14:20                                       | 2017-11-13 14:14:20 +0000 UTC           |
| 1332151919                                            | 2012-03-19 10:11:59 +0000 UTC           |
| 1384216367189                                         | 2013-11-12 00:32:47.189 +0000 UTC       |
| 1384216367111222                                      | 2013-11-12 00:32:47.111222 +0000 UTC    |
| 1384216367111222333                                   | 2013-11-12 00:32:47.111222333 +0000 UTC |
+-------------------------------------------------------+-----------------------------------------+

Testing your policy

The API has a policy test endpoint that allows the Border0 administrator to test a policy. Using this API, the endpoint administrator can see if a user will be allowed access to a Socket and what actions are allowed

Given this example input file: testp.json

{
  "email": "[email protected]",
  "ip_address": "206.214.246.96",
  "time": "2022-10-06T20:00:00Z"
}

We can now test the policy using curl like this (note that you need your API admin token).
The UUID in the curl command below is the UUID of the policy.

$ curl -s -d @testp.json  -H "x-access-token: $(cat ~/.mysocketio_token)"\
  https://api.border0.com/api/v1/policy/48529a18-747c-443c-a589-f4fb60f40aa1/test
{
  "Actions": {
    "database": [
      "*"
    ],
    "http": [
      "*"
    ],
    "ssh": [
      "*"
    ]
  },
  "Info": {
    "allowed": [
      "policy: \"default-connector-policy\", email addres did match policy",
      "policy: \"default-connector-policy\", IP address did match policy",
      "policy: \"default-connector-policy\", Country code did match policy"
    ]
  }
}

Policies

📘
Two types of policies

Policy Components

Action

Condition

Who

🚧
Define at least one property in the Who section

Where

When

Version

Valid date examples

📘
Time and Date format

Testing your policy

📘Two types of policies

Policy Components

Action

Condition

Who

🚧Define at least one property in the Who section

Where

When

Version

Valid date examples

📘Time and Date format

Testing your policy

📘
Two types of policies

🚧
Define at least one property in the Who section

📘
Time and Date format