Mobile application version management

As an organization, you only want approved application versions to be able to communicate with the OneWelcome Identity Platform. Therefore application version management is an important feature. Each application version that is published must be configured. A version of the application for a specific platform is used, such as PaymentApp v1.1 Android.

An application should prove it is the application version it pretends to be when it communicates with the OneWelcome Identity Platform for the first time. When this is proven, the application receives credentials that can be used for further communication. Based on these credentials, all requests for this application can be correlated to this specific application installation.

To create a new application, go to the Configuration section of the administration console, then App Configuration, and open the Applications tab.

From the list of applications, click the application identifier in the Identifier column. At the bottom of the screen, the versions for this application can be managed.

Configure a new application version

• To create an app version, click the Add App version button.

• To create an app version with the same configuration as an existing version, click the Clone App version button.

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

The Status defines whether the OneWelcome Identity Platform accepts requests from app installations for this version. The status field has three options:

1. Enabled: This version of the application can register itself as a new application installation on the OneWelcome Identity Platform and existing application installations can be used.

2. Login enabled, registration disabled: Only applications that are already registered can continue using the OneWelcome Identity Platform without upgrading. New registrations for this app version are denied.

3. Disabled: The use of a specific app version is completely disabled. For example, use this status when a version configuration is created for future usage, the version contains a severe issue that requires it to be disabled, or when a version is so outdated that customers cannot use it anymore.

Security settings

Security settings: Application signature

The application sends a signature with every request to the OneWelcome Identity Platform to prove that it is a genuine app installation. An app developer delivers 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.

The Integrity level defines the strictness of the verification of the application signature. When the Full level 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. The None level is only recommended for development purposes.

Note

The integrity level is only used for the OneWelcome Identity Platform 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 check box should be enabled. With tampering protection, the application has to prove its identity to the OneWelcome Identity Platform in a more strict way.

Tampering protection option for iOS SDK 11+ is deprecated. Use integrity level FULL and use a new app signature (App ID) calculated from the TeamID and BundleID instead of the one created from the calculator. For more information, check here.

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, such as 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 12345|ABCDEF1234567890ABCDEF1234567890 is not valid because the first part does not have the correct size.

Note

Development mode and tampering protection are used for mobile apps with the OneWelcome Identity Platform Android SDK 10 or lower and iOS SDK 9 or lower. Newer versions use the integrity level.

Security settings: Payload encryption

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 is encrypted as well. An installation of the OneWelcome Identity Platform security proxy is required to use payload encryption. Enabling payload encryption without the security proxy does not have any effect.

Configure mobile authentication

The mobile authentication configuration is only available when the mobile authentication feature is enabled at the system level.

Configure push messaging

Push messaging configuration can be selected from the drop-down list. It only shows the push messaging configurations for the selected platform. For more information about it, see mobile authentication.

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 is used.

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 updates 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 the notification, whereas 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.

Remove an existing app version

The application version list includes a trash icon for removing a version. An app version can only be removed when no application installations are using the application version. An alternative to removing a version is forcing users to upgrade.

Forcing users to upgrade

There are several reasons why you might want users to upgrade their applications, such as the following examples:

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

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 setting the status to Disabled. Users are prompted to upgrade via the app store when using the disabled application. After upgrading from an application version that is disabled, the user can use the application again without having to register again.

Note

Users might experience poor usability when they are forced to upgrade when they 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 setting the status to Login enabled, registration disabled. Users are prompted to upgrade via the app store when using the application for the first time. Users that previously used the application won't notice any disruption. After upgrading or downgrading from an application version that is disabled, the user can use the application again without having to register again.