Mobile authentication
The user can approve actions using mobile authentication. These actions can be bank transfers or purchases, but you can also use mobile authentication to sign in to a website. There are three methods to interact with the user: via push messages, text messages (SMS), or a One-Time-Password (OTP). The process for the mobile authentication differs per method.
The user flows and configuration options per method are described in their specific pages:
General configuration
In the admin console, go to Configuration → Mobile authentication. The configuration options on this page are explained on the pages for each authentication method.
When Mobile authentication is not visible, you must enable it as a feature in Configuration → System → Features.
Configuration for callback endpoints
The configuration for callback endpoints serves two purposes:
-
Restrictions: If the Only allow preconfigured Callback URLs option is enabled in the mobile configuration, the mobile authentication only succeeds when the callback URL in the request matches one of the preconfigured callback URLs.
-
Authentication: Used for configuration of the credentials for basic authentication on the callback endpoint.
| Field | Required | Description |
|---|---|---|
| Callback URL | yes | URL that is used for the callback of mobile authentication. Must match exactly with the requested callback URL. |
| Username | no | Optional username for basic authentication when calling the callback URL. |
| Password | no | Optional password for basic authentication when calling the callback URL. |
Adding additional context to the secure message
Both push and OTP types give the ability to specify additional parameters as part of the initialization process to give users more context about where the request is originating. This is useful in mitigating phishing attempts since the user is given more details before they confirm the requested action.
To enable this feature the following conditions must be met:
-
the geolocation feature is enabled and properly configured
-
the mobile authentication initialization request contains the following optional fields:
ip_address,user_agent.
It is possible to customize the way additional context is added to the secure message by modifying the template available under the mobileAuthentication.confirmation.template key. This template contains predefined placeholders that are replaced at runtime with the actual values.
| Placeholder | Init parameter | Example value | Description |
|---|---|---|---|
| message | secure_message |
You are logging into the XYZ portal | The secure message provided as a part of mobile authentication initialization |
| operatingSystem | user_agent |
Mac 10.14 | The users' operating system detected based on the user-agent HTTP header |
| browser | user_agent |
Chrome 73.0 | The users' browser detected based on the user-agent HTTP header |
| countryCode | ip_address |
NL | The users' code of the country detected based on the IP address |
| region | ip_address |
Provincie Utrecht | The users' region detected based on the IP address |
| city | ip_address |
Utrecht | The users' city detected based on the IP address |
By default, the template has the following value:
[message] Device: [operatingSystem] [browser], Location: [countryCode], [region], [city]
The placeholders correspond to the different init parameters as defined in the table above. For example, if you don't send user_agent during the init request, you don't get back values for operatingSystem or browser.
You should coordinate the formatting with the device that displays this message to make it more readable. You can also mix and match the order of the phrasing. For example, [message] using [browser] from [city], [countryCode] results in You are logging in to the XYZ portal using Chrome 73.0 from Utrecht, NL.
The template mechanism supports internationalization. The actual language used in each case is chosen based on the language_code field provided together with the ip_address and user_agent as a part of a mobile authentication initialization request. If no template exists for the specified language_code, or the language_code is not provided, the template defaults to English.
Any error encountered during geolocation resolution, such as the service being inaccessible or unavailable, or an incomplete or malformed response being returned, results in only the base message being sent to the mobile application. An event is also logged indicating the error in the administration console for help with troubleshooting.
