IP Access Control List APIs

Overview

This API has been available since 1.30.0

An IP ACL (Access Control List) is a list of IP ranges that are either Allowed or Blocked. Along with one entry that defines a start IP address of * (wild) that defines the default behavior when an IP address does not match any other range in the list. This means an IP ACL will have a default action of either Allow or Block. The IP address start and end entries for ranges currently only support IPv4.

An IP ACL may be assigned to an API Key, a Tenant or an Application.

When an IP ACL is assigned to an API key, the IP ACL will restrict the usage of the API key based upon the request originating IP address. If a request is made using an API key with an assigned IP ACL and the IP address is found to be blocked, a 401 status code will be returned. The user of this API key will not be able to tell the difference between an invalid API key and an API key that is blocked due to the IP ACL.

When an IP ACL is assigned to a Tenant or Application, it is used to restrict access to the FusionAuth SSO. This means it will be used to restrict access to endpoints that begin with /oauth2/, /account/, /email/, /password/, /registration/ and any other user accessible themed pages. It will not be used to restrict access to the FusionAuth admin UI except when accessed through SSO, or the FusionAuth API.

If two IP ACLs are assigned one to a Tenant and the other to an Application, the Application IP ACL will take precedence.

The IP address used to test against the IP ACL is resolved by using the first value in the X-Forwarded-For HTTP header. If this header is not found, then the IP address reported by the HTTP Servlet request as the remote address will be used. If you are accessing FusionAuth through a proxy it is important that you trust your edge proxy to set the correct value in the X-Forwarded-For HTTP header. Because this header can be set by any HTTP client, it is only secure or trustworthy when managed by a trusted edge proxy. You should not rely upon this feature alone to restrict access to an API key.

The following APIs are provided to manage IP ACLs.

Create an IP ACL
Retrieve an IP ACL
Search for IP ACLs
Update an IP ACL
Delete an IP ACL

Create an IP ACL

This API is used to create a new IP ACL.

Request

Create an IP ACL with a randomly generated Id

URI

POST /api/ip-acl

Create an IP ACL with the provided unique Id

URI

POST /api/ip-acl/{ipAccessControlListId}

Request Parameters

ipAccessControlListId [UUID] Optional defaults to secure random UUID: The Id to use for the new IP ACL. If not specified a secure random UUID will be generated.

Request Body

ipAccessControlList.entries [Array] Required

A list of IP ranges and the action to apply for each. One and only one entry must have a startIPAddress of * to indicate the default action of the IP ACL.

ipAccessControlList.entries[x].action [String] Required

The action to take for this IP Range. The possible values are:

Allow - allow all IPs in the range
Block - block all IPs in the range

ipAccessControlList.entries[x].endIPAddress [String] Required

The ending IP (IPv4) for this range. The only time this is not required is when startIPAddress is equal to *, in which case this field is ignored. This value must be greater than or equal to the startIPAddress. To define a range of a single IP address, set this field equal to the value for startIPAddress.

ipAccessControlList.entries[x].startIPAddress [String] Required

The starting IP (IPv4) for this range.

ipAccessControlList.name [String] Required

The unique name of this IP ACL.

Example IP ACL request JSON


{
  "ipAccessControlList": {
    "name": "Block all except one range",
    "entries": [
      {
        "action": "Block",
        "startIPAddress": "*"
      },
      {
        "action": "Allow",
        "startIPAddress": "71.205.92.217",
        "endIPAddress": "76.104.251.50"
      }
    ]
  }
}

Response

The response for this API contains the IP ACL that was created.

Table 1. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body

ipAccessControlList.entries [Array]: A list of IP ranges and the action to apply for each. One and only one entry will have a startIPAddress of * to indicate the default action of the IP ACL.
ipAccessControlList.entries[x].action [String]: The action to take for this IP Range.
ipAccessControlList.entries[x].endIPAddress [String]: The ending IP (IPv4) for this range.
ipAccessControlList.entries[x].startIPAddress [String]: The starting IP (IPv4) for this range.
ipAccessControlList.name [String]: The unique name of this IP ACL.

Example IP ACL response JSON


{
  "ipAccessControlList": {
    "name": "Block two specific ranges",
    "entries": [
      {
        "action": "Allow",
        "startIPAddress": "*"
      },
      {
        "action": "Block",
        "startIPAddress": "76.104.0.0",
        "endIPAddress": "76.104.255.255"
      },
      {
        "action": "Block",
        "startIPAddress": "71.205.0.0",
        "endIPAddress": "71.205.255.255"
      }
    ],
    "id": "2d9f1c45-725a-4718-b631-b40b7180dbf5",
    "insertInstant": 1628887035851,
    "lastUpdateInstant": 1628887035851
  }
}

Retrieve an IP ACL

This API is used to retrieve a single IP ACL by unique Id.

Request

Retrieve an IP ACL by Id

URI

GET /api/ip-acl/{ipAccessControlListId}

Request Parameters

ipAccessControlListId [UUID] Required: The unique Id of the IP ACL to retrieve.

Response

Table 2. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you requested doesn’t exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body

ipAccessControlList.entries [Array]: A list of IP ranges and the action to apply for each. One and only one entry will have a startIPAddress of * to indicate the default action of the IP ACL.
ipAccessControlList.entries[x].action [String]: The action to take for this IP Range.
ipAccessControlList.entries[x].endIPAddress [String]: The ending IP (IPv4) for this range.
ipAccessControlList.entries[x].startIPAddress [String]: The starting IP (IPv4) for this range.
ipAccessControlList.name [String]: The unique name of this IP ACL.

Example IP ACL response JSON


{
  "ipAccessControlList": {
    "name": "Block two specific ranges",
    "entries": [
      {
        "action": "Allow",
        "startIPAddress": "*"
      },
      {
        "action": "Block",
        "startIPAddress": "76.104.0.0",
        "endIPAddress": "76.104.255.255"
      },
      {
        "action": "Block",
        "startIPAddress": "71.205.0.0",
        "endIPAddress": "71.205.255.255"
      }
    ],
    "id": "2d9f1c45-725a-4718-b631-b40b7180dbf5",
    "insertInstant": 1628887035851,
    "lastUpdateInstant": 1628887035851
  }
}

Search for IP ACLs

Request

Searches the IP ACLs using the given search criteria

URI

GET /api/ip-acl/search?name={name}

When calling the API using a GET request you will send the search criteria on the URL using request parameters. In order to simplify the example URL above, only the IP ACL specific parameter is shown, however you may add any of the documented request parameters to the URL.

Request Parameters

name [String] Optional

The string to match all or part of the IP ACL name. This can contain wildcards using the asterisk or percent characters (* or %).

numberOfResults [Integer] Optional defaults to 25

The number of results to return from the search.

orderBy [String] Optional defaults to name ASC

The database column to order the search results on plus the order direction.

The possible values are:

id - the id of the IP ACL
insertInstant - the instant when the IP ACL was created
lastUpdateInstant - the last instant that the IP ACL was updated
name - the name of the IP ACL

For example, to order the results by the insert instant in descending order, the value would be provided as insertInstant DESC. The final string is optional, can be set to ASC or DESC, or omitted and will default to ASC.

startRow [Integer] Optional defaults to 0

The offset row to return results from. If the search has 200 records in it and this is 50, it starts with row 50.

Searches the IP ACLs using the given search criteria

URI

POST /api/ip-acl/search

When calling the API using a POST request you will send the search criteria in a JSON request body.

Request Body

search.name [String] Optional

The string to match all or part of the IP ACL name. This can contain wildcards using the asterisk or percent characters (* or %).

search.numberOfResults [Integer] Optional defaults to 25

The number of results to return from the search.

search.orderBy [String] Optional defaults to insertInstant DESC

The database column to order the search results on plus the order direction.

The possible values are:

id - the id of the IP ACL
insertInstant - the instant when the IP ACL was created
lastUpdateInstant - the last instant that the IP ACL was updated
name - the name of the IP ACL

For example, to order the results by the insert instant in descending order, the value would be provided as insertInstant DESC. The final string is optional, can be set to ASC or DESC, or omitted and will default to ASC.

search.startRow [Integer] Optional defaults to 0

The offset row to return results from. If the search has 200 records in it and this is 50, it starts with row 50.

Response

The response for this API contains the IP ACLs matching the search criteria in paginated format.

Table 3. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you requested doesn’t exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body

ipAccessControlLists [Array]: The list of all IP ACLs
ipAccessControlLists[x].entries [Array]: A list of IP ranges and the action to apply for each. One and only one entry will have a startIPAddress of * to indicate the default action of the IP ACL.
ipAccessControlLists[x].entries[y].action [String]: The action to take for this IP Range.
ipAccessControlLists[x].entries[y].endIPAddress [String]: The ending IP (IPv4) for this range.
ipAccessControlLists[x].entries[y].startIPAddress [String]: The starting IP (IPv4) for this range.
ipAccessControlLists[x].name [String]: The unique name of this IP ACL.

Example IP ACL response JSON


{
  "ipAccessControlLists": [
    {
      "name": "Block all except one range",
      "entries": [
        {
          "action": "Block",
          "startIPAddress": "*"
        },
        {
          "action": "Allow",
          "startIPAddress": "71.205.92.217",
          "endIPAddress": "76.104.251.50"
        }
      ],
      "id": "fba75c7b-8c27-4cdd-840e-694d808d0aab",
      "insertInstant": 1628887024740,
      "lastUpdateInstant": 1628887024740
    },
    {
      "name": "Block two specific ranges",
      "entries": [
        {
          "action": "Allow",
          "startIPAddress": "*"
        },
        {
          "action": "Block",
          "startIPAddress": "76.104.0.0",
          "endIPAddress": "76.104.255.255"
        },
        {
          "action": "Block",
          "startIPAddress": "71.205.0.0",
          "endIPAddress": "71.205.255.255"
        }
      ],
      "id": "2d9f1c45-725a-4718-b631-b40b7180dbf5",
      "insertInstant": 1628887035851,
      "lastUpdateInstant": 1628887035851
    }
  ]
}

Update an IP ACL

This API is used to update an existing IP ACL.

You must specify the Id of the IP ACL you are updating on the URI.

You must specify all of the properties of the IP ACL when calling this API with the PUT HTTP method. When used with PUT, this API doesn’t merge the existing IP ACL and your new data. It replaces the existing IP ACL with your new data.

Utilize the PATCH HTTP method to send specific changes to merge into an existing IP ACL.

Request

Update the IP ACL with the given Id

URI

PUT /api/ip-acl/{ipAccessControlListId}

PATCH /api/ip-acl/{ipAccessControlListId}

Available since 1.39.0

When using the PATCH method, you can either use the same request body documentation that is provided for the PUT request for backward compatibility. Or you may use either JSON Patch/RFC 6902 or JSON Merge Patch/RFC 7396. See the PATCH documentation for more information.

Available since 1.12.0

When using the PATCH method, use the same request body documentation that is provided for the PUT request. The PATCH method will merge the provided request parameters into the existing object, this means all parameters are optional when using the PATCH method and you only provide the values you want changed. A null value can be used to remove a value. Patching an Array will result in all values from the new list being appended to the existing list, this is a known limitation to the current implementation of PATCH.

Request Parameters

ipAccessControlListId [UUID] Required: The Id of the IP ACL to update.

Request Body

ipAccessControlList.entries [Array] Required

A list of IP ranges and the action to apply for each. One and only one entry must have a startIPAddress of * to indicate the default action of the IP ACL.

ipAccessControlList.entries[x].action [String] Required

The action to take for this IP Range. The possible values are:

Allow - allow all IPs in the range
Block - block all IPs in the range

ipAccessControlList.entries[x].endIPAddress [String] Required

ipAccessControlList.entries[x].startIPAddress [String] Required

The starting IP (IPv4) for this range.

ipAccessControlList.name [String] Required

The unique name of this IP ACL.

Example IP ACL request JSON


{
  "ipAccessControlList": {
    "name": "Block all except one range",
    "entries": [
      {
        "action": "Block",
        "startIPAddress": "*"
      },
      {
        "action": "Allow",
        "startIPAddress": "71.205.92.217",
        "endIPAddress": "76.104.251.50"
      }
    ]
  }
}

Response

The response for this API contains the IP ACL that was updated.

Table 4. Response Codes
Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you are trying to update doesn’t exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body

ipAccessControlList.entries [Array]: A list of IP ranges and the action to apply for each. One and only one entry will have a startIPAddress of * to indicate the default action of the IP ACL.
ipAccessControlList.entries[x].action [String]: The action to take for this IP Range.
ipAccessControlList.entries[x].endIPAddress [String]: The ending IP (IPv4) for this range.
ipAccessControlList.entries[x].startIPAddress [String]: The starting IP (IPv4) for this range.
ipAccessControlList.name [String]: The unique name of this IP ACL.

Example IP ACL response JSON


{
  "ipAccessControlList": {
    "name": "Block two specific ranges",
    "entries": [
      {
        "action": "Allow",
        "startIPAddress": "*"
      },
      {
        "action": "Block",
        "startIPAddress": "76.104.0.0",
        "endIPAddress": "76.104.255.255"
      },
      {
        "action": "Block",
        "startIPAddress": "71.205.0.0",
        "endIPAddress": "71.205.255.255"
      }
    ],
    "id": "2d9f1c45-725a-4718-b631-b40b7180dbf5",
    "insertInstant": 1628887035851,
    "lastUpdateInstant": 1628887035851
  }
}

Delete an IP ACL

This API is used to permanently delete an IP ACL. Deleting an IP ACL will remove it from any tenants and/or applications it was assigned. Delete will fail with a validation error if the IP ACL is still in use.

Request

Delete an IP ACL by Id

URI

DELETE /api/ip-acl/{ipAccessControlListId}

Request Parameters

ipAccessControlListId [UUID] Required: The unique Id of the IP ACL to delete.

Response

This API does not return a JSON response body.

Table 5. Response Codes
Code	Description
200	The request was successful. The response will be empty.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you are trying to delete doesn’t exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

IP Access Control List APIs

Overview

Create an IP ACL

Request

Request Parameters

Request Body

Response

Response Body

Retrieve an IP ACL

Request

Request Parameters

Response

Response Body

Search for IP ACLs

Request

Request Parameters

Request Body

Response

Response Body

Update an IP ACL

Request

Request Parameters

Request Body

Response

Response Body

Delete an IP ACL

Request

Request Parameters

Response

Feedback

How helpful was this page?

See a problem?

Have a question or comment to share?