Configuring Network and Location-Based Policy Controls

This guide describes how to set up and configure Network and Location-Based Policy Controls for HYPR Affirm verification flows.

Beta Feature

Network and Location-Based Policy Controls is in Beta. The feature lets enterprises make contextual, risk-informed decisions with IP and location-based rules to address location spoofing, network impersonation and insider fraud threats.

Overview

Network and Location-Based Policy Controls let administrators enforce security policies in HYPR Affirm verification flows based on the following:

• IP Address: Block or allow specific IP addresses or IP ranges
• Geographic Location: Enforce distance thresholds from expected user locations
• Country: Block requesters from specific countries or sanctioned regions using managed country block lists

With policy controls disabled, requesters can verify their location through browser geolocation or IP location.

With policy controls enabled, a requester fails verification in the following cases:

• An IP block list exists and the requester's IP address is on that list
• An IP allow list exists, strict enforcement is enabled and the requester's IP address is not on the list
• A distance threshold is set and the requester's current location is outside that threshold from their expected location, as determined through either browser or IP location
• A country block list is assigned and the requester's country, determined from the browser location or the IP address, is on that list

The Location step passes only when none of these checks fails and Affirm can determine a location and a distance.

Prerequisites

Before you begin, make sure you have the following:

• HYPR Control Center access with Affirm administration permissions
• HYPR 10.7.0 or later
• An understanding of your organization's network infrastructure and expected user locations
• Network and location policy controls enabled on the tenant by HYPR. See the Feature Flags Reference for the canonical flag identifier

Permissions

Only Control Center administrators can configure network and location-based policy controls.

Feature Flag

This feature requires tenant-level enablement (see the Feature Flags Reference). When the feature is disabled:

• The UI to configure the policy is not visible
• Related policy control details are not visible in reports
• The Location Settings tab under Advanced Settings is not shown
• The Activity Log still includes cells for location policy-control verification, shown as Not Configured

IP-Based Policy Controls

IP-based policy controls let administrators create block lists and allow lists of IP addresses, to control which network sources can access Affirm workflows.

IP Address Rule Formats

The following table lists the supported formats for IP address rules.

Format	Example
Single IPv4 address	203.94.178.56
IPv4 range with dash	203.94.1.40-203.94.50.255
IPv4 range with CIDR	203.94.128.0/20
IPv4 wildcards	203.94.*.*
Single IPv6 address	2001:0db8:85a3:0000:0000:8a2e:0370:7334
IPv6 range	2001:db8::ff00:41:0-2001:db8::ff00:41:12ff
IPv6 range with CIDR	2001:db8::/46
IPv6 wildcards	2001:db8::ff00:41:*

In the step card, click Show supported IP address rule formats to see these formats. A rule cannot appear on both lists, and a list cannot repeat a rule.

IP Block List

The IP Block List contains IP addresses to deny access to Affirm workflows. When a requester's IP address matches a block list rule, the IP check fails and so does the Location step. Affirm still runs the other configured checks and records their results.

To configure the block list:

1. In the Verification Flows tab, click the row of the verification flow you want to configure.

2. In the left sidebar, click Verification Steps.

3. Expand the Location step.

   

4. Add IP addresses or IP ranges to the block list in a supported format, for example the range 1.1.1.1-1.1.1.255.

5. Optional: Add a description for your rule, using letters, numbers, underscores and spaces.

6. Click Add.

7. Click Save to save the flow.

The IP block list is checked after the Country Block List. See Order of Precedence.

IP Allow List

The IP Allow List contains trusted IP addresses, such as corporate offices or VPN endpoints. With Strict Enforcement turned on, a requester whose IP address matches no allow list rule fails verification. See Order of Precedence.

To configure the allow list:

1. Open the Location step of the flow, as described for the IP Block List.
2. Add IP addresses or IP ranges to the allow list in a supported format, for example the range 1.1.1.1-1.1.1.255.
3. Optional: Add a description for your rule, using letters, numbers, underscores and spaces.
4. Click Add.
5. Click Save to save the flow.

The allow list behaves as follows:

• When the allow list is enabled, the IP addresses saved on the known locations selected for the step are added to it
• Affirm checks the allow list after the block list in the policy enforcement order
• Without Strict Enforcement, this check does not fail an address that matches no allow-list rule

Strict Enforcement Mode

When Strict Enforcement is enabled, only IP addresses on the allow list can pass verification. All other IP addresses are denied, even if they are not on the block list.

Location-Based Policy Controls

Location-based policy controls let administrators enforce geographic restrictions by setting a maximum allowed distance from an expected user location.

Distance Threshold

The Distance Threshold defines the maximum allowed distance from an expected location. If a user's current location exceeds this threshold, verification fails.

To set the distance threshold:

1. Open the Location verification step.
2. Select Distance Threshold.
3. Enter the value.
   • Values are stored in meters, but you can enter them in the UI in your preferred unit: miles, kilometers or meters
   • The maximum allowed value is 20,000,000 meters (the maximum distance between any two points on Earth)
   • The value can't be negative. With a value of 0, Affirm measures no distance and records the distance check as passed.
4. Save your configuration.

The distance check behaves as follows:

• The expected location is the nearest of the address on file and the known locations selected for the step; a known location can carry its own threshold
• Affirm uses the browser location when it has one and the IP location otherwise, and measures the route distance where a route exists and the straight-line distance otherwise
• If no distance can be calculated, the check fails
• Affirm checks the distance threshold after the IP-based checks in the policy enforcement order

Blocked Countries

Beta Feature

The Blocked Countries feature is in Beta.

The Blocked Countries feature lets administrators define lists of countries. Requesters in a listed country are blocked from passing the Location verification step. Use it for country-level access control on sensitive workflows, for example to enforce trade sanction compliance or to restrict verification to approved regions.

You manage country block lists centrally in Advanced Settings > Location Settings, then assign each list to one or more verification flows. The Location Settings tab appears when network and location policy controls are enabled for your tenant.

Creating a Country Block List

1. In the HYPR Affirm menu, navigate to Advanced Settings and select the Location Settings tab.

2. In the Blocked Countries section, click + Countries List.

3. In the Add List dialog, enter a name for the list and select a list type:

   • Sanctioned Countries: Creates the list with Cuba, Iran, North Korea, Russia and Syria pre-selected. Review the selection against your own compliance requirements.

     

   • Custom List: Opens a full country and region selector. Choose individual countries with the checkboxes, or use Select All or Clear to adjust the selection in bulk.

     

4. Click Add List to save. A confirmation toast appears when the list is created successfully.

   

To edit or delete an existing list, use the edit (pencil) or delete (trash) icons on the list card.

Assigning a Country Block List to a Verification Flow

After you create a country block list, you can assign it to the Location step of any verification flow.

1. In the Verification Flows tab, click the row of the verification flow you want to configure.

2. In the left sidebar, click Verification Steps.

3. Expand the Location step.

4. From the Country Block List drop-down, choose the list to apply.

   

5. Click Save. A confirmation toast appears when the flow is updated successfully.

   

To remove a country block list from a flow, set the drop-down back to - (No Country Block List) - and save.

End-User and Approver Experience

Requester (blocked user): When a requester attempts verification from a blocked country, the Location step fails. With the step's default failure outcome, Continue Workflow, they see a "Verification Unsuccessful" screen and are advanced to the next step in the flow once the retry limit is reached. With Deny Verification or Redirect to URL, the flow ends or redirects instead. Affirm determines the country from both the browser location and the IP address. If either one is on the list, the check fails.

Approver: The verification results panel shows the Location step details. When a country block list is in effect and the requester's country is on it, the Country allowed field displays No alongside the overall step Status: Failed.

Multi-Headquarters Location Policy

Organizations with multiple physical locations, such as several headquarters or offices, can save each one as a known location. A requester passes the distance check if they are within the distance threshold of the nearest expected location: their address on file or any known location selected for the step.

Configuring Known Locations

1. In the HYPR Affirm menu, navigate to Advanced Settings and select the Location Settings tab.
2. In the Known Locations section, click + Known Location.
3. In the Add Location dialog, enter the location details. Each known location carries:
   • Name: a display name of up to 255 characters
   • Address: Country / Region, Street Address, Address Line 2, City, State (or State / Province / Region outside the United States) and Zip / Postal Code, used for distance calculation
   • IP Address: an optional IP address for this location; when the step's IP Address Allow List is enabled, it is added to that list
   • Distance Threshold: select Use global distance threshold to use the step's threshold, or clear it and enter a threshold for this location
4. Click Add Location.
5. In each verification flow that should use the location, open the Location step.
6. Under Known Locations, move the location to Selected.
7. Click Save.

If no per-location threshold is set, the step's threshold applies to all selected known locations.

How Location Validation Evaluates Against Multiple Locations

When a workflow with the Location step runs, Affirm measures the distance from the requester to the address on file and to each selected known location. The distance check compares the nearest of these with its threshold. It returns PASS if the requester is within the threshold of that location and FAIL otherwise.

When the step's IP Address Allow List is enabled, a known location's IP address works as an allow-list rule. With Strict Enforcement, a requester whose IP address matches no rule, including the known locations' addresses, fails the step. The distance check still applies to requesters whose IP address matches.

Logging

Each location decision records the per-location evaluation in the Activity Log:

• Distance per location evaluated: the calculated distance to the address on file and to each selected known location, from the browser location and from the IP location, useful for tuning thresholds and diagnosing borderline failures
• IP rule outcome: whether the IP allow and block lists matched, and which rule
• Final decision: the combined Location step outcome after all rules evaluate

Policy Enforcement

This section describes how Affirm evaluates the policy controls during a verification flow and logs the results.

Order of Precedence

The Location step passes only when every configured check passes. Affirm records the first failure it finds, in the following order:

1. Country Block List (if assigned)
   • If the requester's country, determined from the browser location or the IP address, is on the assigned list, verification fails
2. IP Block List
   • If the IP address matches a block list rule, verification fails
3. IP Allow List with Strict Enforcement
   • If strict enforcement is enabled and the IP address matches no allow list rule, verification fails
4. Distance Threshold
   • If the distance to the nearest expected location is not less than the configured threshold, or no distance can be calculated, verification fails
5. Location data
   • If Affirm cannot determine an address and a distance from either the browser location or the IP address, verification fails

Workflow Integration

Network and Location-Based Policy Controls work within Affirm verification flows as follows:

1. Policy Check: When a requester reaches the Location step, Affirm checks IP-based and location-based policies in order of precedence
2. Enforcement: If a user fails any policy check (country block, IP block, not on allow list with strict enforcement or outside location threshold), the Location step fails and the step's retry limit and failure outcome apply. When your tenant uses the Affirm Risk Policy Builder, the assigned Policy Evaluation Kit sets the retries and failure action instead
3. Bypass: If policies are disabled, verification can proceed using standard Affirm workflow steps

Activity Logging

Affirm records the result of each policy check in the Activity Log:

• Location IP Address Allowed: Shows the Pass, Fail, Not Configured or Not Associated status for IP address checks
  • Pass: A block or allow list is enabled and the IP address matched no block list rule, and either matched the allow list or strict enforcement is disabled
  • Fail: IP address either matched a rule in the block list or was not in an allow list with strict enforcement enabled
  • Not Configured: The allow list and block list are disabled, or network and location policy controls are not enabled for the tenant
  • Not Associated: Shown on older records only

• Location Distance Threshold: Shows the Pass, Fail, Not Configured or Not Associated status for location-based distance checks
  • Pass: Threshold exists and calculated distance is within threshold
  • Fail: Threshold exists and calculated distance is not within threshold
  • Not Configured: The distance threshold is disabled, or network and location policy controls are not enabled for the tenant
  • Not Associated: Shown on older records only
• Location Country Allowed: Shows the Pass, Fail or Not Configured status for country block list checks
  • Pass: A country block list is assigned and the requester's detected country is not on it
  • Fail: A country block list is assigned and the requester's detected country is on it
  • Not Configured: No country block list is assigned to the flow
• Location Acquired: Shows whether Affirm obtained a usable location, separately for the browser location and the IP location

Administrators can review these logs to monitor policy effectiveness and investigate security events.

Troubleshooting

Verification Failures

If users fail verification unexpectedly, check the following:

• Check Activity Log: Review the Activity Log to see which policy check failed
• Verify IP Lists: Confirm that user IP addresses are correctly configured in the block and allow lists
• Review Location Data: Make sure user directory data contains accurate location information
• Test Policies: Temporarily disable policies to confirm whether they cause the issue

Location Detection Issues

If location-based checks do not work as expected, check the following:

• Browser Permissions: Make sure users have granted browser geolocation permissions
• Directory Data: Confirm that the user directory contains complete and accurate location information

Related Documentation

• Advanced Setup
• Affirm Overview
• Activity Log
• Audit Trail