API security
This topic describes best practices for API security.
Input limiting
Imposing restrictions on the size and number of resources that a user can request through an API can help mitigate denial-of-service (DoS) vulnerabilities. By default, the following built-in API rate limiting is available:
- REST requests containing inputs that represent a list of entities. When enabled, the default maximum is 20 for synchronous requests and 5,000 for asynchronous requests.
- REST and GraphQL queries that allow paginated results can be limited to a maximum number of items per page. When enabled, the default maximum is 300.
- REST queries that allow paginated results can have a default number of items per page imposed. When enabled, the default maximum is 20.
By default, these input limits are disabled, but you can use the following methods to enable them:
- Set the values in the Admin.
- Run the
bin/magento config:set
command. - Add entries to the
env.php
file. - Set environment variables.
When input limiting has been enabled, the system uses the default value for each limitation listed above. You can also configure custom values.
Although some simple examples for configuring these values from the CLI are provided below, all of the values can be configured per website and per store view in addition to being configurable globally. In addition, these values can also be configured via env.php
as well as via environment variables.
In addition, the Admin provides a configuration setting for limiting session sizes for Admin users and storefront visitors.
Enable the input limiting system
To enable these input limiting features from the Admin, go to Stores > Settings > Configuration > Services > Web Api Limits or GraphQL Input Limits and set Enable Input Limits to Yes.
To enable with the CLI, run one or both of the following commands:
1
bin/magento config:set webapi/validation/input_limit_enabled 1
1
bin/magento config:set graphql/validation/input_limit_enabled 1
Maximum parameter inputs
The EntityArrayValidator
class constructor limits the number of objects that can be given to inputs that represent arrays of objects. For example, the PUT /V1/guest-carts/{cartId}/collect-totals
endpoint contains the input parameter additionalData->extension_attributes->gift_messages
, which represents a list of gift message information objects.
There are four possible input arrays:
additional_data
agreement_ids
gift_messages
custom_attributes
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
{
"paymentMethod": {
"po_number": "string",
"method": "string",
"additional_data": [
"string"
],
"extension_attributes": {
"agreement_ids": [
"string"
]
}
},
"shippingCarrierCode": "string",
"shippingMethodCode": "string",
"additionalData": {
"extension_attributes": {
"gift_messages": [
{
"gift_message_id": 0,
"customer_id": 0,
"sender": "string",
"recipient": "string",
"message": "string",
"extension_attributes": {
"entity_id": "string",
"entity_type": "string",
"wrapping_id": 0,
"wrapping_allow_gift_receipt": true,
"wrapping_add_printed_card": true
}
}
]
},
"custom_attributes": [
{
"attribute_code": "string",
"value": "string"
}
]
}
}
By default, any one of these arrays can include up to 20 items, but you can change this value in the configuration UI via Stores > Settings > Configuration > Services > Web API Input Limits > Input List Limit or via CLI using the webapi/validation/complex_array_limit
configuration path.
Input limit for REST endpoints
Some REST endpoints can contain a high number of elements, and developers need a way to set the limit for each endpoint. The limit for a specific REST endpoint can be set in the webapi.xml
configuration file for synchronous requests and webapi_async.xml
for asynchronous requests.
To do this, assign a value for the <data input-array-size-limit/>
attribute within a <route>
definition. The value for input-array-size-limit
must be a non-negative integer.
The following example sets the input limit for the /V1/some-custom-route
route.
If the route works synchronously, open the <module_dir>/etc/webapi.xml
configuration file. Otherwise, open <module_dir>/etc/webapi_async.xml
.
Add the data
tag with the input-array-size-limit
attribute to the route configuration.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
<?xml version="1.0"?>
<!--
Some custom module
-->
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd">
<route url="/V1/some-custom-route" method="POST">
<service class="Vendor\Module\Api\EntityRepositoryInterface" method="save"/>
<resources>
<resource ref="Vendor_Entity::entities" />
</resources>
<data input-array-size-limit="5" /> <!-- limit only for route `/V1/some-custom-route` -->
</route>
</routes>
Clear the configuration cache for the changes to take effect.
1
bin/magento cache:clear config
Values by default for REST endpoints
If you need to change the default limits for REST endpoints, then edit the webapi
section of the <magento_root>/app/etc/env.php
file as follows:
1
2
3
4
5
6
7
8
9
10
11
12
[
//...
'webapi' => [
'sync' => [
'default_input_array_size_limit' => <non-negative value>, //overrides values for synchronous REST endpoints
],
'async' => [
'default_input_array_size_limit' => <non-negative value>, //overrides values for asynchronous REST endpoints
],
]
//...
];
Maximum page size
The maximum page size setting controls the pagination of various web API responses. By default, the maximum value is 300
. You can change the default in the Admin by selecting Stores > Settings > Configuration > Services > Web API Input Limits or GraphQl Input Limits > Maximum Page Size field.
GraphQL security configuration describes how to set the maximum page size in GraphQL.
Default page size
The Default Page Size setting controls the pagination of various web API responses. You can change the default value of 20
in the Admin by selecting Stores > Settings > Configuration > Services > Web API Input Limits > Default Page Size. To change the value from the CLI, run the following command:
1
bin/magento config:set webapi/validation/default_page_size 30