Geofencing
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.
Basic flow for geofencing
- The server informs the client about the current geofencing mode.
- Depending on the geofencing mode, the client determines whether to call the external geocoder platform service with location as a parameter.
- If the external geocoder platform service was called, then it will return the address from the location.
- 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.
- 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)
} - 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
REQUIREDmode, then the transaction will fail. - If geofencing is set to the
OPTIONALmode, 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.
- If geofencing is set to the
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.
API integration
Geofencing result object
The geofencing result is provided in the REST response as the geofencing object.
To learn more about this, you can refer to the Encap API reference documentation.
The geofencing object is:
- A session object for activation (registration/enrolment).
- A session object for authentication.
Response fields
Example: Geofencing result
"geofencing" : {
"country_code" : "NO",
"client_status" : "OK",
"server_boundary_validation" : "SUCCESS"
}
Geofencing client statuses
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.
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
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
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 application configuration
Learn how to configure the application configuration for geofencing.
Geofencing modes
The geofencing feature can be used in multiple modes:
The OFF mode means that a device location check is not performed.
By default, geofencing is always turned OFF.
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.
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:
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
You must keep this configuration synchronised across all servers in the cluster.