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
POST /api/ip-acl
Create an IP ACL with the provided unique Id
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.
{
"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.
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.
{
"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
GET /api/ip-acl/{ipAccessControlListId}
Request Parameters
- ipAccessControlListId [UUID] Required
-
The unique Id of the IP ACL to retrieve.
Response
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.
{
"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
- 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 toASC
orDESC
, or omitted and will default toASC
. -
- 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
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 toASC
orDESC
, or omitted and will default toASC
. -
- 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.
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.
{
"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
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 anArray
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.
{
"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.
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.
{
"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 /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.
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.