Configure OCI Regional WAF Rate Limiting with a Custom 503 Response Using OCI CLI
Overview
This guide shows how to configure an Oracle Cloud Infrastructure regional Web Application Firewall policy to:
- Monitor requests to
eits-uat.fcicanada.com. - Apply rate limiting only to requests whose path begins with
/apex/. - Limit each client IP address to 100 requests within 60 seconds.
- Return a custom HTTP 503 page for 300 seconds when the threshold is exceeded.
- Preserve all existing WAF actions and rules.
The tested regional WAF policy was:
Policy name: QA_RegionalWAF_Policy
Region: ca-toronto-1
Lifecycle state: ACTIVE
Target host: eits-uat.fcicanada.com
Target path: /apex/
Important: OCI WAF rate limiting is evaluated per client IP address. It does not calculate one combined request total for all application users. Users behind the same NAT gateway, VPN, proxy, or secure web gateway may share one visible public IP address.
Prerequisites
- OCI CLI installed and configured.
- An OCI CLI profile with permission to read and update the WAF policy.
jqinstalled.- The regional WAF policy OCID.
- A Linux shell such as Bash.
Step 1: Create a Working Directory
mkdir -p rate_limiting_waf
cd rate_limiting_waf
Step 2: Set Environment Variables
Set the OCI profile, region, WAF policy OCID, action name, and rule name.
export OCI_PROFILE="CLOUD_ADMIN_FCIAS2"
export OCI_REGION="ca-toronto-1"
export WAF_POLICY_ID="ocid1.webappfirewallpolicy.oc1.ca-toronto-1.REPLACE_WITH_POLICY_OCID"
export ACTION_NAME="EITS-UAT-HIGH-VOLUME-503"
export RULE_NAME="EITS-UAT-APEX-RATE-LIMIT"
Security note: Do not publish a production or internal OCID in a public blog post. Replace it with a placeholder as shown above.
Step 3: Verify the WAF Policy
oci waf web-app-firewall-policy get \
--web-app-firewall-policy-id "$WAF_POLICY_ID" \
--profile "$OCI_PROFILE" \
--region "$OCI_REGION" \
--query 'data.{"Name":"display-name","State":"lifecycle-state","OCID":id}' \
--output table
Example output:
+-----------------------+----------------------------------------------+--------+
| Name | OCID | State |
+-----------------------+----------------------------------------------+--------+
| QA_RegionalWAF_Policy | ocid1.webappfirewallpolicy... | ACTIVE |
+-----------------------+----------------------------------------------+--------+
Confirm that the policy is the correct one and that its lifecycle state is ACTIVE.
Step 4: Back Up the Existing WAF Policy
The OCI CLI update command submits complete policy sections. Back up the policy before changing the actions or request-rate-limiting arrays.
oci waf web-app-firewall-policy get \
--web-app-firewall-policy-id "$WAF_POLICY_ID" \
--profile "$OCI_PROFILE" \
--region "$OCI_REGION" \
> waf-policy-before-rate-limit.json
Extract the existing actions and rate-limiting configuration:
jq '.data.actions' \
waf-policy-before-rate-limit.json \
> actions-before.json
jq '.data."request-rate-limiting"' \
waf-policy-before-rate-limit.json \
> request-rate-limiting-before.json
In this implementation, the original rate-limiting section returned:
null
That confirmed that no request rate-limiting rules were configured before this change.
Step 5: Create the Custom 503 HTML Page
Create the static response page that OCI WAF will return when a client exceeds the configured request threshold.
cat > eits-high-volume.html <<'EOF'
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>EITS Intake – Temporarily Unavailable</title>
<style>
body {
margin: 0;
min-height: 100vh;
display: flex;
align-items: center;
justify-content: center;
background: #f5f6f7;
color: #222;
font-family: Arial, Helvetica, sans-serif;
}
.message {
max-width: 700px;
margin: 20px;
padding: 40px;
text-align: center;
background: #fff;
border-radius: 8px;
box-shadow: 0 3px 15px rgba(0, 0, 0, 0.12);
}
h1 {
margin-top: 0;
font-size: 28px;
}
p {
font-size: 18px;
line-height: 1.6;
}
</style>
</head>
<body>
<main class="message">
<h1>503 Service Temporarily Unavailable</h1>
<p>
EITS Intake is currently experiencing a high volume of requests
and is unable to process your request at this time.
</p>
<p>
Please wait a few minutes and try again. We apologize for the
inconvenience and appreciate your patience.
</p>
</main>
</body>
</html>
EOF
Correction: The tested shell output contained
<h1>503 Service Temporarily Unavailable /h1>. The version above corrects it to a valid closing tag: </h1>.
Step 6: Build the Complete WAF Actions JSON
The following command reads the current action list, removes any older action with the same name, and appends the custom RETURN_HTTP_RESPONSE action.
jq \
--rawfile html eits-high-volume.html \
--arg actionName "$ACTION_NAME" \
'
(.data.actions // [])
| map(select(.name != $actionName))
+ [
{
"name": $actionName,
"type": "RETURN_HTTP_RESPONSE",
"code": 503,
"headers": [
{
"name": "Content-Type",
"value": "text/html; charset=UTF-8"
},
{
"name": "Retry-After",
"value": "300"
},
{
"name": "Cache-Control",
"value": "no-store"
}
],
"body": {
"type": "STATIC_TEXT",
"text": $html
}
}
]
' waf-policy-before-rate-limit.json > actions.json
Review the generated JSON:
jq . actions.json
The new action should include:
{
"name": "EITS-UAT-HIGH-VOLUME-503",
"type": "RETURN_HTTP_RESPONSE",
"code": 503,
"headers": [
{
"name": "Content-Type",
"value": "text/html; charset=UTF-8"
},
{
"name": "Retry-After",
"value": "300"
},
{
"name": "Cache-Control",
"value": "no-store"
}
],
"body": {
"type": "STATIC_TEXT",
"text": "..."
}
}
Step 7: Add the Custom Action to the WAF Policy
oci waf web-app-firewall-policy update \
--web-app-firewall-policy-id "$WAF_POLICY_ID" \
--actions file://actions.json \
--profile "$OCI_PROFILE" \
--region "$OCI_REGION" \
--wait-for-state SUCCEEDED \
--force
Successful output includes:
"operation-type": "UPDATE_WAF_POLICY"
"percent-complete": 100.0
"status": "SUCCEEDED"
Step 8: Verify the Custom Action
oci waf web-app-firewall-policy get \
--web-app-firewall-policy-id "$WAF_POLICY_ID" \
--profile "$OCI_PROFILE" \
--region "$OCI_REGION" \
--query "data.actions[?name=='${ACTION_NAME}']" \
--output json
Confirm that the returned action has:
type:RETURN_HTTP_RESPONSEcode:503Content-Type:text/html; charset=UTF-8Retry-After:300Cache-Control:no-store
Step 9: Retrieve the Policy Again
Retrieve the policy after the action has been added. This refreshed JSON will be used to preserve the current configuration while adding the rate-limiting rule.
oci waf web-app-firewall-policy get \
--web-app-firewall-policy-id "$WAF_POLICY_ID" \
--profile "$OCI_PROFILE" \
--region "$OCI_REGION" \
> waf-policy-with-action.json
Step 10: Build the Rate-Limiting Rule
The rule below applies only when both of these conditions are true:
- The HTTP host is
eits-uat.fcicanada.com. - The request path begins with
/apex/.
It does not match a specific APEX session identifier because values such as 10395221140358 change between sessions.
jq \
--arg ruleName "$RULE_NAME" \
--arg actionName "$ACTION_NAME" \
'
{
"rules":
(
(.data."request-rate-limiting".rules // [])
| map(select(.name != $ruleName))
+ [
{
"name": $ruleName,
"type": "REQUEST_RATE_LIMITING",
"conditionLanguage": "JMESPATH",
"condition": "http.request.host == '\''eits-uat.fcicanada.com'\'' && starts_with(http.request.url.path, '\''/apex/'\'')",
"actionName": $actionName,
"configurations": [
{
"requestsLimit": 100,
"periodInSeconds": 60,
"actionDurationInSeconds": 300
}
]
}
]
)
}
' waf-policy-with-action.json > request-rate-limiting.json
Review the generated rate-limiting configuration:
jq . request-rate-limiting.json
Expected output:
{
"rules": [
{
"name": "EITS-UAT-APEX-RATE-LIMIT",
"type": "REQUEST_RATE_LIMITING",
"conditionLanguage": "JMESPATH",
"condition": "http.request.host == 'eits-uat.fcicanada.com' && starts_with(http.request.url.path, '/apex/')",
"actionName": "EITS-UAT-HIGH-VOLUME-503",
"configurations": [
{
"requestsLimit": 100,
"periodInSeconds": 60,
"actionDurationInSeconds": 300
}
]
}
]
}
Step 11: Apply the Rate-Limiting Rule
oci waf web-app-firewall-policy update \
--web-app-firewall-policy-id "$WAF_POLICY_ID" \
--request-rate-limiting file://request-rate-limiting.json \
--profile "$OCI_PROFILE" \
--region "$OCI_REGION" \
--wait-for-state SUCCEEDED \
--force
Successful output includes:
"operation-type": "UPDATE_WAF_POLICY"
"percent-complete": 100.0
"status": "SUCCEEDED"
Step 12: Verify the Rate-Limiting Rule
oci waf web-app-firewall-policy get \
--web-app-firewall-policy-id "$WAF_POLICY_ID" \
--profile "$OCI_PROFILE" \
--region "$OCI_REGION" \
--query "data.\"request-rate-limiting\".rules[?name=='${RULE_NAME}']" \
--output json
Verified output:
[
{
"action-name": "EITS-UAT-HIGH-VOLUME-503",
"condition": "http.request.host == 'eits-uat.fcicanada.com' && starts_with(http.request.url.path, '/apex/')",
"condition-language": "JMESPATH",
"configurations": [
{
"action-duration-in-seconds": 300,
"period-in-seconds": 60,
"requests-limit": 100
}
],
"name": "EITS-UAT-APEX-RATE-LIMIT",
"type": "REQUEST_RATE_LIMITING"
}
]
Step 13: List All WAF Actions
oci waf web-app-firewall-policy get \
--web-app-firewall-policy-id "$WAF_POLICY_ID" \
--profile "$OCI_PROFILE" \
--region "$OCI_REGION" \
--query 'data.actions[].{Name:name,Type:type}' \
--output table
Verified output:
+-----------------------------------------+----------------------+
| Name | Type |
+-----------------------------------------+----------------------+
| Pre-configured Check Action | CHECK |
| Pre-configured Allow Action | ALLOW |
| Pre-configured 401 Response Code Action | RETURN_HTTP_RESPONSE |
| Unauthorized to access this web site | RETURN_HTTP_RESPONSE |
| maintenance-503 | RETURN_HTTP_RESPONSE |
| EITS-UAT-HIGH-VOLUME-503 | RETURN_HTTP_RESPONSE |
+-----------------------------------------+----------------------+
How the Configuration Works
Client request
|
v
OCI Regional WAF
|
|-- Host is not eits-uat.fcicanada.com
| '-- Rate-limit rule does not apply
|
|-- Path does not begin with /apex/
| '-- Rate-limit rule does not apply
|
'-- Host and path match
|
|-- Up to 100 requests within 60 seconds
| '-- Request continues to the reverse proxy
|
'-- Threshold exceeded for that client IP
'-- Return custom HTTP 503 page for 300 seconds
Configuration Values
| Setting | Value | Meaning |
|---|---|---|
requestsLimit |
100 | Maximum requests allowed from one client IP during the evaluation period. |
periodInSeconds |
60 | The request-counting window. |
actionDurationInSeconds |
300 | How long the custom response action remains active for the client IP after the threshold is exceeded. |
Retry-After |
300 | Advises the client to retry after five minutes. |
Testing
Use a non-production client and a safe URL. Avoid sending repeated requests to an APEX form submission endpoint.
seq 1 150 | xargs -n1 -P20 \
curl -sk -o /dev/null \
-w '%{http_code}\n' \
'https://eits-uat.fcicanada.com/apex/'
Expected behavior:
- Initial requests receive the normal application response.
- After the client IP exceeds the threshold, responses change to HTTP 503.
- The custom HTML message is displayed.
- The client IP remains subject to the action for 300 seconds.
To inspect response headers:
curl -skI https://eits-uat.fcicanada.com/apex/
During rate limiting, the response should include:
HTTP/1.1 503 Service Unavailable
Content-Type: text/html; charset=UTF-8
Retry-After: 300
Cache-Control: no-store
Rollback
Restore the Previous Actions
oci waf web-app-firewall-policy update \
--web-app-firewall-policy-id "$WAF_POLICY_ID" \
--actions file://actions-before.json \
--profile "$OCI_PROFILE" \
--region "$OCI_REGION" \
--wait-for-state SUCCEEDED \
--force
Remove the Rate-Limiting Rule
Because the original rate-limiting configuration was null, use an empty rule list to remove the rule:
cat > request-rate-limiting-empty.json <<'EOF'
{
"rules": []
}
EOF
oci waf web-app-firewall-policy update \
--web-app-firewall-policy-id "$WAF_POLICY_ID" \
--request-rate-limiting file://request-rate-limiting-empty.json \
--profile "$OCI_PROFILE" \
--region "$OCI_REGION" \
--wait-for-state SUCCEEDED \
--force
Rollback warning: Always retrieve and review the current policy immediately before rollback. Another administrator may have added valid actions or rules after the original backup was created.
Operational Considerations
- Shared public IP addresses: Users behind Skyhigh, corporate NAT, VPN, or proxy infrastructure may appear as one client IP. Choose the request threshold using observed production traffic.
- APEX sessions: Do not include the changing APEX session number in the WAF condition.
- HTTP status: HTTP 503 is appropriate because the restriction represents temporary unavailability. HTTP 502 should normally be reserved for an invalid upstream gateway response.
- Policy replacement behavior: The CLI update sends the entire actions or rate-limiting section. Always merge with the existing policy instead of submitting only the new object.
- Monitoring: Review WAF logs after activation to confirm the rule is not affecting legitimate users.
Final Result
The regional WAF policy now protects the EITS UAT APEX endpoint with a per-client-IP request limit. A client that sends more than 100 matching requests within 60 seconds receives a custom HTTP 503 response for 300 seconds. Existing WAF actions remain preserved.
