Location aware authentication sessions

This document describes the feature to capture mobile device's location during authentication sessions, report this to the VeridiumID server and further down to Shibboleth.

General Description

During authentication sessions mobile devices will capture user location, reverse geocode it to habitation information (country, city, street, etc) and send this information in AuthenticationResponse call.

The VeridiumID server will save this information on sessions and on successful authentications the Identity Token will contain this information.

Shibboleth (SAML authentications) will read this information from the Veridium Identity Token and add it to the SAML message.

Mobile side

Upon Authentication session final response (AuthenticationResponse / package SDK response for proxy authentication) the mobile device should capture user location through OS frameworks and apply reverse geocode it to habitable location. Usually this process is done through network calls to Apple/Google servers and have device quotas attached (e.g. the quota for Apple is one call per minute) so it should not be abused (throttle calls, cache them if needed). The information gathered is then sent to the server together with the signed authentication response (the server APIs will be updated - see Server section).

Due to GDPR regulations different clients may restrict what information is reported to servers related to location. This configuration should be read from server's Mobile Settings. This setting should be coded as a precision level for location reporting. Possible values are NONE, COUNTRY, DISTRICT, CITY, STREET, STREET_NUMBER, GPS_LOCATION.
If this setting is missing it should be considered by default to NONE.

The precision of the GPS location can be configured in Settings → Geolocation → Location Coordinates Precision

In order to increase location precision one approach would be to start location monitoring (on a background worker) when the device attaches to the authentication session. By the time the biometric authentication is completed by the user, the OS would have had time to increase the accuracy of the location through internal mechanisms (Wifi connections, 4G trianguralizations, GPS signal).

Server side

The server will update the AuthenticationResponse and VerifyAuthentication APIs by adding specific location fields (the Content-Type version will remain the same for backwards compatibility purposes)

CODE

"location": { 
	"coordinates": {
		"latitude": 2.333, 
		"longitude":44.32 
    },
	"accuracy": 42.0,
	"countryCode": "RO",
	"district": "Bucharest",
	"city": "Bucharest",
	"street": "Buzesti",
	"streetNumber": "71",
	"errorCode": 0
}

'errorCode' can have the following values:

0 - location was captured successfully
1053 - Failed to geocode the location
1054 - Location services is unavailable
1055 - Location permission denied for app
1056 - Timeout getting location

This information will be saved on the session as is and will be consumed by other modules for Risk analysis, forwarding to external services, etc. The SessionStatusResponse will contain along with IdentityToken location information relevant for that s found on session and embed it.

In order to make server behaviour configurable a new configuration file location.json will be added in Zookeeper, containing the following:

CODE

{
  "accuracyThreshold": 50,
  "countryCodeReplacement": "XB",
  "locationAttributeFilter": [
    "countryCode",
    "accuracy"
  ]
}

accuracyThreshold - a limit for accuracy received from mobile.

If accuracy received from mobile in higher the country code will be passed, as is form mobile, after being saved in data layer
If accuracy received from mobile in lower than the threshold the country code will not be passed further, but will be set to XB (cross border, or some other relevant label)

countryCodeReplacement - a label to be set on location fields when accuracy not high enough

locationAttributes - an array containing the allowed fields for the location object returned from mobile. Can contain some or all location fields. If this setting is not defined mobiles will not send location information to the server on AuthenticationResponse or ValidateAuthenticationResponse API calls.

Shibboleth

The SAML message will be updated by Shibboleth with location information extracted from the Veridium SessionStatusResponse (extraData) when the session is in the status COMPLETED. In order to pass those specific attributes in the SAML Response will be added in the XML schema as SubjectDerivedAttributes as described at Location in SAML Assertion.