# Geofencing

Page contents

About geofencing
- Example use case
How does geofencing work?
How to configure geofencing

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 registrations 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 register 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 SDK will send the country code of the location of the device to the MobileID service. The MobileID service 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 MobileID service maps between the SDK country and its associated continent. The MobileID service contains a default mapping which is defined according to ISO 3166 and the data from GeoNames.org (opens new window).

# Basic flow for geofencing

The MobileID service informs the SDK about the current geofencing mode.
Depending on the geofencing mode, the SDK 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 SDK sends the country from the address to the MobileID service.

Note

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

When the transaction completes, the MobileID service will evaluate if the country reported by the SDK 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 SDK 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 platform’s 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.
Configure the application configuration.

# Configure the mobile SDK

You can use the buttons below to 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

To enable and configure geofencing geofencing, you need to update your application configuration.

You can see what values need to be set in the Geofencing configurations table in the application configuration feature documentation.

About geofencing configurations

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

To find our how to set these properties, see the Make changes to your configuration section on this page.

# 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.

# Make changes to your configuration

To update your application configuration with the necessary properties, you can either:

Use the Signicat Dashboard (opens new window).
Use our MobileID Admin REST API.

# MobileID integration

# Geofencing result object

The result of the geofencing validation is returned in the registration, authentication and signature operation responses as the geofencing object.

Field	Description
`countryCode`	The country code in an ISO 3166-1 Alpha-2 format, as reported by the SDK.
`clientStatus`	The status of the geofencing operation, as reported by the SDK. See Geofencing client status for possible values.
`serverBoundaryValidation`	The status of the geofencing server validation, after evaluating the country against the allowed region. See Geofencing server boundary validation statuses for possible values.

Geofencing client status

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

If the device fails to obtain a location, or if the SDK's reverse geocode request fails, then the clientStatus field will be populated with an appropriate status.

Example: Geofencing result object

"geofencing" : {
    "countryCode" : "NO",
    "clientStatus" : "OK",
    "serverBoundaryValidation" : "SUCCESS"
  }

# 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.

# Get geofencing configuration for a device

To retrieve the geofencing configuration for a given device, you can use the Get geofencing settings endpoint in our MobileID API. As a result, the geofencing configuration object is returned.

# Update geofencing configuration for a device

To update the geofencing configuration for a given device, you can use the Update geofencing settings endpoint in our MobileID API. As a result, the geofencing configuration object is returned.

# Delete geofencing configuration for a device

To delete the geofencing configuration for a given device, you can use the Delete geofencing settings endpoint in our MobileID API.

← Face Authentication Hardware-protected keys →