Developer Pages

# Geofencing

Page contents

Documentation scope

To use our geofencing feature, you need to:

  • Configure the mobile SDK.

  • Configure the application configuration.

This documentation describes how the feature works, and how to configure the application configuration.

To find out how to configure the mobile SDK, see our SDK feature documentation:

# About geofencing

Our geofencing feature enables you to strengthen security for transactions by evaluating the current location of a device against a list of allowed regions. By limiting the use of Encap SCA activations (registrations/enrolments) and authentications to certain regions​, you can reduce the chance of fraud.

# Example use case

You want to be notified of transactions that occur in a specific country. This means that if someone tries to activate (register/enrol) or authenticate in this country, then you can either block the transaction or be notified that it is happening.

# How does geofencing work?

When geofencing is enabled, the client will send the country code of the location of the device to the server. The server will verify the location and limit the use of the device based on the configuration in your application configuration and what you have set as your allowed regions.

# What are allowed regions?

Geofencing allowed regions are defined as:

allowed continents + allowed countries - denied countries

# How are countries and continents defined?

Countries are identified in an ISO 3166-1 alpha-2 two-letter country code format.

Geofencing regions can also be defined on continent level. In this instance, the Encap server maps between the client country and its associated continent. The Encap server contains a default mapping which is defined according to ISO 3166 and the data from GeoNames.org (opens new window).

# Basic flow for geofencing

  1. The server informs the client about the current geofencing mode.

  2. Depending on the geofencing mode, the client determines whether to call the external geocoder platform service with location as a parameter.

  3. If the external geocoder platform service was called, then it will return the address from the location.

  4. The client sends the country from the address to the server.

    Note

    The region must be allowed in the application configuration and the end-user must grant location permissions to the app.

  5. When the transaction completes, the server will evaluate if the country reported by the client is within the allowed regions, according to the following rule:

    if (country in <allowed continents> && clientCountry not in <denied countries> || country in <allowed countries>)
{
// Success
}
else
{
// Failure - deny reject transaction (if REQUIRED mode)
}

  6. If the transaction was performed by a mobile client outside of the allowed geofencing boundaries, then the result depends on which mode you have configured geofencing to use:

    • If geofencing is set to the REQUIRED mode, then the transaction will fail.

    • If geofencing is set to the OPTIONAL mode, then the transaction will succeed, but the result of the evaluation is reported to you together with the actual country. It is up to you what action to take on the result.

# Risks

  • For iOS, with a compromised system such as a jailbroken device, it is possible to fake the location that is coming from the location API.

  • For Android, it is possible to install a location provider that can fake your location. This can be done without rooting the device.

To help mitigate these risks, you can shield the app or implement app attestation.

# How to configure geofencing

To use our geofencing feature, you need to:

# Configure the mobile SDK

Learn how to configure the mobile SDK for geofencing.

Configure the Android SDK
Learn how to configure the Android SDK for geofencing
Configure the iOS SDK
Learn how to configure the iOS SDK for geofencing

# Configure the application configuration

Learn how to configure the application configuration for geofencing.

# Geofencing modes

The geofencing feature can be used in multiple modes:

OFF

The OFF mode means that a device location check is not performed.

By default, geofencing is always turned OFF.

OPTIONAL

The OPTIONAL mode means that a device location check is performed. If the location is not a part of the allowed regions, or if the location check fails, then the transaction will still be performed.

It is up to you what action is taken on the result.

REQUIRED

The REQUIRED mode means that a device location check is performed. If the location is not a part of the allowed regions, or if the location check fails, then the transaction will fail.

# Setting the properties

The configuration is split into a set of properties for activation (registration/enrolment) and authentication, so that you can enforce different rules for the different operations.

To enable geofencing, you need to set the following properties in the application configuration:

Property name Description Allowed values Default value
GEOFENCING_ACTIVATION_MODE Determines if or how geofencing is used for activation (registration/enrolment). OFF,
OPTIONAL,
REQUIRED		 OFF
GEOFENCING_ACTIVATION_ALLOWED_CONTINENTS Comma-separated list of continents where activation (registration/enrolment) is allowed, in a two-letter continent code format. AF (Africa),
AN (Antarctica),
AS (Asia),
EU (Europe),
NA (North America),
OC (Oceania),
SA (South America)
GEOFENCING_ACTIVATION_ALLOWED_COUNTRIES Comma-separated list of countries where activation (registration/enrolment) is allowed, in an ISO 3166-1 alpha-2 two-letter country code format

These countries are in addition to those covered by the allowed continents parameter.		 You can find a list of countries and corresponding codes at GeoNames (opens new window).
GEOFENCING_ACTIVATION_DENIED_COUNTRIES Comma-separated list of countries where activation (registration/enrolment) is not allowed, in an ISO 3166-1 alpha-2 two-letter country code format.

These countries will be excluded from those covered by the allowed continents parameter.		 You can find a list of countries and corresponding codes at GeoNames (opens new window).
GEOFENCING_AUTHENTICATION_MODE Determines if or how geofencing is used for authentication. OFF,
OPTIONAL,
REQUIRED		 OFF
GEOFENCING_AUTHENTICATION_ALLOWED_CONTINENTS Comma-separated list of continents where authentication is allowed, in a two-letter continent code format. AF (Africa),
AN (Antarctica),
AS (Asia),
EU (Europe),
NA (North America),
OC (Oceania),
SA (South America)
GEOFENCING_AUTHENTICATION_ALLOWED_COUNTRIES Comma-separated list of countries where authentication is allowed, in an ISO 3166-1 alpha-2 two-letter country code format.

These countries are in addition to those covered by the allowed continents parameter.		 You can find a list of countries and corresponding codes at GeoNames (opens new window).
GEOFENCING_AUTHENTICATION_DENIED_COUNTRIES Comma-separated list of countries where authentication is not allowed, in an ISO 3166-1 alpha-2 two-letter country code format.

These countries will be excluded from those covered by the allowed continents parameter.		 You can find a list of countries and corresponding codes at GeoNames (opens new window).
GEOFENCING_TIMEOUT The maximum time (given in milliseconds) to wait for the location lookup and reverse geocoding to complete on the client.

The timing starts when the client calls the finish operation.

If the timeout is exceeded, then the client will continue without a country.		 From 0 to MAXINT. 10000
# New countries

In the rare instance where a new country is defined, the country-continent mapping can be overridden in the property file <ENCAP_HOME>/core/config/encap-cluster-geofencing.properties.

For example, if a new country in Europe was defined in ISO 3166 with country code XX, then you can configure this in the property file using:

# Mapping of ISO-3166 alpha2 country code to continent code
geofencing.continentForCountry.XX=EU

Important

You must keep this configuration synchronised across all servers in the cluster.

# Encap REST API integration

# Activation and authentication

The result of the geofencing validation is returned in the activation (registration/enrolment) and authentication operation response.

# Geofencing result object
Field Type Description
country_code String The country code in an ISO 3166-1 Alpha-2 format, as reported by the client.
client_status String The status of the geofencing operation, as reported by the client.

See Geofencing client status for possible values.
server_boundary_validation String The status of the geofencing server validation, after evaluating the country against the allowed region.

This can be either SUCCESS or FAILURE.

Example: Geofencing result object

"geofencing" : {
    "country_code" : "NO",
    "client_status" : "OK",
    "server_boundary_validation" : "SUCCESS"
  }
# Geofencing client status

If a country code is obtained successfully, then the geofencing client status (client_status) will be populated with OK.

If the device fails to obtain a location, or if the client's reverse geocode request fails, then the client_status field will be populated with an appropriate status from the table below.

Client status Description
OK The country code was obtained.
LOCATION_NOT_ENABLED Either:
  • The location was not requested by the app.
  • The end-user declined access to location services for the app on their device.
LOCATION_TIMEOUT The device did not obtain a location within the configured accuracy before timeout.
LOCATION_MOCKED Android devices only

The location of the device was mocked.

This is based on the location methods isFromMockProvider() (opens new window) and isMock() (opens new window), which indicate whether this location is marked as a mock location.

Note: To test faking the GPS location of the device, you can download and install a mock location app, then enable it in the Developer options (opens new window) on the device.
GEOCODER_NOT_SUPPORTED Android devices only

Geocoder is not supported on the device.
GEOCODER_NETWORK_ERROR Either:
  • The geocoder network or service is not available.
  • Too many requests have been made to the geocoder service (offered by Apple or Google), as it is rate-limited for each app.
GEOCODER_UNEXPECTED_ERROR An unexpected geocoder error occurred.
GEOCODER_TIMEOUT The geocoder call did not finish within the time limit.
GEOCODER_NO_RESULT_FOUND The reverse geocode request yielded an empty result for the current location.

# Override configuration for a specific device

For authentication operations, you can modify the geofencing configuration for a specific device using our REST APIs. This will override the geofencing configuration in the application configuration.

# Geofencing configuration object
Field Type Description
mode String The geofencing mode.
allowed_continents String Comma-separated list of continents where authentication is allowed for a specific device, in a two-letter continent code format.
allowed_countries String Comma-separated list of countries where authentication is allowed for a specific device, in an ISO 3166-1 alpha-2 two-letter country code format.

These countries are in addition to those covered by the allowed continents parameter.
denied_countries String Comma-separated list of countries where authentication is not allowed for a specific device, in an ISO 3166-1 alpha-2 two-letter country code format.

These countries will be excluded from those covered by the allowed continents parameter.

Example: Geofencing config object

{
  "mode" : "OPTIONAL",
  "allowed_continents" : "EU",
  "allowed_countries" : "US",
  "denied_countries" : "XX"
}
# Get geofencing configuration for a device

You can use this endpoint to retrieve the geofencing configuration for a device. As a result, the geofencing config object is returned.

GET /api/smart-device/v1/devices/{deviceId}/geofencing
# Update geofencing configuration for a device

You can use this endpoint to update the geofencing configuration for a device. As a result, the geofencing config object is returned.

PUT /api/smart-device/v1/devices/{deviceId}/geofencing
# Delete geofencing configuration for a device

You can use this endpoint to delete the geofencing configuration for a device.

DELETE /api/smart-device/v1/devices/{deviceId}/geofencing
Last updated: 11/04/2024 07:47 UTC

← Authenticator App →