Identity Management: IP Whitelist API v1

Lets you programmatically maintain a list of whitelist IP addresses to control the set of users who can access Luna.

Learn more:


Overview

The IP whitelist functionality in Luna Control Center serves as a filtering mechanism for incoming Luna user login requests. The IP whitelist API lets you programmatically prevent your company’s Luna users from accessing Luna from IP address you leave off the whitelist. This API is part of the larger Identity and Access Management application in Luna.

Once enabled, the IP whitelist functionality lets users log in only from approved, or whitelisted, IP addresses. All other users trying to access Luna from non-whitelisted IP addresses are blocked. The only requests that are accepted are those coming from CIDR blocks or IP addresses that you have registered and are recognized based on HTTP headers.

The IP whitelist on your company’s Luna account is represented by an array of CIDR blocks, where each CIDR block has a unique identifier and additional descriptive information. The entire array of CIDR blocks is referred to as the IP whitelist, and allows you to perform operations on all of the CIDR blocks at once. Otherwise, you must enable or disable CIDR blocks one at a time.

You can enable or disable IP whitelist at the account level, but you can’t edit it directly. Because there is only one IP whitelist per account in Luna, you do not need to specifically or uniquely identify it when interacting with it through this API.

Who should use this API

You should use this API if you are an administrator on your company’s Luna account and you manage your company’s CIDR lists. You should use this CIDR list to programmatically allow user access to Luna Control Center only from IP addresses you specify.

Getting started

  • Review Get Started on tools that Akamai provides for all its APIs.

  • Review Authorize Your Client to create your API access credentials and authorizations. As detailed in the The API Identity Model section, you then access the API using custom hostnames that looks like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • This API requires admin-level grants to use. Ensure you add them to your client.

  • Review the Authorize Your Client section to make sure the identity under which you provision the API can access its full range of functionality. Use the Identity Management application to expand access if necessary, or the Identity Management API as a programmatic alternative.

Resources

This section specifies the IP whitelist API’s URL resources and parameters, providing details to interact with each operation, and guidance on the workflow through the API.

The following summarizes the main set of resources available to administrators:

  • IP whitelist: The account-level IP address filter that contains the set of IP addresses from which users access Luna Control Center.

  • CIDR block: A range of IP addresses. The API allows either CIDR blocks or individual IP addresses as cidrblockId parameter values. When using a CIDR block as a query parameter in this API, any slash characters included in the CIDR block must be encoded as %2F.

  • State, or account status: The IP whitelist is either enabled or disabled at the account level. The View IP whitelist status operation tells you whether the IP whitelist is active on the account.

While you don’t need to validate each new CIDR block’s formatting, use the Validate CIDR blocks operation to ensure the CIDR blocks you add to your whitelist are properly formatted. If you want to validate your CIDR blocks, run the Validate CIDR blocks with the CIDR block as a query parameter before running Create a CIDR block.

Editing or deleting CIDR blocks is restricted by IP address and user permissions. Additionally, because a whitelist cannot be empty, you may not modify or delete a CIDR block that is the only element in a whitelist.

The IP whitelist on your company’s Luna account is represented by an array of CIDR blocks, where each CIDR block has a unique identifier and additional descriptive information. The entire array of CIDR blocks is referred to as the IP whitelist, and allows you to perform operations on all of the CIDR blocks at once. Otherwise, enabling or disabling a CIDR block must be done one at a time.

The whitelist can be enabled or disabled at the account level, but it is not its own object that you can edit directly. Because there is only one IP whitelist per account in Luna, it does not need to be specifically or uniquely identified when interacting with it through this API.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
List CIDR blocks GET /identity-management/v1/user-admin/ip-acl/whitelist{?actions}
Create a CIDR block POST /identity-management/v1/user-admin/ip-acl/whitelist
View CIDR block details GET /identity-management/v1/user-admin/ip-acl/whitelist/{cidrBlockId}{?actions}
Modify a CIDR block PUT /identity-management/v1/user-admin/ip-acl/whitelist/{cidrBlockId}
Delete a CIDR block DELETE /identity-management/v1/user-admin/ip-acl/whitelist/{cidrBlockId}
Enable IP whitelist filtering POST /identity-management/v1/user-admin/ip-acl/enable
Disable IP whitelist filtering POST /identity-management/v1/user-admin/ip-acl/disable
View IP whitelist status GET /identity-management/v1/user-admin/ip-acl/state
Validate CIDR blocks GET /identity-management/v1/user-admin/ip-acl/validate{?cidrblock}

List CIDR blocks

Retrieve a list of all CIDR blocks on your account’s IP whitelist. The whitelist you retrieve is for the account designated by your API client.

GET /identity-management/v1/user-admin/ip-acl/whitelist{?actions}

Sample: /identity-management/v1/user-admin/ip-acl/whitelist?actions=true

Parameter Type Sample Description
Optional query parameters
actions Boolean true Optionally enable actions to include them as part of the response object.

Status 200 application/json

Response Body:

[
    {
        "cidrBlockId": 921,
        "enabled": true,
        "comments": "West Coast Office",
        "cidrBlock": "127.0.0.1/24",
        "createdDate": "2017-07-27T18:11:25.000Z",
        "createdBy": "johndoe",
        "modifiedDate": "2017-07-27T18:11:25.000Z",
        "modifiedBy": "johndoe",
        "actions": {
            "delete": true,
            "edit": true
        }
    },
    {
        "cidrBlockId": 6042,
        "enabled": true,
        "comments": "East Coast Office",
        "cidrBlock": "128.5.6.6/24",
        "createdDate": "2017-07-27T18:11:25.000Z",
        "createdBy": "johndoe",
        "modifiedDate": "2017-07-27T18:11:25.000Z",
        "modifiedBy": "johndoe",
        "actions": {
            "delete": true,
            "edit": false
        }
    }
]
  1. Optionally enable the actions query parameter to return what actions a user can take against each CIDR block and include it in the response.

  2. Make a GET request to /identity-management/v1/user-admin/ip-acl/whitelist{?actions}.

  3. The response is an array of CidrBlock objects.

Create a CIDR block

Add additional CIDR blocks to your account’s IP whitelist. You can only add one CIDR block at a time.

POST /identity-management/v1/user-admin/ip-acl/whitelist

Content-Type: application/json

Request Body:

{
    "enabled": true,
    "comments": "EMEA Offices",
    "cidrBlock": "128.10.46.60/24"
}

Status 200 application/json

Response Body:

{
    "cidrBlockId": 2567,
    "enabled": true,
    "comments": "APAC Region",
    "cidrBlock": "128.5.6.6/24",
    "createdDate": "2017-07-27T18:11:25.000Z",
    "createdBy": "johndoe",
    "modifiedDate": "2017-07-27T18:11:25.000Z",
    "modifiedBy": "johndoe",
    "actions": {
        "delete": true,
        "edit": false
    }
}
  1. Create a CidrBlock request object.

  2. Make a POST request to /identity-management/v1/user-admin/ip-acl/whitelist.

  3. The response is a CidrBlock object.

View CIDR block details

Retrieve a specific CIDR block.

GET /identity-management/v1/user-admin/ip-acl/whitelist/{cidrBlockId}{?actions}

Sample: /identity-management/v1/user-admin/ip-acl/whitelist/6688?actions=true

Parameter Type Sample Description
URL parameters
cidrBlockId Integer 6688 A Unique identifier for a CIDR block.
Optional query parameters
actions Boolean true Optionally enable actions to include them as part of the response object.

Status 200 application/json

Response Body:

{
    "cidrBlockId": 2567,
    "enabled": true,
    "comments": "APAC Region",
    "cidrBlock": "128.5.6.6/24",
    "createdDate": "2017-07-27T18:11:25.000Z",
    "createdBy": "johndoe",
    "modifiedDate": "2017-07-27T18:11:25.000Z",
    "modifiedBy": "johndoe",
    "actions": {
        "delete": true,
        "edit": false
    }
}
  1. Run the List CIDR blocks operation to retrieve a list of CIDR blocks. Save the cidrBlockId of the CIDR block you want to view.

  2. Optionally enable the actions query parameter to return what actions a user can take against the CIDR block and include it in the response.

  3. Make a GET request to /identity-management/v1/user-admin/ip-acl/whitelist/{cidrBlockId}{?actions}.

  4. The response is a CidrBlock object.

Modify a CIDR block

Enable or disable an existing CIDR block, or perform other edits like updating comments or update the IP address or range in the CIDR block. Note that you can only update a CIDR block if there are multiple CIDR blocks on the whitelist, if IP whitelist is enabled on the account, and you are attempting to make your changes to the CIDR block from an IP address that is on the whitelist. You cannot edit the last CIDR block in the whitelist, or the CIDR block that allows access to the current user.

PUT /identity-management/v1/user-admin/ip-acl/whitelist/{cidrBlockId}

Sample: /identity-management/v1/user-admin/ip-acl/whitelist/6688

Content-Type: application/json

Request Body:

{
    "enabled": true,
    "comments": "EMEA Offices",
    "cidrBlock": "128.10.46.60/24"
}
Parameter Type Sample Description
URL parameters
cidrBlockId Integer 6688 A Unique identifier for a CIDR block.

Status 200 application/json

Response Body:

{
    "cidrBlockId": 2567,
    "enabled": true,
    "comments": "APAC Region",
    "cidrBlock": "128.5.6.6/24",
    "createdDate": "2017-07-27T18:11:25.000Z",
    "createdBy": "johndoe",
    "modifiedDate": "2017-07-27T18:11:25.000Z",
    "modifiedBy": "johndoe",
    "actions": {
        "delete": true,
        "edit": false
    }
}
  1. Run List CIDR blocks operation to and find the relevant CIDR block and cidrBlockID.

  2. Modidy the CIDR block.

  3. Make a PUT request to /identity-management/v1/user-admin/ip-acl/whitelist/{cidrBlockId}.

  4. The response is the modified CidrBlock object.

Delete a CIDR block

Once you delete a CIDR block from the whitelist, any requests from IPs you just deleted fail the next time someone tries to log in from that address. Users accessing Luna Control Center from an IP address you delete are not automatically logged out of Luna at the time you delete the IP address. If IP whitelist filtering is enabled for the account, you cannot delete the last CIDR block in the whitelist or the CIDR block that allows access to the current user. There are no restrictions if IP whitelist filtering is disabled on the account.

DELETE /identity-management/v1/user-admin/ip-acl/whitelist/{cidrBlockId}

Sample: /identity-management/v1/user-admin/ip-acl/whitelist/6688

Parameter Type Sample Description
URL parameters
cidrBlockId Integer 6688 A Unique identifier for a CIDR block.

Status 204

  1. Run the List CIDR blocks operation with the query parameter of actions=true to retrieve a list of deleteable CIDR blocks. Save the cidrBlockId of the CIDR block you want to delete.

  2. Make a DELETE request to /identity-management/v1/user-admin/ip-acl/whitelist/{cidrBlockId}.

Enable IP whitelist filtering

Before you enable IP whitelist filtering on your account, you must add at least one IP address to allow through. Once enabled, the whitelist cannot be empty.

POST /identity-management/v1/user-admin/ip-acl/enable

Status 204

Disable IP whitelist filtering

Once you disable IP whitelist filtering on your account, users are able to access Luna Control Center regardless of their IP address, or who assigns it.

POST /identity-management/v1/user-admin/ip-acl/disable

Status 204

View IP whitelist status

Describes whether IP whitelist filtering is enabled or disabled on your account.

GET /identity-management/v1/user-admin/ip-acl/state

Status 200 application/json

Response Body:

{
    "enabled": true
}

Validate CIDR blocks

Use this operation to validate the format of your CIDR blocks. Pass the CIDR block or an individual IP address through this operation as the query parameter to validate it. Any slash characters included in the CIDR block must be encoded as %2F.

GET /identity-management/v1/user-admin/ip-acl/validate{?cidrblock}

Sample: /identity-management/v1/user-admin/ip-acl/validate?cidrblock=127.0.0.1/20

Parameter Type Sample Description
Required query parameters
cidrblock String 127.0.0.1/20 The CIDR block value you want to validate. This is not the same as a cidrBlockId.

Status 204

Data

This section provides details for each type of data object the API exchanges.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Member is required to be present, regardless of whether its value is empty or null.
Member is optional, and may be omitted in some cases.
Member is out of scope, and irrelevant to the specified interaction context. If you include the member in that context, it’s either ignored, or causes an error.

CidrBlock

This object encapsulates all members for a CIDR block in the IP whitelist data structure.

Download schema: new-ip-acl.json, ip-acl.json

Sample POST request:

{
    "enabled": true,
    "comments": "EMEA Offices",
    "cidrBlock": "128.10.46.60/24"
}

Sample GET response:

{
    "cidrBlockId": 2567,
    "enabled": true,
    "comments": "APAC Region",
    "cidrBlock": "128.5.6.6/24",
    "createdDate": "2017-07-27T18:11:25.000Z",
    "createdBy": "johndoe",
    "modifiedDate": "2017-07-27T18:11:25.000Z",
    "modifiedBy": "johndoe",
    "actions": {
        "delete": true,
        "edit": false
    }
}

CidrBlock members

Member Type POST GET Description
actions CidrBlock.actions Encapsulates the actions you can take against a CIDR block.
cidrBlock String The value of an IP address or IP address range.
cidrBlockId Integer Read-only. A unique identifier for a CIDR block.
comments String Descriptive text you provide for the CIDR block.
createdBy String Read-only. The user who created the CIDR block.
createdDate String Read-only. The ISO 8601 timestamp the CIDR block was created.
enabled Boolean If false, the whitelist ignores the CIDR block as if it isn’t there.
modifiedBy String The user who last modified the CIDR block.
modifiedDate String Read-only. The ISO 8601 timestamp the CIDR block was last modified.
CidrBlock.actions: Encapsulates the actions you can take against a CIDR block.
delete Boolean Whether you can delete this CIDR block. You may not be able to delete a CIDR block if you are trying to delete it from a non-whitelisted IP address, or if the CIDR block is the only one in the IP whitelist.
edit Boolean Whether you can edit this CIDR block. You may not be able to edit a CIDR block if you are trying to modify it from a non-whitelisted IP address, or if the CIDR block is the only one in the IP whitelist.

Errors

This section provides details on the data object that reflects the API’s common response to error cases, and lists the API’s range of response status codes for both error and success cases.

Error responses

This API adheres to the HTTP Problem Details standard.

{
  "type" : "/ip-acl/error-types/1006",
  "httpStatus" : 400,
  "title" : "error creating new record",
  "detail" : "Cidr block already whitelisted",
  "instance" : "",
  "errors" : [ ]
}

HTTP status codes

This section lists the full range of response codes the API may generate.

Code Description
200 The operation was successful.
201 Resource successfully created.
204 Successfully processed request.
400 Bad Request.
401 Authentication failure.
403 Access is forbidden.
404 Resource not found.
500 Internal server error.
502 Platform timeout error.
503 Too many requests. Service is temporarily unavailable.

Last modified: 3/29/2018