To properly secure your application, enable the predefined MobileFirst application-authenticity security check (
appAuthenticity). When enabled, this check validates the authenticity of the application before providing it with any services. Applications in production environment should have this feature enabled.
To enable application authenticity, you can either follow the on-screen instructions in the MobileFirst Operations Console → [your-application] → Authenticity, or review the information below.
- Application authenticity is available in all supported platforms (iOS, watchOS, Android, Windows 8.1 Universal, Windows 10 UWP) in both Cordova and native applications.
- Application Authenticity flow
- Enabling Application Authenticity
- Configuring Application Authenticity
- Build Time Secret (BTS)
Application Authenticity Flow
The application-authenticity security check is run during the application’s registration to MobileFirst Server, which occurs the first time an instance of the application attempts to connect to the server. By default the authenticity check does not run again.
Once app authenticity is enabled and if customer needs to introduce any changes in their application, then the application version needs to be upgraded.
See Configuring application authenticity to learn how to customize this behavior.
Enabling Application Authenticity
For application authenticity to be enabled in your application:
- Open the MobileFirst Operations Console in your favorite browser.
- Select your application from the navigation sidebar and click on the Authenticity menu item.
- Toggle the On/Off button in the Status box.
MobileFirst Server validates the application’s authenticity on the first attempt to connect to the server. To apply this validation also to protected resources, add the
appAuthenticity security check to the protecting scope.
Disabling Application Authenticity
Some changes to the application during development might cause it to fail the authenticity validation. Accordingly, it is recommended to disable application authenticity during the development process. Applications in production environment should have this feature enabled.
To disable application authenticity, toggle back the On/Off button in the Status box.
Configuring Application Authenticity
By default, Application Authenticity is checked only during client registration. However, just like any other security check, you can decide to protect your application or resources with the
appAuthenticity security check from the console, following the instructions under Protecting resources.
You can configure the predefined application-authenticity security check with the following property:
expirationSec: Defaults to 3600 seconds / 1 hour. Defines the duration until the authenticity token expires.
After an authenticity check has completed, it does not occur again until the token has expired based on the set value.
To configure the
Load the MobileFirst Operations Console, navigate to [your application] → Security → Security-Check Configurations, and click on New.
Search for the
Set a new value in seconds.
Build Time Secret (BTS)
The Build Time Secret (BTS) is an optional tool to enhance authenticity validation, for iOS and watchOS applications only. The tool injects the application with a secret determined at build time, which is later used in the authenticity validation process.
The BTS tool can be downloaded from the MobileFirst Operations Console → Download Center.
To use the BTS tool in Xcode:
- Under the Build Phases tab click the + button and create new Run Script Phase.
- Copy the path of BTS Tool and paste in the new Run Script Phase you have created.
- Drag the Run Script Phase above the Compile sources phase.
- This step is required only if the application environment is watchOS. To enable BTS, developer needs to pass any swift file name, which is packaged in the watchOS extension after the BTS tool location.
For example, suppose if the watchOS extension package contains
HelloWatchOS.swift file, the developer will need to pass
HelloWatchOS as an argument along with the path of BTS tool.
The tool should be used when building a production version of the application.
The application authenticity algorithm uses application data and metadata in its validation. The first device to connect to the server after enabling application authenticity provides a “fingerprint” of the application, containing some of this data.
It is possible to reset this fingerprint, providing the algorithm with new data. This could be useful during development (for example after changing the application in Xcode). To reset the fingerprint, use the reset command from the mfpadm CLI.
After resetting the fingerprint, the appAuthenticity security check continues to work as before (this will be transparent to the user).
Mobile First Platform Foundation provides static and dynamic app authenticity for applications. These validation types differ on the algorithm and attributes used to generate app authenticity seeds. By default, when application authenticity is enabled, it uses the dynamic validation algorithm. Both the validation types ensure the security of the application. Dynamic app authenticity uses strict validations and checks for app authenticity. For static app authenticity, we use slightly relaxed algorithm, which will not use all the validation checks as used in dynamic app authenticity.
The dynamic app authenticity is configurable from MobileFirst Console. The internal algorithm takes care of generating app authenticity data based on the options chosen in console. For static app authenticity, one need to use the mfpadm CLI.
For enabling static app authenticity and to switch between validation types, use the mfpadm CLI:
mfpadm --url= --user= --passwordfile= --secure=false app version [RUNTIME] [APPNAME] [ENVIRONMENT] [VERSION] set authenticity-validation TYPE
TYPE can either be
Support for SDK versions 22.214.171.124-MFPF-IF201701250919 or earlier
The dynamic and static validation types are only supported by client SDKs released in February 2017 or later. For SDK versions 126.96.36.199-MFPF-IF201701250919 or earlier, use the legacy application authenticity tool:
The application binary file must be signed by using the mfp-app-authenticity tool. Eligible binary files are:
ipa for iOS,
apk for Android, and
appx for Windows 8.1 Universal & Windows 10 UWP.
- Download the mfp-app-authenticity tool from the MobileFirst Operations Console → Download Center.
Open a Command-line window and run the command:
java -jar path-to-mfp-app-authenticity.jar path-to-binary-file
java -jar /Users/your-username/Desktop/mfp-app-authenticity.jar /Users/your-username/Desktop/MyBankApp.ipa
This command generates an
MyBankApp.authenticity_data, next to the
- Upload the
.authenticity_datafile using the mfpadm CLI:
app version [RUNTIME-NAME] APP-NAME ENVIRONMENT VERSION set authenticity-data FILE
If application authenticity feature is turned on in the Mobile Foundation server, the Application Authenticity feature crashes app during runtime. This issue happens only when app is built using gradle plugin >= v3.6.0 & gradle version >= v5.6.4 and app is run from Android Studio using Android Studio Run button and installed on the device.
When app is run from Android Studio, the Android Studio removes some of the files from apk needed for app authenticity to work, hence during runtime app crashes with below errors :
2020-08-18 11:43:29.534 17533-22369/? A/pstarterandroi: java_vm_ext.cc:570] JNI DETECTED ERROR IN APPLICATION: java_object == null
2020-08-18 11:43:29.534 17533-22369/? A/pstarterandroi: java_vm_ext.cc:570] in call to GetObjectClass
2020-08-18 11:43:29.534 17533-22369/? A/pstarterandroi: java_vm_ext.cc:570] from java.lang.String com.worklight.common.security.AppAuthenticityToken.a1(android.content.Context, java.lang.String)
2020-08-18 11:43:29.688 17533-22369/? A/pstarterandroi: runtime.cc:631] Runtime aborting...
2020-08-18 11:43:29.688 17533-22369/? A/pstarterandroi: runtime.cc:631] Dumping all threads without mutator
This issue is not observed when apk is built in Android Studio or using gradle or cordova command and installed apk via Play Store or adb or cordova command on the device.▲