Mobile authentication configuration

Via mobile authentication a second factor login can be realized. Mobile authentication is using SMS, OTP and push messages to interact with the end-user. This section will describe how to configure mobile authentication.

Note: Mobile authentication should be enabled on system level.

In the admin console the configuration related to mobile authentication can be found in the mobile config section.

General mobile config

Configure mobile authentication enrollment rules

A user must enroll with PGP encryption keys to use mobile authentication.

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


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:

configure ios push messaging

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.


In order 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:

configure android push messaging

Configure FCM endpoint (optional)

For Android applications the Firebase Cloud Messaging (FCM) services are used. The default endpoint for this service is 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_​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 to protect 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

Mobile authentication type

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.

An authentication transaction has a limited time to live, specified in seconds. This value determines how long the user has to answer a mobile authentication request, from the moment the request has been initialized by the portal. 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.


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.


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.


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

With SMS authentication the user will receive a six digit code, this code is included in the message. In both the message provided via the api and the default messages. A placeholder must be included to indicate where the code should be inserted in the message. The placeholder to be used is {code}. An example SMS message: Your example SMS code: {code}. If the {code} placeholder is not included in the message, it will fallback to only sending the code value with no additional message.

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

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.

Callback Config

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.