skip to main content
Administering Hybrid Data Pipeline : Implementing IP address whitelists : Using the IP Address Whitelist API
  

Try Now

Using the IP Address Whitelist API

When setting up IP address whitelists, you must identify the IP addresses that you need to whitelist. You can specify a single address, a list of addresses or a range of addresses. You can use the IP Address Whitelist API to set, view, modify and delete whitelists. For details on all the API operations supported, see IP Address Whitelist API.
The IP addresses can be specified in either IPv4 or IPv6 format, or a combination of the two. The IP addresses can also be specified in the IPv4-mapped IPv6 combination address format. The following is the payload format for whitelisting a range of IP addresses:
{
"startAddress": "<Starting IP address in IPv4 or IPv6 format>",
"endAddress": "<Ending IP address in IPv4 or IPv6 format>"
}
If you specify only a start address, and do not specify an end address, the mentioned IP address will be treated as an individual IP address, and will be whitelisted.
If you are specifying a range of IP addresses, the starting IP address and the ending IP address should be in the same format. You can specify different IP address formats for different whitelists. For example, you may specify a whitelist for data access APIs in IPv4 format, and specify a Management API whitelist in IPv6 format.
If the incoming IP address is in IPv6 format, it will be validated against the IP address range having IPv6 addresses only. This same limitations holds true for IPv4 addresses. The system will not convert IP addresses from one format to another to check for whitelisting.
In a load balanced deployment, the load balancer should be configured to echo back the originating client's IP address in the X-Forwarded-For header to have this feature function appropriately.
In the following section, examples of IP whitelisting at the system level, tenant level and user level are shown.

System level example

In the following example, a GET request retrieves all the whitelists applied at the system level.
Request
GET https://MyServer:8443/api/admin/security/whitelist/system
Response
{
"managementAPI": [],
"adminAPI": [],
"dataAccess": [],
"webUI": []
}
The response indicates that none of the resources are protected at a system level. The following POST request creates whitelists for all resources except the Web UI. By providing null as the value for the "webUI" property, a whitelist is not applied to the Web UI.
Request
POST https://MyServer:8443/api/admin/security/whitelist/system
Request Payload
{
"managementAPI": [
{
"startAddress": "10.20.30.0",
"endAddress": "10.20.30.10"
}
],
"adminAPI": [
{
"startAddress": "10.20.30.0",
"endAddress": "10.20.40.20"
}
],
"dataAccess": [
{
"startAddress": "10.20.30.0",
"endAddress": "10.20.50.20"
}
],
"webUI": null
}
If the above request is successful, the specified IP addresses are whitelisted for the specified resources. So, a user with an IP of 10.20.30.5 can access the Management API.

Tenant level example

In a multitenant environment, whitelists can be set at a tenant level. In the following example, the POST request creates a whitelist for a specific tenant.
Request
POST https://MyServer:8443/api/admin/security/whitelist/tenants/2
Request Payload
{
"managementAPI": [
{
"startAddress": "10.20.30.0",
"endAddress": "10.20.30.5"
}
],
"adminAPI": [
{
"startAddress": "10.20.30.0",
"endAddress": "10.20.40.5"

}
],
"dataAccess": [
{
"startAddress": "10.20.30.0",
"endAddress": "10.20.50.5"
}
],
"webUI": null
}
If the above request is successful, the specified IP addresses are whitelisted for the specified resources under the tenant. In this example, the tenant has a tenant ID of 2. So, a user with an IP of 10.20.30.5 can access the management API.

User level example

In the following example, the POST request creates a whitelist for a specific user. In cases where end users create their own data sources, administrators can allow end users to configure their own data access and Management API whitelists.
Request
POST https://MyServer:8443/api/mgmt/security/whitelist/user/1
Request Payload
{
"managementAPI": [
{
"startAddress": "10.20.30.2"
}
],
"adminAPI": [
{
"startAddress": "10.20.30.2"
}
],
"dataAccess": [
{
"startAddress": "10.20.30.2"
}
]
}
If the above request is successful, the specified IP address is whitelisted for the specified user owned resources. So, a user with an IP address of 10.20.30.2 only can access the Management API.