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. The user can be enrolled on several devices at a time.

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

By default a user can enroll again only by disconnecting the enrolled device or disable mobile authentication via the end user device api. By enabling the Enrollment override enabled option in General subsection in the admin panel, the user is able to update the PGP encryption keys by just enrolling mobile authentication again.

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 on an application instance to use mobile authentication via push messaging. The user can be enrolled on only one application instance at a time. If a user has a smart phone and a tablet on which the application is installed, the user can only enroll for mobile authentication with pushon one of these devices.

By default a user can only switch devices by disconnecting the enrolled device, or disabling mobile authentication with push via the end user device API. By enabling the Enrollment override enabled option in the Push authentication subsection in the admin panel, the user is able to switch between the devices by just enrolling for mobile authentication with push again. Mobile authentication with push will then automatically be disabled on the previous device. Go to the General mobile config section to configure this option.

Note: When mobile authentication with push is the only method for second factor authentication, enabling the override enrollment function 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 the device enrollment override feature 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:

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

  • The mobile application must be registered in the Apple developer account
  • The Apple developer team ID should be retrieved (which can be found under Account -> Membership).
  • An APNs auth key should be downloaded 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 here.

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

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 URI for these services is already configured 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.

Mobile authentication API version 2 is protected by oauth credentials (see more information here). The unprotected API version 1 can be used if and only it is enabled with a Docker Compose environment variable (see more information here).

We strongly recommend to protect the authentication API by infrastructural measures like an IP whitelist, especially if using the deprecated API is enabled. The following endpoint for deprecated API must be a part of that IP whitelist: /oauth/authenticate/user/{user_id} (in API version 2 this endpoint is /oauth/api/v2/authenticate/user).

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.

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

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.