Configuring Network and Location-Based Policy Controls

This guide provides administrators with instructions for setting up and configuring Network and Location-Based Policy Controls for HYPR Affirm identity verification workflows.

Beta Feature

Network and Location-Based Policy Controls is currently in Beta status. This feature enables enterprises to make contextual, risk-informed decisions using both IP and location-based rules to address location spoofing, network impersonation, and insider fraud threats.

Overview

Network and Location-Based Policy Controls strengthen HYPR Affirm's identity verification workflows by enabling administrators to enforce security policies based on:

• IP Address: Block or allow specific IP addresses or IP ranges
• Geographic Location: Enforce distance thresholds from expected user locations

Default Behavior:

• With policy controls disabled, requesters can verify location through browser geolocation OR IP location

With Policy Controls Enabled:

• If an IP block list exists and the requester's IP address is on that list, they will fail verification
• If an IP allow list exists and the requester's IP address is on that list, they will pass verification regardless of current location
• If an IP allow list exists and the requester's IP address is NOT on that list and strict enforcement is enabled, they will fail verification
• If a distance threshold is set and the requester's current location from their expected location is outside that threshold (determined through either browser or IP location), they will fail verification

These controls help organizations mitigate security threats while maintaining a seamless user experience for legitimate users and satisfying audit and compliance requirements.

Prerequisites

• HYPR Control Center access with Affirm administration permissions
• HYPR 10.7.0 or later
• Understanding of your organization's network infrastructure and expected user locations
• Feature flag AFFIRM_NETWORK_LOCATION_POLICY_CONTROLS must be enabled

Permissions

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

Feature Flag

This feature requires the AFFIRM_NETWORK_LOCATION_POLICY_CONTROLS feature flag to be enabled. When disabled:

• The UI to configure the policy is not visible
• Related policy control details are not visible in reports
• Activity log will still include cells for location policy-control verification but will be considered "not associated" unless that flow was run when the flag was enabled and the policy was configured

IP-Based Policy Controls

IP-based policy controls allow administrators to create block lists and allow lists for IP addresses, providing granular control over which network sources can access Affirm workflows.

IP Address Rule Formats

Administrators can configure IP address rules using the following supported formats:

IPv4 Formats:

• 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.*.*

IPv6 Formats:

• 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:*

IP Block List

The IP Block List contains IP addresses that should be denied access to Affirm workflows. When a user attempts to access a workflow from a blocked IP address, verification fails immediately.

Configuration:

1. Navigate to the Location verification step in the flow configuration modal in Control Center (click your desired flow in the Verification Flows tab in the HYPR Affirm menu in Control Center, scroll down and hover over Location in the Verification Steps section of the menu panel, and click the pencil icon to begin editing the step)

2. Add IP addresses or IP ranges to the Block List using supported formats — you can also use ranges, i.e. 1.1.1.1-1.1.1.255)
3. Optionally, add a description for your rule
4. Save your rule

Behavior:

• If an IP block list exists and the requester's IP address is on that list, they will fail verification
• Block list checks are performed first in the policy enforcement order

IP Allow List

The IP Allow List contains IP addresses that should always be allowed access, regardless of location-based policy checks. This is useful for trusted network locations such as corporate offices or VPN endpoints.

Configuration:

1. Navigate to the same section in the Verification Flows interface as for the IP Block List.
2. Add IP addresses or IP ranges to the Allow List using supported formats — you can also use ranges, i.e. 1.1.1.1-1.1.1.255)
3. Optionally, add a description for your rule
4. Save your rule

Behavior:

• If an IP allow list exists and the requester's IP address is on that list, they will pass verification regardless of current location
• Allow list checks are performed after block list checks in the policy enforcement order

Strict Enforcement Mode

When the Strict Enforcement option 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.

Behavior:

• If an IP allow list exists and the requester's IP address is NOT on that list and strict enforcement is enabled, they will fail verification
• When enabled, only allow-listed IPs can pass verification, even if they are not on the block list
• This provides the highest level of network-based security control

Location-Based Policy Controls

Location-based policy controls allow administrators to 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.

Configuration:

1. Navigate to the Location verification step
2. Set the Distance Threshold value
   • Values are stored in meters but can be set using your preferred unit of measurement in the UI
   • Maximum allowed value is 20,000,000 meters (maximum distance between any two points on Earth)
   • Must be a positive number
3. Save your configuration

Behavior:

• If a distance threshold is set and the requester's current location from their expected location is outside that threshold (determined through either browser or IP location), they will fail verification
• Distance threshold checks are performed last in the policy enforcement order

Policy Enforcement

Order of Precedence

Policy controls are checked in the following order. If any check returns PASS or FAIL, subsequent checks are not evaluated:

1. IP Block List (checked first)
   • If the IP address matches a block list rule, verification fails immediately
2. IP Allow List (checked second)
   • If the IP address matches an allow list rule, verification passes (unless strict enforcement is enabled and the IP is not on the allow list)
3. Distance Threshold (checked last)
   • If the distance exceeds the configured threshold, verification fails

Workflow Integration

Network and Location-Based Policy Controls are integrated into Affirm identity verification workflows:

1. Policy Check: When a user initiates a verification workflow, the system checks IP-based and location-based policies in order of precedence
2. Enforcement: If a user fails any policy check (IP block, not on allow list with strict enforcement, or outside location threshold), verification fails
3. Bypass: If policies are disabled, verification can proceed using standard Affirm workflow steps

Activity Logging

All policy-triggered events are logged in the Activity Log for audit and compliance purposes:

• Location IP Address Allowed: Shows pass/fail/not configured/not associated status for IP address checks
  • Pass: Allow list exists and IP was either found in 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: Feature flag is enabled and allow list and block list are disabled
  • Not Associated: Feature flag is disabled
• Location Distance Threshold: Shows pass/fail/not configured/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: Feature flag is enabled and distance threshold is disabled
  • Not Associated: Feature flag is disabled

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

Troubleshooting

Verification Failures

If users are experiencing unexpected verification failures:

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

Location Detection Issues

If location-based checks are not working as expected:

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

Related Documentation

• Administering HYPR Affirm
• Affirm Overview
• Activity Log
• Audit Trail