Mobile authentication

The end-user can approve actions using mobile authentication. These actions can be bank transfers or purchases, but you can also utilize mobile authentication to sign in to a website. There are three methods to interact with the end-user: via push messages, text messages (SMS), or a One Time Password (OTP). The process for the mobile authentication will differ per method.

Flows

Push messaging

The end-user must have installed a mobile app with the Onegini SDK to use mobile authentication via push messaging. After the end-user has installed the app, they must enroll their app for mobile authentication with push messaging. The website initiates the mobile authentication at the Onegini Token Server which sends a push message via Google's FCM or Apple's APNs service to the mobile device. When the end-user interacts with the push message, the mobile app is opened. The mobile app will ask the end-user to approve the transaction. For extra security, the end-user may need to authenticate by entering their pin, or using biometric authentication (fingerprint, face recognition). This is configurable. The Onegini SDK sends the approval result to the Onegini Token Server which then notifies the website.

One time code via SMS

For SMS, the end-user does not have to install anything on their mobile device. The website initiates the mobile authentication at the Onegini Token Server which sends a text message with a code to the end-user. The website then needs to present a screen to the end-user to enter the code that was sent via SMS. When the end-user has entered the code, the website sends this to the Onegini Token Server which returns the validation result.

One Time Password

The end-user must have installed a mobile app with the Onegini SDK to use mobile authentication via OTP. After the end-user has installed the app, they must enroll their app for mobile authentication. The website initiates the mobile authentication at the Onegini Token Server which returns a (long) code. A common process is to include this code in a QR-code which the end-user can scan with their mobile device. When the end-user is already on their mobile device, you can create a link that opens the mobile app. The mobile app then sends the code to the Onegini Token Server which will notify the website about the result.

Configuration

In the admin console, go to Configuration -> Mobile authentication.

When Mobile authentication is not visible, you must enable it as a feature in Configuration -> System -> Features.

Configure mobile authentication enrollment rules

A user must enroll their device with PGP encryption keys to use mobile authentication with push or OTP.

Note: The following options are not accessible if enrollment is disabled.

By enabling the Unique PGP keys per enrollment enabled option in General subsection in the admin panel, for every user enrollment a new PGP key pair will be generated. For better performance it is advised to not enable this option.

Go to the General subsection in General mobile config section to configure described options.

Configure enrollment for mobile authentication with push rules

Note: In order to be able to configure push enrollment rules, mobile authentication enrollment must be enabled. Mobile authentication with push enrollment is not possible without mobile authentication enrollment performed upfront.

A user must enroll their push configuration to use mobile authentication via push messaging.

By default, a single user can enroll only a single device for single application. In order to enroll a different device or re-enroll for an application again the current device needs to be deleted - see User Management and Device API for further details. To overcome this limitation it is possible to change Push enrollment mode mode:

• Single device - only a single device is allowed per user for a given application, an attempt to enroll a new device will fail (default)
• Override allowed - only a single device is allowed per user for a given application, but enrollment of a new device automatically replaces the previously registered device
• Multiple devices - enrollment of multiple devices is allowed. If this is enabled, you must be using version 4 of the API. Version 2 and 3 of the API will respond with Not Found (404) with this configuration. A user may register different devices for different applications regardless of this setting.

Warning: When mobile authentication with push is the only method for second factor authentication, enabling either override allowed or multiple device support might introduce a security risk. Anyone who has access to the first factor credentials can enroll a new device and use this device for second factor authentication. A decision to enable multiple device support should therefore be taken carefully.

Configure mobile authentication with push

Mobile authentication with push consists of two processes which can be enabled/disabled individually:

• Device enrollment: this process is used to activate mobile authentication with push for a user on a certain device.
• Authorization: this process is used to actually send push messages to users for authorization.

For mobile authentication with push platform specific services are used offered by the platform vendors (Google and Apple). In the application version configuration section, the administrator can specify the platform of a version and the app version specific configuration for mobile authentication with push.

Some optional detailed technical configuration can be done via the mobile authentication Docker Compose environment variables.

To perform the actual authentication with push some mobile authentication types have to be configured.

This section describes how to configure push messaging for iOS and Android. Go to the Push messaging configuration section of the Mobile Authentication section

iOS

In order to configure iOS specific push messaging go to the Push messaging configuration subsection of the Mobile Authentication section. Click the Add push messaging configuration and select ios platform to display iOS specific configuration fields like on the image below:

For iOS applications the Apple Push Notification service (APNs) is used to send notifications. This service allows clients (for example, the Token Server) to authenticate using signed JSON web tokens (JWT). This involves some configuration on the part of the administrator.

The overview of the APNs can be found in Apple developer documentation .

Configure push messaging

Note: The Token Server previously used certificate authentication, which was configured per application and whose configuration was significantly more complex. The newer token authentication supported by Apple is a much more straightforward process and can be used across all applications per team, which is why support for certificate authentication has been dropped for newer applications (old configurations still work, but should be migrated as soon as possible).

• Register the mobile application in the Apple developer account
• Retrieve the Apple developer team ID (you can find it under Account -> Membership).
• Download an APNs auth key from the Apple developer account (making a note of its identifier). This download is in the form of a .p8 file, which is a PKCS#8 encoded EC private key, in PEM format. You can find more information on how to create an APNs authentication token signing key in the Apple Developer Account Help.

The Apple developer team ID and key ID should be entered into the form. The .p8 file should be selected using the form input.

APNs environment

Apple supports two environments: production and development (also known as sandbox). The URLs for these environments are pre-configured. Both environments can be accessed using the same push messaging configuration. The desired environment is therefore not specified in the push messaging configuration. Instead, the desired environment can be configured at application version level. See app version management for more details.

Note: For mobile platform versions with deprecated push messaging configured, the APNs environment will be still fetched from push messaging configuration and APNs environment set on application version level will be ignored.

Application bundle identifier

The Application bundle identifier is a unique identifier of an app. It uses the reverse domain name notation. You can find it in the Certificates, Identifiers & Profiles page page of your Apple developer account. Multiple applications can use the same push messaging configuration. The Application bundle identifier is therefore not specified in the push messaging configuration. Instead, the desired Application bundle identifier can be configured at application version level. See app version management for more details.

Note: For mobile platform versions with deprecated push messaging configured, the Application bundle identifier does not need to be specified.

Configure outgoing proxy (optional)

If you are using an outgoing proxy. An outgoing proxy can be configured for APNs. Go to the proxy configuration guide to learn how to configure an outgoing proxy.

Android

To configure Android specific push messaging go to the Push messaging configuration subsection of the Mobile Authentication section. Click the Add push messaging configuration and select android platform to display Android specific configuration fields like on the image below:

For Android applications, the Firebase Cloud Messaging (FCM) services are used.

Note: Your client application needs to be registered in the Firebase Console to use Firebase. In order to setup your Android app to use FCM follow the steps described in Add Firebase to your app FCM guide.

Firebase Cloud Messaging (FCM) API versions
FCM introduced new type of APIs, HTTP v1 APIs, which will replace existing legacy APIs. Legacy APIs were deprecated on 6/20/2023 and will stop working on 6/20/2024. Because of this, all existing push messaging configurations should migrate to use HTTP v1 APIs as soon as possible. New push messaging configurations should use HTTP v1 APIs. Information about differences in APIs is available here.

Configuration using HTTP v1 FCM APIs (recommended)

• Obtain the FCM Service Account Key JSON file from the Firebase Console. Description about how to do this is available here.
• Proceed to FCM Push Messaging section of Add Push messaging configuration form
• Select HTTP v1 API FCM API Version
• Select downloaded Service Account as FCM Service Account key

Configuration using Legacy FCM APIs (deprecated)

Configure FCM endpoint (optional)

The default endpoint for this service is https://fcm.googleapis.com/fcm/send. If a different URL is required it can be provided as push server endpoint, otherwise leave this field empty.

Configure FCM endpoint (optional)

For Android applications the Firebase Cloud Messaging (FCM) services are used. The default endpoint for this service is https://fcm.googleapis.com/fcm/send. If a different URL is required it can be provided as push server endpoint, otherwise leave this field empty.

Configure FCM Server key

Note: Your client application needs to be registered in the Firebase Console to use Firebase. In order to setup your Android app to use FCM follow the steps described in Add Firebase to your app FCM guide.

FCM requires an API key to identify the project/application you would like to send push messages for. In order to configure it, follow the steps described below:

1. Go to your project dashboard in Firebase Console.
2. Click the cog in the left hand menu, and select Project Settings.
3. Choose Cloud messaging tab
4. Copy the Server key and provide it in the FCM Key for server applications field of the Android push messaging configuration in the Token Server Admin Console.

Configure outgoing proxy (optional)

If you are using an outgoing proxy. A proxy can be configured for the communication with FCM. For the proxy functionality the following settings can be set.

Property	Description
TOKEN_SERVER_ENGINE_EXTERNAL_REST_SERVICES_PROXY_ENABLED_BOOLEAN	Boolean to indicate if a proxy should be used, by default using a proxy is disabled.
TOKEN_SERVER_ENGINE_EXTERNAL_REST_SERVICES_PROXY_PREEMPTIVE_AUTH_ENABLED_BOOLEAN	Boolean to indicate if preemptive authentication must be enabled for the specified proxy host.
TOKEN_SERVER_ENGINE_EXTERNAL_REST_SERVICES_PROXY_USERNAME	Username for authentication on the proxy if authentication is required.
TOKEN_SERVER_ENGINE_EXTERNAL_REST_SERVICES_PROXY_PASSWORD	Password for authentication on the proxy.
TOKEN_SERVER_ENGINE_EXTERNAL_REST_SERVICES_PROXY_SCHEMA	Schema of the proxy (default is http).
TOKEN_SERVER_ENGINE_EXTERNAL_REST_SERVICES_PROXY_HOST	Hostname of the proxy.
TOKEN_SERVER_ENGINE_EXTERNAL_REST_SERVICES_PROXY_PORT	Port of the proxy (default is 8080).

Configure SMS authentication

SMS authentication only consists of a single process called authorization. This process needs to be enabled to send out SMS messages to users.

A prerequisite is that a SMS gateway is configured in the technical configuration of the application by setting a Docker Compose environment variable TOKEN_SERVER_ENGINE_CUSTOM_HOOKS_SMS_GATEWAY. As the SMS gateway the implementation corresponding to the used SMS service provider should be used, by default Twilio is used.

To do the actual SMS authentication mobile authentication types for SMS have to be configured

Configure access via the API to initiate mobile authentication

Mobile authentication can be initiated via a REST API. So mobile authentication can be integrated with another application like a portal or resource gateway.

The Mobile authentication API is protected via basic authentication or credentials from url encoded form .

We strongly recommend protecting the authentication API by infrastructural measures like an IP whitelist.

Details about the API can be found in the mobile authentication api reference.

Configure mobile authentication types

The mobile section of the admin panel contains a Mobile authentication types tab. In this tab you can manage different types of authentication.

Each mobile authentication type has a unique name which is used as an identifier. The authorization method defines the method that will be used. Examples include push, push with PIN, push with fingerprint, OTP, and SMS. Depending on the selected method some configuration fields will be hidden or displayed.

In the Max allowed resends field you can specify how many times it is allowed to send the same verification code again (the value 0 means that resending is disabled).

An authentication transaction has a limited time to live, specified in seconds. This defines the maximum amount of time for the end-user to complete the mobile authentication transaction, calculated from the moment the mobile authentication was initialized. For authentication methods where a user has multiple attempts to enter a code (e.g. SMS or Push with PIN), all the attempts need to take place within the specified time to live of the mobile authentication type.

A different mobile authentication method can be specified as a fallback. The fallback is used when the originally requested mobile authentication method can not be initialized. For example, a mobile authentication type with method Push may be configured to use SMS as a fallback. In the event that the user has not enrolled any applications for push authentication, the Token Server will not be able to send a push notification. Instead, it will start SMS authentication.

Default messages can be configured in case no message was provided via the API. If no default message is specified for the requested language, the English default message is used. Default messages can be configured for specific language codes. In order to support more languages than the default the following Docker Compose environment variable needs to be changed TOKEN_SERVER_ADMIN_GENERAL_SUPPORTED_LOCALES.

For all types of mobile authentication except SMS, a user must have completed key enrollment with the Token Server.

Push

To receive push messages, a user must be enrolled for push, in addition to having keys enrolled. For regular push no refresh token or access token is required for the user, only an enrolled application.

Push with PIN

Push with PIN requires the user to have a refresh token. Therefore the application used must have PIN authentication enabled. In this application config also the max allowed PIN attempts must be configured. So when a user receives a push with PIN request for this application the user is disconnected after the max number of attempts is exceeded.

Push with Fingerprint

A Push with Fingerprint mobile authentication request can be approved by a valid fingerprint or by a valid PIN. If a user does not have a fingerprint configured or the device does not support it, the PIN can be used. The idea behind this is that the PIN mechanism is more secure than the fingerprint authentication. Therefore, the PIN can be always used as a fallback in this case. In order to enable fingerprint authentication for an application it must have the Fingerprint authentication enabled.

Push with Custom Authenticator

A transaction for Push with Custom Authenticator can be approved via the authentication flow of the Custom Authenticator or by entering a valid PIN. If the user does not have a Custom Authenticator configured, they can use the PIN. The PIN is always available. In order to enable Custom Authenticators for an application it must have configuration for the Custom Authenticator.

OTP

For OTP authentication, the user's application obtains an OTP (One Time Password) directly from the portal. For example, after having initialized a mobile authentication request (without specifying the user), the web portal may display a QR code that the user can scan using their app. The OTP is then used to link the user's unauthenticated session on the portal to the authenticated session in the app. To configure an OTP authentication type, only the name, OTP type, and a time to live need to be specified. Fallback is not supported for OTP.

SMS

For SMS based authentication, the maximum number of attempts has to be specified. When this value is 0 the user can try to enter codes until the request has expired. When the maximum is set, the transaction is invalidated when the maximum amount of attempts is exceeded.

Text messages are sent from the phone number that is configured for the SMS provider. You can configure a specific sender per mobile authentication type. This can be a phone number, a short code that is registered with your SMS provider, or an alphanumeric sender id (e.g. your brand name). Not all countries support sending SMS messages from an alphanumeric sender id, while other countries require to register the sender id up front. Configuring the sender id per mobile authentication type is optional. When Twilio is configured as SMS provider and sending the text message fails with the sender id for this mobile authentication type, the Onegini Token Server will retry sending the SMS using the phone number that is configured via the environment variable TOKEN_SERVER_ENGINE_SMS_GATEWAY_TWILIO_FROM_NUMBER.

SMS message body

With SMS authentication, the end-user will receive a six digit code. This code must be included in the message. This message can be configured up front or sent with the api request that triggers the mobile authentication. A placeholder must be included to indicate where the code should be inserted in the message. The placeholder to be used is {code}. If the {code} placeholder is not included in the message, the Onegini Token Server will only send the code in the text message and no additional message.

An example SMS message: Your example SMS code: {code}.

The Onegini Token Server is sending SMS for one time codes. There is a ( proposed) standard for sending one time codes via SMS. Some browsers will suggest using the code that has been sent for that domain. For the autocomplete, the message must end with:

• a newline
• @ plus the host name of the website where the end-user enters the code, e.g. @www.example.com
• # plus the code: #code

Your verification code is: {code}

@www.example.com #{code}

Configuration for Callback endpoints

The configuration for Callback endpoints serves two purposes:

1. Whitelisting: if the callback URL whitelist is enabled in the Mobile config, the mobile authentication will only succeed for those URLs that are allowed.
2. Authentication: 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.

In order to enable this feature the following conditions must be met:

• the geolocation feature is enabled.
• the geolocation service is 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 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 end-users' operating system detected based on the user-agent http header
browser	user_agent	Chrome 73.0	The end-users' browser of the end-user detected based on the user-agent http header
countryCode	ip_address	NL	The end-users' code of the country detected based on the ip address
region	ip_address	Provincie Utrecht	The end-users' region detected based on the ip address
city	ip_address	Utrecht	The end-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 will not get back values for operatingSystem or browser.

You should coordinate the formatting with the device that will be displaying this message to make it more readable/clear. You can also mix and match the order phrasing. For example: [message] using [browser] from [city], [countryCode] would yield You are logging into the XYZ portal using Chrome 73.0 from Utrecht, NL

The template mechanism supports internationalization. The actual language used in each case is picked based on the language_code field provided together with ip_address and user_agent as a part of mobile authentication initialization request. If no template exists for the specified language_code or language_code is not provided, the template will default to English.

Any error encountered during geolocation resolution such as the service being inaccessible/unavailable or an incomplete/malformed response being returned will result in only the base message being sent to the mobile application. An event will also be logged indicating the error in the administration console for help with troubleshooting.