Ordering an Access App

This document guides you through the process of ordering a branded Access App compatible with the Nevis Mobile Authentication Solution.

Place your order

Start the process by submitting a request via the Nevis portal. If you don't have access to our portal, contact [email protected].

Our staff will get back to you and provide you with:

• A spreadsheet to provide us with the required information.
• An editable template to customise the look and feel.

The process to order an Access App consists of the following steps:

1. Providing Required Information
2. Access App Delivery
3. Finalization
4. Distribution

After initial publication, Access App releases and updates are handled by the update process described in the chapter Update and Release Process.

Providing Required Information

Responsible: Partner and customer

Technical Information

As part of the order process, you will receive a spreadsheet from us to help you providing the technical information. This section explains the technical options and features in detail and will help you filling out the spreadsheet.

1. App Name

The name of the Access App is what the end user sees in the public app stores as well as on their device after installation.

2. App Link Domain / Customer URI scheme (with x-callback-url support)

The mobile-only feature of the Access App requires

• either one or more URI schemes, or
• one or more domains other than the one supplied with the Backend URL.

Recommendation

We recommend using app links instead of custom URIs.

caution

When using x-callback-urls, it is required to supply navigation whitelist, specifying which navigation targets are allowed. This is necessary to prevent malicious manipulation of the rendered links and unintended navigation.

The whitelist can consist of

1. Custom URI schemes for app navigation. For example: myapp://. The Access App will navigate only to applications that have registered for the custom URI scheme myapp.

2. HTTPS domains. For example: https://mydomain.com. The Access App will only allow callbacks to HTTPS URLs in the mydomain.com domain. If an application is attached to that domain through App Links (in Android) or Universal Links (in iOS), the Access Application will navigate to that application. If not, the URL will be opened in the default Web browser on the mobile device.

   You can also use wildcards in the domain to allow invoking all the subdomains: https://*.mydomain.com.

If you use x-callback-urls to navigate to another application, using HTTPS domains (that is, using applications configured with App links or Universal links) is more secure than using applications with a custom URI scheme. The reason is that any application can be configured to use a given URI scheme, but only the applications that are allowed in your domain can be configured to use app links or universal links with that domain.

3. Configurable App Features

Specific Access App features can be turned on or off based on customer requirements:

• Forced Access App Update (Default: disabled)
• Multi-account (Default: enabled)
• Callback Timeout (Default: 5 seconds)
• Class 2 Authenticator support (Android only, default: disabled)
• Biometric Authentication Passcode Fallback (Default: disabled)
• Remove Biometric Authenticator on New OS Biometrics (Default: enabled)
• PIN minimum and maximum length (Default: 6 digits)

If no information regarding the configurable features is provided, each feature is either enabled or disabled according to the default setting for that specific feature.

4. App Identifier

The app identifier (or bundle identifier) uniquely identifies the app. It must be unique in the app store ecosystem. It is recommended using the reverse domain name notation. For example: ch.nevis.accessapp

caution

The app identifier has to match the app identifier used for the Firebase Push Configuration.

5a. Privacy Policy URL

The URL to a web page containing the private policy information. The user can access the contents by clicking on the Privacy Policy item in the settings screen of the Access App.

Privacy policy URLs in configuration are processed as URI Templates (RFC6570) with the following restrictions:

• Only Level 1 URI Templates are supported.
• Only the following variables are supported for config URLs:
  • lang: This parameter is expanded to a ISO 639-1 language code used currently run-time by the application. E.g.: “en“, “de“
  • langCountry: This parameter is expanded to full IETF language tags including the country code. E.g.: “en-US”, “de-CH”

note

Using URI Template expressions in URLs are optional. If a not supported variable is used, the expression is expanded to an empty string.

5b. Help URL

An optional URL to a web page containing information for the end user. If provided, the user can access the contents by clicking on the Help item in the settings screen of the Access App.

The URI Templates (RFC6570) is also supported in the help URL with the same restrictions those described in case of Privacy Policy URL.

5c. Registration URL

An optional URL that points to a registration web page. If provided, the user can access the contents by clicking on the Open registration page item in the settings screen of the Access App. This item is displayed only the user does not have any registered account.

The URI Templates (RFC6570) is also supported in the registration URL with the same restrictions those described in case of Privacy Policy URL.

6. Firebase Push Configuration

You can obtain the required configuration files in the Firebase console, either when you add the respective Android and iOS app information, or later via the Project Settings screen. The files are in .plist (iOS) and .json (Android) format.

Production and Integration Flavors

As the app flavors share the same app identifier, we recommend using the same Firebase project for both flavors. Nevis "duplicates" the config files for the respective app flavors integration and production.

There may be scenarios where you might not want to use the same Firebase project for both flavors, and thus using a different Firebase configuration (project) for the integration and production system. In these cases, Nevis requires the push configuration for each of the Firebase projects respectively. The push configurations still need to use the same app identifier in this scenario.

7a. Backend URL

The Backend URL of the environment integrating the Nevis Mobile Authentication Solution.

Production and Integration Flavors

Backend URLs in configuration are processed as URI Templates (RFC6570) with the following restrictions:

• Only Level 1 URI Templates are supported.
• Only the domain variable is supported for base URLs. This parameter is replaced with a domain/host name.
• The value that is used as domain/host name is the domain of the server provided during the first successful out-of-band registration.
• Once a successful registration is completed, the value of the Backend URL cannot be modified.
• The allowed domain values can be restricted using the Domain whitelist configuration.

7b. Domain whitelist

The Backend URL can be parametrized using the domain variable. The domains allowed can (and should) be restricted using the Domain whitelist. The Domain whitelist allows using wildcards.

Example 1

Backend URL: https://{domain}/_app

Domain whitelist: [integrationserver.mycompany.com, productionserver.mycompany.com]

The first element in the Domain whitelist is used as default domain. Only integrationserver.company.com and productionserver.mycompany.com is accepted by the application. When the user scans a QR code generated in server productionserver.mycompany.com, the resulting Backend URL is https://productionserver.mycompany.com/_app.

Example 2

Backend URL: https://{domain}/_app

Domain whitelist: [integrationserver.mycompany.com, *.mycompany.com]

The first element in the Domain whitelist is used as default domain. Only servers under mycompany.com are accepted (see the wildcard in the second element of the Domain whitelist). When the user scans a QR code generated in server productionserver.mycompany.com, the resulting Backend URL is https://productionserver.mycompany.com/_app.

Example 3

Backend URL: https://myserver.mycompany.com/_app

Domain whitelist: []

The application only accepts operations from myserver.mycompany.com.

8. Success Screen Countdown

When the Access App is called from another application to perform a registration, authentication or transaction confirmation, and the operation finishes successfully, the Access App will display a screen informing the user that the operation finished. By default, this screen will be displayed for 5 seconds before navigating automatically to the application specified using x-callback-url or, in the case of Android if no x-callback-url was specified, returning to the invoking application. The remaining time before navigation is displayed as a countdown in the button present in the screen.

You can modify this default value to increase or decrease the time before returning automatically. If 1 or 2 is specified, no button will be displayed in the success confirmation screen. If 0 is specified, no success confirmation screen will be displayed, no vibration nor sound will be played, and the Access App will return immediately.

Note that in the case of error, the error screen will always be displayed and the user must click on the button in the error screen to return from the Access App.

9. Allow Class 2 Biometric Sensors (Android Only)

The Android Access App uses Class 3 (strong) biometric sensors with the biometric authenticator. Most fingerprint sensors are Class 3, but currently only the Google Pixel mobile phones have Class 3 face recognition sensors.

Optionally you can allow using Class 2 (weak) biometric sensors. Some Samsung devices come with Class 2 face and iris recognition sensors. However, Class 2 sensors are less secure than Class 3 sensors. Moreover, if a Class 2 sensor is used, the FIDO UAF credentials are not protected requiring user authentication by the operating system.

Because of the reduced security, this feature must be enabled with care: this is a trade-off between convenience (support face recognition in more devices) and security.

caution

The value of this parameter only affects new registrations. For example, if a user with a Samsung 21 registered a biometric authenticator using an application that does not allow Class 2 sensors, upgrading to an application that does allow them will not enable face recognition for that user.

10. Biometric Authentication Passcode Fallback

The Access App can be configured so that Biometric Authentication Passcode Fallback option is enabled allowing the end user to use the device passcode as alternative to biometric authentication.

caution

Changing the state of this option will effect ONLY the NEW registrations.

11. Biometric Authentication Passcode Fallback

The Access App will by default remove biometric authenticators on new OS biometrics. As soon as the biometric information in the operating system changes (for example adding or removing a fingerprint), the biometric authenticators are removed leading to higher security. This feature can be disabled.

12. PIN Minimum and Maximum Length

The Access App can be configured to define which is the minimum and maximum allowed length of the PIN. If the user provides a shorter or longer PIN when defining or changing it, the Access App will display an error. This will affect only new PIN registrations or PIN value modifications, existing registered PINs that are not conform to the configured length can still be used to authenticate.

By default, the Access App requires a PIN of 6 digits (that is, the PIN minimum and maximum length are 6).

caution

If you specify something different than 6 for the PIN minimum of maximum lengths, you must update accordingly the contents of the following properties in the localizations file:

• pin_enrollment_screen_format
• pin_enrollment_screen_error_pin_format
• pin_change_screen_format

Look and Feel

For customizing the look and feel of the app, Nevis provides you access to Figma, an onlinegraphics editor. This tool guides you through the app customization while showing you directly what the end result looks like. Additionally, it helps to create the screenshots for the app store listings for both the iOS App Store and the Google Play Store.

Figma allows you to customize the:

• app icons,
• app background image,
• app colors, and
• app elements and in-app icons.

To get access to our Figma customization template, provide an email address.

Custom Fonts in Figma

Using custom fonts in Figma is not supported at the moment. However the Nevis Access App supports using custom fonts. Contact us if you would like to use a custom font in the Access App.

Localizations

Localizations file

Nevis supplies standard translations of all app messages. If custom translations are desired, Nevis provides a localizations.csv file to adjust the text and translations to your needs. No changes are necessary if the provided translations and languages meet your requirements.

You can obtain the latest translations file from our public repository. The release tags indicate a specific, released Access App version - for example releases/2.6.x. The next tag indicates the localizations.csv file for the next unreleased Access App version.

Monitoring

We recommend using GitHub's notification feature to get notified when a new translations.csv file becomes available.

Languages

Default translations are provided in the following five languages:

• English
• German
• French
• Italian
• Simplified Chinese

info

In case no specific, custom values are defined (per translation key), the default translations will be used. This means when providing custom translations, only changed translation key-value entries must be supplied.

Format of the .csv file

The first line contains the list of supported languages, every other line contains a translation key with the values for the given language.

Placeholders

The provided translations contain the following placeholders: <app_name>. During the application build, the placeholder is replaced with the value provided as App Name, see the table Required technical information.

How to remove a supported language

If no modifications of the translations themselves are needed, a localizations.csv only containing the first line, listing only the needed language keys suffices. In case there are customizations necessary in any translations, only provide the translations in the needed languages.

Example: removing Chinese(zh) as supported language

change first line from:
Key,en,de,fr,it,zh
to:
Key,en,de,fr,it

How to add a new language

Duplicate the localizations.csv file and extend the first line with the needed language(s). Also add the translations for all the lines below.

Example: add Spanish(es) as supported language

Key,en,de,fr,it,zh,sp
home_screen_title,...
home_screen_scan,...
...

Submission

To trigger the creation and delivery of the Access App, submit the following items to Nevis:

• The required technical information, see the table Required technical information.
• The localizations.csv file, in case of modifications.

Access App Delivery

Responsible: Nevis

Nevis delivers two separate flavors of the Access App: the integration and production flavors.

• The production flavor represents the application package to be distributed to end users, either publicly to the app store or Google Play Store, or internally to employees. In the case of Android, the application is delivered as Android App Bundle to be published to the Google Play Store and also for convenience as an APK, to be installed directly in mobile phones for testing, or to distribute and test the application using play stores other than the Google Play Store. In addition, non-Google play stores such as Chinese app stores do not support the Android App Bundle (.aab) format. In these cases, use the APK format.
• The integration flavor can be used for testing before releasing the app to production. While being visually identical to the productionflavor, it uses a different configuration that allows the application to communicate with an integration (or staging) backend. In addition to that, this flavor logs messages that can be useful to debug errors. Be aware that although app logs are in clear text, the SDK-generated log entries are still obfuscated. However, the generated entries can be used for issue analysis by Nevis.

Publication

The delivered applications must be signed before they can be published to an app store. See the Finalization section for further information.

Finalization

Responsible: Partner and customer

You cannot just publish the delivered artifacts to the app stores as delivered. Since you, the customer, are responsible for the app distribution, sign the applications with your own certificates and profiles.

info

The artifacts are shipped with the -unsigned suffix which indicates the signing is required, as unsigned apps cannot be installed on a mobile device.

For a description of the steps that are required to sign the app per platform, refer to Prepare Android publication or Prepare iOS Publication.

Distribution

Responsible: Partner and customer

The partner/customer is responsible for distributing the application to its end users. Different types of distribution are possible:

• Ad hoc distribution of the integration version, to be tested internally on specific devices.
• App store distribution of the productionversion, to the app store or Google Play Store.
• In-house distribution of the integration or production version, to employees.

App signing

Ensure that the signing certificate used for app signing exists for the whole lifetime of the app. An app signed with a different signing certificate can not be uploaded to the play store as an app update.

To distribute the application, the customer needs to have its own Apple Developer account and/or Google Play account. Customers are also responsible for managing the app store and Google Play information like screenshots (from Figma), app descriptions or metadata.