Geolocation & Authorization info collection

[AlexLobaciov]

Summary:
Reference issue: https://github.com/saltedge/sca-identity-service-example/issues/55

Task:

• [x] 1. On application setup or within the enrollment procedure (if you decide to go with logic described under point 1.3 here) - ask user for permission to collect his GPS data.
  • Text update: "The information on your location will be collected at the time when you authorize action. The collected information will be used for accurate Transaction Risk Analysis"
    Example

• [x] 2. User's location by GPS should determine the 'latitude' and 'longitude', collected data should be sent with action authorization response, see reference issue
• [x] 3. Additionally, method of user auhtorization, either Passcode or Biometrics - should be collected and sent with action authorization response, see reference issue
• [x] 4. Please update Mobile SDK accordingly

UPDATE

User flow:

PROTOYPE = "SCA geolocation" page in default Figma file.

1) "Access to Location Services" (granting permission) when provider sets it as mandatory

---

A. Location Services access after successful enrollment.

Once new connection is finished, user should be asked about granting access for Authenticator to Location Services. It might be that Location Services are off.

• If Location Services are off, user sees system dialogue to turn it on, with description "Turn On Location Services to Allow "Authenticator" to Determine Your Location" with buttons "Settings" and "Cancel". Button "Cancel" just closes the system dialogue; button "Settings" takes user to "Location Services" page in settings, where user should just activate the Location Services and return back to the app.
• If Location Service are on, user sees system dialogue to grant permission for access to Location Services with system question "Allow "Authenticator" to use your location?" and custom description message "Your service provider is requesting you to provide your location data every time you are authorizing an action for accurate risk analysis. You can turn “Precise” location off.", with possibility to disable "Precise location", and options "Allow Once", "Allow While Using App" and "Don't Allow". The options are described below.

1. User taps on "Allow Once"
   • Access is granted for single use, system dialogue window closes, user can tap on "Done" to finish the enrollment and authorize his action(s) while application session is active.
2. User taps on "Allow While Using App" (good-case scenario)
   • Access is granted while using the app, system dialogue window closes, user can tap on "Done" to finish the enrollment and authorize his action(s)
3. User taps on "Don't Allow" (See paragraphs B&C)
   • Access to device location is not granted, system window closes, user can tap on "Done" to finish the enrollment
   • On "Connections" page, the connection status is "Grant access to location data" (see C for details)

---

B. Location Services access if user taps on "Don't Allow" after enrollment

If user denied to grant permission for Salt Edge Authenticator to grant access to Location Services, then user cannot be asked about it once again later, since permission is denied completely.

Use-case: User got pending action authorization.

For pending authorization request, by tap on "Allow" or "Deny", user sees dialogue window with explanation why is Location Services data required with title "Turn on Location Settings", description "Select Location and tap “While Using the App” to allow Authenticator to determine your location, as requested by your service provider.", and buttons "Settings" and "Cancel".

• Button "Cancel" just closes the dialogue window (loop)
• Button "Settings" takes user to "Authenticator" page from Settings, where user should choose "Location" and change the value to "Allow While Using App". When returned back to Authenticator, user can proceed with action authorizations.

As a result, it is required for user to grant permission to access Location Services for this specific provider. Until then, user cannot authorize any action.

---

C. Connection status if access not granted (Don't Allow)

If user did not grant the access to location user can see a different connection status:

1. On "Connections" page, the connection status is "Grant access to location data" and marked with yellow color (FFC130 - for both dark and light themes). The connection menu contains new field "Access to Location".
2. By tap on "Access to Location", user sees dialogue window with explanation why is Location Services data required with title "Turn on Location Settings", description "Select Location and tap “While Using the App” to allow Authenticator to determine your location, as requested by your service provider.", and buttons "Settings" and "Cancel".
   • Button "Cancel" just closes the dialogue window (loop)
   • Button "Settings" takes user to "Authenticator" page from Settings, where user should choose "Location" and change the value to "Allow While Using App".

---

2) Enable "Location Services" when provider sets geolocation data as mandatory

If access to Location Services data is granted for Salt Edge Authenticator app, but "Location Services" is currently disabled/turned off, then when user got pending action authorization, by tap on "Allow" or "Deny", user sees system dialogue to turn it on, with description "Turn On Location Services to Allow "Authenticator" to Determine Your Location" with buttons "Settings" and "Cancel". Button "Cancel" just closes the system dialogue; button "Settings" takes user to "Location Services" page in settings, where user should just activate the Location Services and return back to the app.

---

3) Access to "Location Services" and enabling "Location Services" when provider sets it as optional

1. Access to "Location Service". After enrollment, ask user once for the access to location data

   • if user taps on "Allow While Using App" good, let's collect this data during action authorization and if GPS service is turned on
   • if user taps on "Allow Once" - also good, let's ask him next time about it as well, when authorizing an action (by tap on "Allow"/"Deny")
   • if user taps on "Deny" - user does not want to share this data, and app should not ask user again about it (for this provider)
   • there is no change in Connection status

2. Enabling "Location Service":

   • Don't ask user to turn on "Location Services" when authorizing the action, even if access to "Location Services" data permission is granted

---

Thanks!

[baller784]

1. In the Connection response, should be parsed a new field - geolocation_required

• geolocation_required [bool, optional]

  Add a new optional Bool field isGeolocationRequired in the Connection model.

2. After the successful Connection enrolment, check the received isGeolocationRequired field:

   • If isGeoloctionRequired is nil, skip this step.
   • If isGeoloctionRequired is true, and sharing of the geolocation isn’t already enabled, the mobile app should ask for the permission for Geolocation usage.
   • If isGeolocationRequired is false, and sharing of the geolocation isn’t already enabled, the mobile app should ask for the permission for Geolocation usage.

3. When a mobile application receives the Authorization, check whether this provider requires the geolocation. Access the Authorization’s connection, by the connectionId, which is already in the authorisation response.

4. Authorization flow:

   • If isGeolocationRequired true, and geolocation sharing is enabled, allow user to make an action
   • If isGeolocationRequired is true and the user has declined the geolocation permission, hide the action buttons(Confirm/deny) and replace buttons with the following text: “Your service provider requires your GPS data to authorize action. To continue, please allow using the geolocation in your phone settings”.
   • If isGeolocationRequired false allow user to make an action
   • If isGeolocationRequired is nil allow user to make an action

5. Add GEO-Location header. Geolocation will be shared with SCA service as a HTTP Header in the next format:

   GEO-Location [string, optional] Format using [RFC2426], i.e. GEO:<latitude>;<longitude>

   Example: GEO-Location: “GEO:52.506931;13.144558”

6. By confirming/denying the Authorization the HTTP request should contain the geolocation header. Retrieve the user’s geolocation using the mobile location api and make the request.

[baller784]

Point 3. User authorization type.

We should send the type of how user has been authorized in the app, using biometrics or passcode. To do this, would be a better choice to create a global variable somewhere in the app, which will store the authorization type.

Example: var userAuthorizationType = "biometrics"

The userAuthorizationType should be send, when confirming/denying the authorization, as an HTTP header in the following format:

Authorization-Type [string, required]

Example: "Authorization-Type": "biometrics"

Backend could ignore extra headers, that's why we can send the Authorization-Type with every authorization request.

[AlexLobaciov]

@ConstantinKV @baller784 please take a look on the updated description - user flow, and prototype. Thanks!

[baller784]

@AlexLobaciov

Due to Apple guidelines, it is not allowed by Apple to open specific Settings page (Like Privacy -> Location), cause this API is private. Please see reference here: https://www.zerotoappstore.com/how-to-open-settings-in-ios-programmatically.html (Section How To Open Specific Settings Page in iOS)

[AlexLobaciov]

@baller784 after investigation, the iOS will solely switch user to the Privacy>Location settings the first time. Afterwards, we'll have to instruct user with the following dialogue window with title "Turn on Location Services". description "Salt Edge Authenticator requires Location Services. To turn on Location Services, open the Settings app > select Privacy > select Location Services > enable Location Services" and button "OK". The OK button just closes the dialogue.

Thanks!

[AlexLobaciov]

@baller784 some fixes should be applied.

• [ ] 1) "Turn on Location Services" message from last comment:
  • This message should be shown after enrollment if Location Services are off
  • After what user turns on Location Services and clicks on "Done" for this dialogue, should appear system dialogue "Allow "Authenticator" to use your location?"
  • Also, if permission is not granted, this message now appears even if Location Services are ON, which is incorrect (see video shared in PM). In turn, if Location Services are on, app should display "Allow "Authenticator" to use your location?" dialogue.
• [ ] 2) In Connection menu, please update the geolocation icon to mappin.and.ellipse

Updated the Prototypes, please take a look for the user flow.