skip to main content
Administering Hybrid Data Pipeline : Implementing IP address whitelists : Configuring IP address whitelists with the API
  

Try Now

Configuring IP address whitelists with the API

You can use the IP Address Whitelist API to view and configure IP address whitelists. 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.
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 specifying a range of IP addresses.
{
"startAddress": "<Starting IP address in IPv4 or IPv6 format>",
"endAddress": "<Ending IP address in IPv4 or IPv6 format>"
}
Apply the following guidelines when specifying IP addresses.
*If you specify only a start address, and do not specify an end address, the specified IP address will be treated as an individual IP address.
*If you are specifying a range of IP addresses, the starting IP address and the ending IP address should be in the same format. However, you can specify different IP address formats for different whitelists. For example, you may use the IPv4 format to whitelist data access APIs, but use the IPv6 format to whitelist Management API.
*If the incoming IP address is in IPv6 format, it will be validated against the IP address range having IPv6 addresses. 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 balancer 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.
The following sections show how to configure IP address whitelists at various levels.
Note: IP address whitelists are enabled by default. Unless you have disabled this feature, any IP address whitelist you create will immediately be enforced. For how to enable or disable IP address whitelists, see Enabling and disabling the IP address whitelist feature.

System level example

In the following example, a GET request retrieves all the IP address 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
}

Tenant level example

In a multitenant environment, IP address whitelists can be set at a tenant level. In the following example, the POST request creates a whitelist for a tenant with the tenant ID of 2.
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
}

User level example

Retrieve users configured with IP address whitelist
The following request returns the users that the administrator making the request can administer. If a system administrator (user with Administrator permission) makes the request, the response lists all the users in the system that have IP address whitelists. If a tenant administrator makes the request, the response lists only the users in tenants for which tenant administrator has administrative access.
Request
GET https://MyServer:8443/api/mgmt/security/whitelist/users
Response Payload
{
"appliedWhiteLists": [
{
"id": 89,
"name": "TestUserA",
"protectedResources": [
"managementAPI",
"dataAccess"
]
},
{
"id": 105,
"name": "TestUserB",
"protectedResources": [
"managementAPI"
]
},
...
]
}
Create IP address whitelist for a user
In the following example, the POST request creates a whitelist for TestUserA by appending the user endpoint with the ?user query parameter and specifying the user's name.
Request
POST https://MyServer:8443/api/mgmt/security/whitelist/user?user=TestUserA
Request Payload
{
"managementAPI": [
{
"startAddress": "10.20.30.2"
}
],
"adminAPI": [
{
"startAddress": "10.20.30.2"
}
],
"dataAccess": [
{
"startAddress": "10.20.30.2"
}
]
}