Ordering an Access App
This document guides you through the process of ordering a branded Access App compatible with the Nevis Mobile Authentication Solution.
The process to order an Access App consists of the following steps:
The following diagram illustrates the ordering process.
These are the steps in more detail:
- After the decision for a branded Access App is taken, the customer together with the Nevis partner supplies the required information to Nevis.
- After Nevis received all information, the Access App instances are created and handed over for testing and verification. This also allows for further adjustments desired by the customer.
- After the final delivery, the customer is able to sign the Access App.
- The signed Access App is now ready for app store 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
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.
We recommend using app links instead of custom URIs.
When using custom URI scheme with x-callback-urls, its 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
- Custom URI schemes for app navigation, using the bundle identifier. For example:
com.mybusinessapp - HTTPS domains. For example:
https://mydomain.com
3. Configurable App Features
Some features of the Access App can be turned on or off based on customer requirements. This is limited to the following features:
- Forced Access App Update
- Multi-account
- Class 2 Authenticator support (Android only)
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
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”
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.
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.
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. 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.
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.
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.
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.csvfile to adjust the text and translations to your needs. No changes are necessary if the provided translations and languages meet your requirements.
Languages
Default translations are provided in the following five languages:
- English
- German
- French
- Italian
- Simplified Chinese
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.
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.
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.
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.
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.
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.