Setting up network zones

What is a network zone?

A network zone enables LUSID API requests to be allowed or blocked based on originating IP addresses and information about those requests.

Network zones can be used both to implement additional security controls (for example, only allowing access from within the company VPN) and to comply with more complex governance requirements (for example, only allowing LUSID service users from within the corporate datacentre IP range).

Network zones are not a replacement for authentication tokens; they are an optional additional security measure.

Note that all IP address-based security controls are inherently vulnerable to IP address spoofing by malicious parties at the network level. However, since all FINBOURNE services are provided over the TCP internet protocol, a malicious actor would not get a response back to a request from a spoofed IP. As such, the risk of IP spoofing is reduced to one of additional noise at a network level.

How does a network zone work?

A LUSID domain can have between zero and ten network zones. Each zone:

Has a unique hierarchy number (the lowest number is most significant).
Can have a maximum of 100 IP addresses or ranges.

As part of the authentication process, the IP address of every request to LUSID is evaluated against the rule criteria in each network zone until one matches, at which point that network zone is considered authoritative. The authoritative zone defines whether the request is immediately rejected or permitted to proceed for processing.

Note: Network zones are processed in ascending order of hierarchy number. If the same IP is configured in multiple zones, the one with the lowest hierarchy number is authoritative.

What can I use a network zone for?

Fundamentally, a network zone can either allow or block a request from being processed any further by LUSID.

A network zone is authoritative for a given request if that request matches all the rule criteria in that zone. In addition to the IP address/CIDR range of a request, you can match on the following:

Whether the user is a LUSID service user.
Whether the user is a LUSID personal user.
Whether the supplied authentication artefact is a JSON Web Token (JWT).
Whether the supplied authentication artefact is a Personal Access Token (PAT).
Whether the user authenticated via Single Sign-On (SSO).
Whether the user has a one or more roles assigned.

Once a request has matched it can either be blocked or allowed.

Note the following:

Network zone restrictions do not apply to API endpoints related to SSO SCIM identity federation. This is because many identity providers, such as Microsoft Entra ID, have IP addresses that regularly change, thus preventing the use of using network zones.
Network zones only apply to requests that originate from outside the LUSID platform; FINBOURNE Technical Support staff (who operate from specific IPs) are exempt.

Specifying a ‘fallback’ or ‘match all’ network zone

If no rule is authoritative (that is, no criteria in any network zone matches the current request) then access is granted by default. As such, you might want to set up a ‘fallback’ network zone with the highest hierarchy number (the last to be evaluated) that matches all IP addresses if you want to “deny by default”.

To match all IP addresses, specify the IP in the network zone as the CIDR range 0.0.0.0/0.

This ‘match all’ IP can be used in more than one network zone concurrently, and in combination with other criteria can facilitate precise access channels. Examples might be:

Granting access to any users authenticating via SSO and originating from any IP.
Granting access to admins from the IPs of the VPN but block any attempt to use admin roles from other IPs.
Permiting PAT use and service user requests from the company VPN or cloud infrastructure, but block if used from other IPs.

Example use cases

Use case	Suggested implementation
Restrict access to known IPs	If you know that all legitimate users will originate from a specific set or range of IP addresses (such as a corporate VPN), block any traffic that does not originate from those IPs: Create one or more network zones to allow access from known IP addresses. Create a fallback zone with the highest hierarchy number to deny any traffic not originating from known IPs.
Restrict administrative access to trusted IPs	To better protect the use of the `lusid-administrator` role and other powerful administrative roles, specify that these roles can only be used from trusted IPs (such as a corporate VPN): Create a network zone that allows access when the IP address is in the trusted range and the calling user has administrative roles assigned. Create a zone with a higher hierarchy number that blocks users with administrative roles from other IPs
Model your geographic regions using access control	If you have dedicated VPN exit points (or office IPs) for each of your corporate locations around the world, you can model each of their IP ranges as a dedicated network zone. By having a zone for each geographic region you can then refer to the authoritative zone of the request in your access control policies: Create a network zone that allows access for the IP/CIDR ranges associated with each geographic region. Create policies that allow or deny access to data or features if the current request's network zone indicates a specific geography.
Restrict service users and Personal Access Tokens	Service users and Personal Access Tokens (PAT) do not have a second form of authentication, so restricting where they can be used (and thus mitigating potential impact of credential loss) is sensible where possible: Create a network zone that permits access to service users or PAT tokens from trusted IP ranges (for example, corporate VPN and AWS/Azure egress IPs). Create a zone with a higher hierarchy number that blocks access to service users or PAT tokens from other IPs.

How do I create, update or delete a network zone?

Important: There is a risk you might lock yourself or your company out of LUSID while configuring network zones. We recommend you only do this at times of least disruption, and test extensively first. If you do find yourself inadvertently locked out, contact FINBOURNE Technical Support.

Changes should propagate in a few seconds but may take up to an hour in some circumstances.

Creating a network zone

To create a network zone, call the CreateNetworkZone API, for example:

curl -X POST 'https://mydomain.lusid.com/identity/api/networkzones'
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer myAPIAccessToken'
  -d '{
  "code": "UK-Office-Network",
  "description": "Network zone definition allowing access to request from the specified addresses for users in the selected groups AND with specific kinds of session types",
  "networkZoneIPs": [
    {
      "type": "CIDR",
      "description": "UK Office",
      "value": "77.77.77.0/24"
    },
    { 
      "type": "IP", 
      "description": "Corporate VPN endpoint 1", 
      "value": "212.10.12.14" 
    }, 
  ],
  "action": "Allow",
  "applyRules": {
    "sessionType": [
      "AllPATAccess",
      "AllSSOUsers",
    ],
    "userRoles": [
      "portfolio-managers",
      "lusid-administrator"
    ]
  }
}'

Note the following:

You must specify a unique code for the network zone, which cannot subsequently be changed.
The networkZoneIPs.type field can either be CIDR or IP.
The action field can either be Allow or Block.
The applyRules.sessionType array can contain any of the following values: AllUsers, AllServiceUsers, AllPersonalUsers, AllPATAccess, AllJWTAccess, AllAccessTokens, AllSSOUsers, AllNonSSOUsers. Note these values have a logical OR relationship, so only one need apply for a request to match.
The applyRules.userRoles array can contain any number of roles, whether this is a FINBOURNE-provided role such as lusid-administrator or a custom role. Note these values have a logical OR relationship, so only one need apply for a request to match.
The sessionType and userRoles arrays have a logical AND relationship, so the example above can be expressed as:
(AllPATAccess OR AllSSOUsers) AND (portfolio-managers OR lusid-administrator).
The hierarchy is automatically set to the next available number, so for the first network zone this is 0, for the second 1 and so on. Examine the API response to confirm the number. You can subsequently change it by calling the UpdateNetworkZone API (see below).

The following example demonstrates creating a ‘fallback’ network zone that blocks access to all requests that are not already allowed:

curl -X POST 'https://mydomain.lusid.com/identity/api/networkzones'
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer myAPIAccessToken'
  -d '{
  "code": "DefaultZone",
  "description": "Network zone definition blocking any users not already explicitly allowed",
  "networkZoneIPs": [
    {
      "type": "CIDR",
      "description": "All IPs",
      "value": "0.0.0.0/0"
    }
  ],
  "action": "Block",
  "applyRules": {
    "sessionType": [],
    "userRoles": []
  }
}'

Updating a network zone

Note: This is a PUT API, not PATCH. You must recreate the network zone in full each time.

To update any of the characteristics of a network zone (apart from the code), call the UpdateNetworkZone API.

For example, to change the hierarchy number of the ‘fallback’ network zone (defined above) to 9 (the highest number, which means it will be evaluated last):

curl -X POST 'https://mydomain.lusid.com/identity/api/networkzones/DefaultZone'
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer myAPIAccessToken'
  -d '{
  "code": "DefaultZone",
  "description": "Network zone definition blocking any users not already explicitly allowed",
  "networkZoneIPs": [
    {
      "type": "CIDR",
      "description": "All IPs",
      "value": "0.0.0.0/0"
    }
  ],
  "action": "Block",
  "applyRules": {
    "sessionType": [],
    "userRoles": []
  },
  "hierarchy": 9
}'

Where can I audit requests rejected by network zones?

Requests that are rejected as a result of network zone rules can be found in Insights in the same way as any other request. Such a request has the error code 939.