Skip to main content
Version: 4.6.x.x RR (Android, iOS) / 4.7.x.x RR (Flutter) / 5.x.x.x RR (React Native)

Configuration

Using the Configuration java, swift, objc, flutter, react native interface, you define the server and endpoints the SDK has to use to do authentication. You can also specify network timeouts.

Authentication Cloud backend​

If your application is using the Nevis Authentication Cloud as backend, the SDK offers a convenience interface for each platform:

  • Configuration.AuthCloudBuilder for java
  • Configuration(authCloudHostname:::) for swift
  • -[NMAConfiguration initWithAuthCloudHostname:] for objc
  • Configuration.authCloudBuilder for flutter
  • Configuration.authCloudBuilder for react native

With these interfaces, you only need to provide the hostname of your cloud environment ($instance.mauth.nevis.cloud).

Configuration in AuthCloud
loading...

Identity Suite backend​

For those cases where your application interacts with an Identity Suite deployment configured with default Admin 4 pattern, the SDK offers a convenience interface for each platform:

  • Configuration.Admin4PatternBuilder for java
  • Configuration(idSuiteHostname:::) for swift
  • -[NMAConfiguration initWithIdSuiteHostname:] for objc
  • Configuration.admin4PatternBuilder for flutter
  • Configuration.admin4PatternBuilder for react native

These initializers allow you to specify the relative paths for each of the endpoints required by the SDK.

Configuration on Identity Suite
loading...

Custom backend​

For those cases where custom endpoint paths are needed, use the generic initializers to obtain a Configuration object:

  • Configuration.Builder for java
  • Configuration(baseUrl:) for swift
  • -[NMAConfiguration initWithBaseUrl:] for objc
  • Configuration.builder for flutter
  • Configuration.builder for react native

App extension configuration​

This is iOS only and applies when the SDK runs inside an app extension, reading the data of its containing application.

  • Configuration.AppExtension(keychainAccessGroup:applicationIdentifier:) swift, objc is supplied as the appExtension: parameter of the Configuration initializers.
  • NMAAppExtension objc is supplied via the NMAConfiguration convenience initializers.

The keychainAccessGroup is the containing application's default keychain access group, and the applicationIdentifier is the containing application's bundle identifier.

App extension configuration
loading...

See iOS App Extensions for prerequisites, entitlements and troubleshooting. This API is experimental and requires iOS SDK 4.6.0 or later.

Facet ID​

The facet ID of your application has to match the list of allowed facets stored provided by the facet service of the backend.

Common issue

The most common developer issue when integrating and testing the SDK is a mismatch between the client and backend facet IDs, specifically for applications running on the Android platform.

Always ensure that your backend facet ID configuration matches the client one.

The backend HTTP API serving the facets must be unprotected according to the UAF 1.1 specification. If you know the correct URL, you will be able to quickly verify the backends facets configuration.

  • Nevis Authentication Cloud: https://<your-cloud-instance>.mauth.nevis.cloud/_app/uaf/1.1/facets
  • On-Premise: https://<your-domain>/nevisfido/uaf/1.1/facets (This can differ according to configuration)

For backend configuration instructions, see one of the following documents:

The format of the facet ID differs between platforms:

Android facet ID​

According to the FIDO UAF 1.1 Specifications, the facet ID on Android should follow the android:apk-key-hash:HASH_VALUE format where the HASH_VALUE is Base64 encoded SHA-256 hash of the APK signing certificate.

For example android:apk-key-hash:z7Xkw62dAn/Bue3mKpYrOZ9zSPC7b4mbgzJmdZEDO5w.

danger

If you modify the certificate used to sign your application, the value of the facet ID changes. So, a change of the certificate implies the need to recalculate the facet ID again, and reconfiguring the server with the new facet ID.

Using Play App Signing​

If Google Play Store Play App Signing is used, Google will sign your application with a certificate that is not accessible.

In this case, to calculate the facet ID, include the facet ID calculating code in your application, publish it in Google Play (for example in an internal test track), and obtain the facet ID when running the application (for instance including it in a debug line).

As long as the certificate used by Google remains the same, the facet ID will not change. So, once the facet ID is obtained, you can remove the facet ID calculating code from your application.

Calculating the facet ID inside a mobile application​

The following code returns the facet ID when executed from inside the application:

Calculate Facet ID
loading...

Calculating facet ID using keytool command-line​

You can calculate the hash using the following command:

keytool -keystore <path-to-apk-signing-keystore> \
-alias <alias-of-entry> \
-exportcert -storepass <keystore-password> 2> /dev/null | \
openssl sha256 -binary | \
openssl base64| \
sed 's/=//g'

Signing Certificate Change​

When you change the certificate used to sign your application, the facet ID in the server must be updated with the new facet ID calculated with the new certificate.

Note that in the case of a certificate update (also known as rotation), if your application must support Android API 27 or lower, you must keep the facet ID corresponding to the original (old) certificate in the server configuration.

iOS facet ID​

In the case of an iOS application, the format of the facet ID is ios:bundle-id:<ios-bundle-id-of-app>.

For example ios:bundle-id:ch.nevis.accessapp

Inside an app extension, the facet ID is derived from the bundle identifier of the configured containing application. As a result, the backend facet list needs only the containing application's ios:bundle-id: entry, not a separate one for the extension.

Flutter facet ID​

In the case of a Flutter application, both Android and iOS facet IDs are needed. Read the chapters above on how you calculate them.

React Native facet ID​

In the case of a React Native application, both Android and iOS facet IDs are needed. Read the chapters above on how you calculate them.

Wildcard Facet IDs​

Nevis Mobile Authentication supports the usage of wildcard facet IDs for development purposes.

Configuring the backend with wildcard facet IDs will allow you to develop your app without having to consider Android signing certificate or iOS bundle identifiers at the early development stage. Simply adding the wildcard entries to the backend facet ID configuration will allow your app to "pass" the facet validation regardless of the real facet ID your app would have.

Wildcard Facet ID example

android:apk-key-hash:*
ios:bundle-id:*

Debug SDK flavor only

Only the debug SDK flavor supports wildcard facet IDs. The release flavor does not allow them, calculate and use non-wildcard facet IDs as described above when using the release flavor.

Last updated on