Mobile application version management¶
As organisation you only want approved application versions to be able to communicate with the Onegini Token Server. Therefore application version management is
an important feature of the Onegini Token Server. Each application version which is published must be configured. When talking about an application version a
version of the application for a specific platform is used. So for example:
PaymentApp v1.1 Android.
An application should prove it is the application version it pretends to be when it communicates with the Onegini Token Server for the first time. When this is proven the application will receive credentials which can be used for further communication. Based on these credentials all requests for this application can be correlated to this specific application installation.
In order to create a new application, go to the
Configuration section of the administration console, then
App Configuration and open the
From the list of applications click on the application identifier in the
Identifier column. At the bottom of the screen the versions for this application can
Configure a new application version¶
Click on the
Add App version button to create an App version from scratch. Click on the
Clone App version button to create an App version with the same
configuration as an existing version.
Version fields need to be filled with a version identifier of the mobile app for that platform. The version identifier is a free format text field. It is
advised to use semantic versioning to see the relation between versions in terms of which is the latest.
Status defines whether the Onegini Token Server accepts requests from app installations for this version. The status field has three options:
Enabled: this version of the application can register itself as a new application installation on the Onegini Token Server and existing application installations can be used.
Login enabled, registration disabled: only applications that already had registered before can keep using the Onegini Token Server without upgrading. New registrations for this app version are denied.
Disabled: completely disable the usage of a specific version. For example, when a version configuration is created for future usage, the version contains a severe issue which requires it to be disabled, or when a version is so outdated that customers cannot use it anymore.
The application sends a signature with every request to the Onegini Token Server to prove that it is a genuine app installation. An app developer will deliver
application signatures as described in the App delivery lifecycle topic. Application
signatures are sometimes referred to as Application thumbprints or Application secrets. Configure their values in the
Application signatures fields.
Integrity level defines the strictness of the verification of the application signature. When level
Full is configured, the application signature must
match a checksum on the device. The values of the configured application signature are not verified when the integrity level is
None is only
recommended for development purposes.
Note: The integrity level is only used for Onegini's Android SDK 11+ and iOS SDK 10+. Earlier versions use the settings for Development mode and Tampering protection.
To prevent tampering with the application, for example via byte code manipulation,
Tampering protection checkbox should be enabled. With tampering protection
the application has to prove its identity to the Onegini Token Server in a more strict way.
When tampering protection is enabled the Application signature has to be a hexadecimal formatted string of 32, 48 or 64 characters. When an Application
signature contains a
|, it indicates that it supports multiple architectures, e.g. 32 and 64 bit. Each architecture returns a unique signature for the same
mobile app version. These parts are combined via the
| into a single application signature. When tampering protection is enabled, the validation rules apply
on all parts of the Application signature separated by the
| individually. For example, the application signature
not valid because the first part does not have the correct size.
Note: Development mode and Tampering protection are used for mobile apps with Onegini's Android SDK 10 or lower and iOS SDK 9 or lower. Newer Onegini versions use the Integrity level.
For the communication of sensitive information TLS/SSL might not be sufficient. The
Payload encryption feature adds a layer of encryption to the request and
response. When an attacker is able to compromise the TLS transport layer, they cannot read the contents of the messages because their payload will be encrypted
as well. An installation of the Onegini Security Proxy is required to use payload encryption. Enabling
Payload encryption without the
Onegini Security Proxy does not have any effect.
Configure mobile authentication¶
Note: The mobile authentication configuration is only available when the mobile authentication feature is enabled on system level.
Configure push messaging¶
Push messaging configuration can be selected from the dropdown list. It only shows the Push messaging configurations for the selected platform. For more
information about it go to the Mobile authentication page.
Push messaging to Cordova app¶
This option is only visible for Android. Enable this when you send push messages to an Android app that is using Cordova. When enabled, extra parameters are added to the push message. These are needed to receive the notification when the Cordova app is running in the background.
Use APNs development environment¶
This option is only visible for iOS. This specifies whether the production or development APNs environment is desired. By default, the production environment will be used.
Note: For mobile platform versions with deprecated push messaging configured, the APNs environment will be still fetched from the push messaging configuration and the APNs environment set on application version level will be ignored.
Send badge number¶
This option is only visible for iOS. The badge is the number of unread notifications for an app shown on top of the app icon. When this setting is enabled, it will update the badge with the number of pending push authentications when the push message is sent.
Note: This setting is only present for iOS because an iOS application does not get started until the user clicks on the notification while the android application is started in the background as soon as the notification is received by the device.
Set Application bundle identifier¶
This option is only visible for iOS. 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.
Note: For mobile platform versions with a deprecated push messaging configuration, the Application bundle identifier does not have to be specified.
Remove an existing app version¶
Via the application version list a trash icon can be found. An app version can only be removed when no application installations are using the application version. An alternative to removing a version is forcing end-users to upgrade.
Forcing end-users to upgrade¶
There are several reasons why you would like end-users to upgrade their applications. For example:
- Reduce support costs due to less application versions.
- Act on known security vulnerabilities.
- Backwards incompatibility with backend systems.
- Force users to start using the latest features.
In order to force users to upgrade to a newer application version the old application version must be disabled. This can be achieved by editing the old version
and set the Status to
Disabled. Users will be prompted to upgrade via the app store when using the disabled application. After upgrading from an application
version which is disabled the user can use the application again without having to register again.
Note: Users might experience bad usability when they are forced to upgrade when users only have a mobile connection available. Forcing a user to upgrade makes the current application version unusable.
Prevent new installation usage of the application¶
To prevent new application installations of an outdated version the version can be disabled for new registrations. This can be achieved by editing a version and
set the Status to
Login enabled, registration disabled. Users will be prompted to upgrade via the app store when using the application for the first time.
Users that already used the application before won't notice any disturbance. After upgrading or downgrading from an application version which is disabled, the
user can use the application again without having to register again.