Overview
What is its Purpose?
- Blocks passage of blacklisted clients through API Proxy by evaluating all incoming clients by source IP address.
- Facilitates centralized blacklist management and provides reusability with corporately defined IP Group records.
- Enables client blocking by country or city using geographical location data.
- Makes blacklist applications fed from external systems possible with variable-based dynamic IP sets.
Working Principle
- Request Arrival: For each HTTP/HTTPS request arriving at the API Gateway, the source IP address of the request is identified.
- Policy Check: If the Blocked IP List policy is active, the system checks in the following order:
- Is a Condition defined? If so, is the condition met?
- Is the policy active (active=true)?
- Is a Variable used or is Apinizer default used?
- Blacklist Evaluation: Request IP is compared with defined IP list, connected IP Groups or selected geographical location entries; if needed, IP set obtained from dynamic variable source is used.
- Decision Making:
- Match Found: Request is rejected, customized error message and determined HTTP code are returned, operation is logged.
- No Match: Request flow is routed to next Policy or target service.
- Error Handling: Customizable HTTP status code and error message are returned for requests that do not comply with the policy rule.
Features and Capabilities
Basic Features
- Blacklist IP Management: Provides ability to add, edit and delete IP addresses in IPv4 / CIDR format; includes validation that prevents typos.
- IP Group Integration: Includes many IP records in blacklist at once by selecting existing IP Groups and provides group-based updates.
- Geographical Location Filters: Manages large-scale blocking scenarios with country and optional city selection, can create records covering all cities.
- Active/Passive Status Control: Easily change the active or passive status of the policy (active/passive toggle). In passive state, the policy is not applied but its configuration is preserved.
- Condition-Based Application: Determine when the policy will be applied by creating complex conditions with Query Builder (e.g., only for specific endpoints or header values).
Advanced Features
- Variable-Based Blacklist: Dynamically applies IP lists fed from external systems by selecting Apinizer Variable.
- Geolocation-Data Blend: Defines multi-layer blocking strategies in combination of selected countries and cities with IP list.
- Policy Usage Visualization: Facilitates impact analysis by tracking API Proxy and Policy Group information where it is used.
- Export/Import Feature: Export policy configuration as a ZIP file. Import to different environments (Development, Test, Production). Version control and backup capability.
- Policy Group and Proxy Group Support: Manage multiple policies within Policy Group. Bulk policy assignment to Proxy Groups. Centralized update and deploy operations.
- Deploy and Versioning: Deploy policy changes to live environment. See which API Proxies use it (Policy Usage). Proxy Group and Policy Group usage reports.
Usage Scenarios
| Scenario | Status | Solution (Policy Application) | Expected Behavior / Result |
|---|---|---|---|
| Off-Office Access Block | Access to internal systems desired only from corporate network | Add external IP blocks to IP list. | Requests from outside corporate IPs return 403 Forbidden. |
| Suspicious Traffic Source | Heavy attacks detected from certain countries | All cities blocked by selecting relevant country in Geolocation. | All requests from selected country are blocked, logged. |
| Temporary Blacklist | IPs performing attacks will be blocked for short period | Add time-limited record to IP list, note in Description. | Relevant IP access is cut; list can be updated after period ends. |
| Partner API Protection | Unauthorized partner attempts exist | Include set excluding only authorized partner IPs from IP Group. | Partner-outside IP attempts are rejected, partner IPs are not affected. |
| Dynamic DLP-Based Blocking | SIEM system shares blacklist with variable | Close useApinizerDefault and select Variable. | IPs in Variable are used before each check. |
| Regional Maintenance Process | Temporary access cut from certain cities | Added to list by selecting country+city with Geolocation. | All requests from selected cities are blocked during maintenance period. |
| Multiple API Security (Optional) | Multiple APIs use same blacklist | Create Policy Group and add this policy. | All APIs benefit from current blacklist simultaneously. |
Configuring Policy Parameters
In this section, you can create a new Blocked IP List policy or configure existing policy parameters to define access rules.Creating a New Blocked IP List Policy
Configuration Steps
| Step | Description / Operation |
|---|---|
| Step 1: Going to Creation Page | - Go to Development → Global Settings → Global Policies → Blocked IP List from the left menu. - Click the [+ Create] button at the top right. |
| Step 2: Entering Basic Information | Policy Status (Policy Status): Shows Active/Passive status. New policies are active by default. Name (Name) Required: Example: Production_IPBlackList- Enter a unique name, does not start with space. - System automatically checks: Green checkmark: available Red X: existing name. Description (Description): Example: “Blocks IPs from global attack sources.” - Max. 1000 characters. - Explain the purpose of the policy. |
| Step 3: Defining Blacklist Sources | - When Use Apinizer Default is open, IP blacklist management is done through policy. - Add IPv4/CIDR entries to IP Address List field; wrong formats are rejected. - Select centralized IP Groups with IP Groups button and add to list. |
| Step 4: Dynamic Variable Configuration (If applicable) | - Use variable-based blacklist by closing default. - Select Apinizer Variable with Select Variable; variable JSON data must return IP list. - Use clear button to remove variable. |
| Step 5: Adding Geographical Restrictions (If applicable) | - If Geolocation is active, select country/city and click Add button. - If country is selected and city is left empty, all cities are blocked. - You can delete added records individually or in bulk from table. |
| Step 6: Defining Condition (Optional) | Examples: - Environment-based: Header = X-Environment, Operator = Equals, Value = production- API Key-based: Header = X-API-Key, Starts With = PROD-- Endpoint-based: Path = /api/admin/*If no condition is defined, the policy is always active |
| Step 7: Error Message Customization (Optional) | - Go to the Error Message Customization tab. - Customize the message to be returned when access is denied. Default: { "statusCode": 403, "message": "[Default error message]" }Custom: { "statusCode": 403, "errorCode": "[CUSTOM_ERROR_CODE]", "message": "[Custom message]" } |
| Step 8: Saving | - Click the [Save] button at the top right. Checklist: Unique name Required fields filled At least one IP or group exists Result: - Policy is added to the list. - Can be connected to APIs. - If global policy, automatically applied. |
Deleting the Policy
For the deletion steps of this policy and the operations to be applied while in use, you can refer to the Removing Policy from Flow section on the Policy Management page.Exporting/Importing the Policy
For the export and import steps of this policy, you can refer to the Export/Import page.Connecting the Policy to API
For the process of how this policy will be connected to APIs, you can refer to the Connecting Policy to API section on the Policy Management page.Advanced Features
| Feature | Description and Usage Steps |
|---|---|
| Dynamic Variable Synchronization | - Select Variable providing IP list from external system. - Track Event Manager notifications to monitor Variable updates. - Verify that policy is deployed in relevant API Proxies after change. |
| Multi-Layer Geolocation Blocking | - Ensure Geolocation settings are active. - Select country and add cities with multi-select if needed. - Regularly review list and clean unnecessary records. |
| Hybrid IP Source Strategy | - Configure both IP list and IP Groups. - Check that policy automatically updates when Group changes. - Define conditions that will trigger only on certain endpoints with Query Builder. |
Best Practices
Things to Do and Best Practices
| Category | Description / Recommendations |
|---|---|
| IP List Maintenance | Bad: Repeating same IP in different formats. Good: Adding clusters collectively with CIDR blocks. Best: Regularly getting reports and removing unnecessary records. |
| IP Group Management | Bad: Adding common IPs individually to each policy. Good: Using shared IP Groups. Best: Mapping IP Group contents with CMDB or IAM processes. |
| Geolocation Usage | Bad: Blocking entire country and leaving critical users outside. Good: Verifying geographical block with periodic reports. Best: Making targeted blocking with city-based records. |
| Variable Management | Bad: Variable format returns invalid JSON. Good: Testing variable at regular intervals. Best: Connecting Variable updates to CI/CD pipeline. |
| Condition Design | Bad: Allowing policy to trigger on every request. Good: Excluding management endpoints. Best: Defining conditions according to environment and user type with Query Builder. |
Security Best Practices
| Security Area | Description / Warnings |
|---|---|
| IP Record Accuracy | Use IP/CIDR validation effectively; faulty records may cause attacker passage. |
| Authorization Control | Give policy editing permissions only to trusted roles; changes must be logged to centralized logs. |
| Variable Security | Audit Variable content against unauthorized changes, restrict source system access. |
| Geolocation Matches | Wrong blocks may occur if Geolocation provider is not current; verify data currency. |
| Log Monitoring | Automatically add repeating IPs to blacklist by routing error message responses to SIEM. |
Things to Avoid
| Category | Description / Warnings |
|---|---|
| Overly Comprehensive Blacklist | Why avoid: Legitimate users are accidentally blocked. Alternative: Use conditional application and geolocation filters. |
| Forgetting Passive Policy | Why avoid: You may leave policy passive and create security vulnerability. Alternative: Verify active status after deploy. |
| Variable Format Errors | Why avoid: Policy does not work at all if JSON structure is corrupted. Alternative: Perform format validation with automation. |
| Unconditional Global Change | Why avoid: May create service interruption for many APIs. Alternative: Validate in test environment first and deploy gradually. |
Performance Tips
| Criterion | Recommendation / Impact |
|---|---|
| IP List Size | Recommendation: Reduce record count with CIDR blocks. Impact: Decision time shortens, memory usage decreases. |
| Variable Read Frequency | Recommendation: Use services that cache Variable value. Impact: Remote call is not made for every request, delay decreases. |
| Geolocation Queries | Recommendation: Clean unnecessary records in country/city additions. Impact: Comparison count decreases, processing time shortens. |
| Policy Group Usage | Recommendation: Manage through Policy Group when using same policy in multiple APIs. Impact: Deploy operations are done in bulk, operational load decreases. |
| Log Level | Recommendation: Focus error logs only on rejected requests. Impact: Log volume is controlled, analysis processes speed up. |
Frequently Asked Questions
| Category | Question | Answer |
|---|---|---|
| General | What does IP Blacklist Policy block? | Provides security by blocking API Proxy access of clients whose source IP is in the list. |
| General | Is Geolocation data mandatory? | No, country/city records should only be added if additional restriction is needed. |
| Technical | What format should Variable be in? | Should contain IP or CIDR string values in JSON array format; e.g., ["10.0.0.0/24","192.168.1.10"]. |
| Technical | What happens if same IP is both in list and group? | Policy evaluates IP once; duplicate records do not change behavior. |
| Usage | How do I apply policy only to certain endpoints? | Select relevant endpoint patterns by defining Path condition in Query Builder. |
| Usage | What does Deploy button on detail page do? | Allows you to transfer policy changes to selected API Proxies to live environment. |