IP Access Control Lists

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

This API is used to create a new IP ACL.

Request

Create an IP ACL with a randomly generated Id

POST /api/ip-acl

Create an IP ACL with the provided unique Id

POST /api/ip-acl/{ipAccessControlListId}

Request Parameters

ipAccessControlListIdUUIDDefaults 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.entriesArrayrequired

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].actionStringrequired

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].endIPAddressStringrequired

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].startIPAddressStringrequired

The starting IP (IPv4) for this range.

ipAccessControlList.nameStringrequired

The unique name of this IP ACL.

Response

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

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

ipAccessControlListsArray

The list of all IP ACLs

ipAccessControlList.entriesArray

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].actionString

The action to take for this IP Range.

ipAccessControlList.entries[x].endIPAddressString

The ending IP (IPv4) for this range.

ipAccessControlList.entries[x].startIPAddressString

The starting IP (IPv4) for this range.

ipAccessControlList.nameString

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

GET /api/ip-acl/{ipAccessControlListId}

Request Parameters

ipAccessControlListIdUUIDrequired

The unique Id of the IP ACL to retrieve.

Response

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

ipAccessControlListsArray

The list of all IP ACLs

ipAccessControlList.entriesArray

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].actionString

The action to take for this IP Range.

ipAccessControlList.entries[x].endIPAddressString

The ending IP (IPv4) for this range.

ipAccessControlList.entries[x].startIPAddressString

The starting IP (IPv4) for this range.

ipAccessControlList.nameString

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

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

nameString

The string to match all or part of the IP ACL name. This can contain wildcards using the asterisk character (*). If no wildcards are present, this parameter value will be interpreted as *value*.

numberOfResultsIntegerDefaults to 25

The number of results to return from the search.

orderByStringDefaults 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.

startRowIntegerDefaults 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

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.nameString

The string to match all or part of the IP ACL name. This can contain wildcards using the asterisk character (*). If no wildcards are present, this parameter value will be interpreted as *value*.

search.numberOfResultsIntegerDefaults to 25

The number of results to return from the search.

search.orderByStringDefaults 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

search.startRowIntegerDefaults 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.

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[x].entriesArray

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].actionString

The action to take for this IP Range.

ipAccessControlLists[x].entries[y].endIPAddressString

The ending IP (IPv4) for this range.

ipAccessControlLists[x].entries[y].startIPAddressString

The starting IP (IPv4) for this range.

ipAccessControlLists[x].nameString

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 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

PUT /api/ip-acl/{ipAccessControlListId}

PATCH /api/ip-acl/{ipAccessControlListId}

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.

When using the PATCH method with a Content-Type of application/json the provided request parameters will be merged 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

ipAccessControlListIdUUIDrequired

The Id of the IP ACL to update.

Request Body

ipAccessControlList.entriesArrayrequired

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].actionStringrequired

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].endIPAddressStringrequired

ipAccessControlList.entries[x].startIPAddressStringrequired

The starting IP (IPv4) for this range.

ipAccessControlList.nameStringrequired

The unique name of this IP ACL.

Response

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

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

ipAccessControlListsArray

The list of all IP ACLs

ipAccessControlList.entriesArray

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].actionString

The action to take for this IP Range.

ipAccessControlList.entries[x].endIPAddressString

The ending IP (IPv4) for this range.

ipAccessControlList.entries[x].startIPAddressString

The starting IP (IPv4) for this range.

ipAccessControlList.nameString

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

DELETE /api/ip-acl/{ipAccessControlListId}

Request Parameters

ipAccessControlListIdUUIDrequired

The unique Id of the IP ACL to delete.

Response

This API does not return a JSON response body.

Response Codes

Code	Description
200	The request was successful.
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.

Results

Recent

IP Access Control Lists

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

Results

Recent