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

    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 character (*). If no wildcards are present, this parameter value will be interpreted as *value*.

    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 character (*). If no wildcards are present, this parameter value will be interpreted as *value*.

    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

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

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.