Mobile authentication configuration

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

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

• Configure push enrollment rules
• Configure push authentication
  • iOS
  • Android
• Configure SMS authentication
• Configure access via the API to initiate mobile authentication
• Configure mobile authentication types
  • Push
  • Push with PIN
  • Push with fingerprint
  • Push with FIDO
  • SMS
• Configuration for Callback endpoints

Configure push enrollment rules

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 on one of these devices.

By default a user can only switch from device by disconnecting the enrolled device or disable mobile authentication via the end user device api. By enabling the Device enrollment override enabled option in the admin panel, the user is able to switch between the devices by just enrolling mobile authentication again. Mobile authentication will then be disabled on the previous device. Go to the General mobile config section to configure this option.

Note When mobile authentication 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 push authentication

Push authentication consists of two processes which can be enabled/disabled individually:

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

For push authentication 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 push authentication.

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

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

iOS

For iOS applications the Apple Push Notification Service (APNS) is used. This service uses an SSL certificate for authentication. To configure the certificate the following steps describe the necessary actions on a high-level:

• The mobile application must be registered in the Apple developer member center,
• Locally a certificate file should be generated,
• The generated certificate needs to be uploaded to Apple who will sign this certificate and configures it for the app,
• The signed certificate should be downloaded and exported (Personal Information Exchange format *.p12)

All steps are described in detail in the Apple developer documentation. We use the legacy version of APNS, but the steps to establish certificate-based provider-to-APNS trust have remained the same.

To configure the certificate it has to be in the .p12 format and Base64 encoded. A description how to get the certificate in the format suitable for configuration can be found in our APNS service reference guide.

The password that is used to create the p12 file should be configured as APNS SSL certificate password. Typically the app developer should be responsible for providing the certificate and certificate password once the app is registered in the Apple Dev Center.

Apple supports two environments: production and sandbox. The urls for these environments are pre-configured and can be adapted if required. Please note that both environments need different certificates to be configured in the Apple developer member center.

Note: No outgoing proxy can be configured for APNS. If outgoing traffic is blocked open the ports required by APNS on your firewall.

Android

For Android applications the Google Cloud Messaging (GCM) services are used. The default URI for these services is already configured https://android.googleapis.com/gcm/send. If a different url is required it can be provided as push server endpoint, otherwise leave this field empty.

GCM requires an api key to identify the project/application you would like to send push messages for. This key can be retrieved via the GCM console. In this console navigate to api usage to enable cloud messaging and to retrieve the api key.

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

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

The mobile section of the admin panel contains a tab Mobile authentication types. 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: Push, Push with PIN, Push with fingerprint or SMS. Depending on the selected method some config fields will show up or hide.

An authentication transaction has a limited time to live, this value should be specified in seconds. For example 60 seconds will give the user one minute to answer a push or SMS message. 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 authentication transaction.

As a fallback a different Mobile authentication type can be specified. The fallback is used when the originally requested authorization can not be initialized. For example push is requested but a user did not enroll any application and SMS is specified as a fallback. In this case SMS authorization is started.

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.

Push

A user is only able to receive push messages when the user is enrolled for push. For regular push no refresh 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 used application must have REFRESH_TOKEN configured as an allowed function. 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 transaction 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. There is no need to configure push with PIN as a fallback for this scenario. 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 allowed function.

Push with FIDO

A push with FIDO transaction can be approved by a passing FIDO authentication or by a valid PIN. If a user does not have a FIDO authenticator configured or the device does not support it, the PIN can be used. There is no need to configure push with PIN as a fallback for this scenario. The idea behind this is that the PIN mechanism is always available, while not all devices support FIDO authentication. Therefore the PIN can be always used as a fallback in this case. In order to enable FIDO authentication for an application it must have configuration for the FIDO authenticator.

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 push authentication will only succeed for those URLs that are allowed.
2. Authentication: configuration of the credentials for basic authentication on the callback endpoint.