Skip to main content
Version: 2.4.x.x

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:

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

The following diagram illustrates the ordering process.

Ordering process overview

These are the steps in more detail:

  1. After the decision for a branded Access App is taken, the customer together with the Nevis partner supplies the required information to Nevis.
  2. After Nevis received all information, the Access App instances arecreated and handed over for testing and verification.
  3. This also allows for further adjustments desired by the customer.
  4. After the final delivery, the customer is able to sign the Access App.
  5. 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

Technical information steps

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.

The mobile-only feature of the Access App requires

  • either a URI scheme, or
  • a domain different from the one supplied with the Backend URL.
Recommendation

We recommend using the URI scheme with x-callback-urls.

See Out-of-Band Operations Using Push, QR Code or Deep Links for additional detail.

caution

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

  1. Custom URI schemes for app navigation, using the bundle identifier. For example: com.mybusinessapp
  2. 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:

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 must 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”
danger

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.

5d. Certificate Pinning Policy for Privacy Policy & Help URLs

The intermediate certificates to be used to access the Privacy Policy and Help URLs. If the application performs certificate pinning, it is required to get the first intermediary server certificate of the chain, starting from the leaf.

info

We only recommend using certificate pinning in certain scenarios. Read the chapter Certificate Pinning Recommendations before you decide on pinning.

Privacy Policy Page Restrictions

If certificate pinning of the privacy policy and help URLs is enabled, all outgoing requests from the page are pinned as well. If the page contains third party resources from another domain they are not loaded.

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. Public Backend Certificate

caution

We recommend using certificate pinning in certain scenarios only. See the chapter Certificate Pinning Recommendations before you decide on pinning.

The intermediate certificates of the backend environment. If the application performs certificate pinning, it is required to get the first intermediary server certificate of the chain, starting from the leaf. If you use Let's Encrypt, the certificate information can be found here.

info

Configurations must be provided separately for the production and integration flavors.

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 app customization example

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

In case no specific, custom values are defined (per translation key), the default translations will be used. This means when providing custom translations, onlychanged 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.
caution

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.