Nevis Mobile Authentication React Native Example Application

This repository contains the example app demonstrating how to use the Nevis Mobile Authentication Client SDK for React Native in a React Native application. The Nevis Mobile Authentication SDK allows you to integrate passwordless authentication to your existing mobile app, backed by FIDO UAF 1.1.

Some features demonstrated in this example app are:

• Registering with QR code (when using the old architecture, see note below) and app link URIs
• Simulating in-band authentication after registration
• Deregistering a registered account
• Changing the PIN of the PIN authenticator
• Changing the device information
• Using the SDK with the Authentication Cloud

Please note that the example app only demonstrates a subset of the SDK features. The main purpose is to demonstrate how the SDK can be used and not to cover all supported scenarios and use cases.

Note

QR code scanning in the example application is only available for the old architecture at the moment as we have not found any open source library that supports both old and new architecture. If you want to implement QR code scanning for the new architecture, evaluate plugin alternatives which support it.

Getting Started

Before you can actually start compiling and using the example application please ensure you have the following ready:

• An Authentication Cloud instance provided by Nevis.
• An access key to use with the Authentication Cloud.

Your development setup has to meet the following prerequisites:

• iOS 12.4 or later
• Xcode 14.x, including Swift 5.7
• Android 6 or later, with API level 23
• Android 10 or later, with API level 29, for the biometric authenticator to work
• Android 11 or later, with API level 30, for the device passcode authenticator to work
• Gradle 7.4 or later
• Android Gradle Plugin com.android.tools.build:gradle 7.4.2 or later
• Kotlin Gradle Plugin org.jetbrains.kotlin:kotlin-gradle-plugin 1.8.21 or later
• React Native 0.72.x

Initialization

First open a terminal and run the yarn command in the root directory to get the React Native dependencies.

Android

1. The Nevis Mobile Authentication Client SDK for Android is published as a GitHub package. In order to be able to download it a valid GitHub account and a Personal Access Token is needed. Please define these in one of the following ways:

   • as environment variables.
   • in gradle.properties in GRADLE_USER_HOME directory or in Gradle installation directory.

   GITHUB_USERNAME=<YOUR USERNAME>
   GITHUB_PERSONAL_ACCESS_TOKEN=<YOUR PERSONAL ACCESS TOKEN>

2. To choose between the Old and the new architecture, you have to set the newArchEnabled property to false or true respectively by either (Note that if you use the yarn scripts described in the Build & run section, this will be done automatically for the selected architecture via setting the environment variable):

   • Changing the corresponding line in android/gradle.properties
   • Setting the environment variable ORG_GRADLE_PROJECT_newArchEnabled=true

3. To set whether the Hermes JavaScript engine should be used or JavaScript Core, you have to set the hermesEnabled property to true or false respectively in android/gradle.properties.

4. Synchronize your android project with Gradle if opened in Android Studio.

[!WARNING] The package repository only exposes the debug flavor. To use the release flavor contact us on [email protected].

iOS

Native iOS dependencies of this project (including the Nevis Mobile Authentication Client SDK for iOS) are provided via Cocoapods. Please install all dependencies by running

• When using the new architecture:

RCT_NEW_ARCH_ENABLED=1 USE_FRAMEWORKS=static NO_FLIPPER=1 pod install

• When using the old architecture:

RCT_NEW_ARCH_ENABLED=0 pod install

Note that if you use the yarn scripts described in the Build & run section, this will be done automatically for the selected architecture.

Bitcode Support

As the native iOS SDK does not provide Bitcode support, the following post install step needs to be added to the Podfile:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['ENABLE_BITCODE'] = 'NO' # NMA SDK does not support Bitcode
    end
  end
end

Configuration

Before being able to use the example app with your Authentication Cloud instance, you'll need to update the configuration file with the right host information.

Edit the assets/config_authentication_cloud.json file and replace

• the host name information with your Authentication Cloud instance

{
  "login": {
    "loginRequestURL": "https://<YOUR INSTANCE>.mauth.nevis.cloud/_app/auth/pwd"
  },
  "sdk": {
    "hostname": "<YOUR INSTANCE>.mauth.nevis.cloud",
     ...
  }
}

Configuration Change

The example apps are supporting two kinds of configuration: authenticationCloud and identitySuite.

To change the configuration open the ConfigurationLoader.ts file which describes the App Environment that should be used. The _appEnvironment assignment should be changed in the constructor to one of the values already mentioned.

Due to the Fast Refresh feature of React Native, you can even change this while running the app, and after it is reloaded, you can start using the different environment without rebuilding the app (Note: this is only true when changing the TypeScript files and not native ones).

Build & run

Android

If you configured everything properly, you can run the app on an Android device or Emulator with the following yarn commands:

• Using the new architecture

yarn android:new

• Using the old architecture

yarn android:old

iOS

If you configured everything properly, you're ready to build and run the example app on an iOS device or Simulator with the following yarn commands:

• Using the new architecture

yarn ios:new

• Using the old architecture

yarn ios:old

Or by choosing Product > Run from Xcode, or by clicking the Run button in your project’s toolbar, similarly how you would run a native iOS application.

[!NOTE] Running the app on an iOS device requires codesign setup.

Try it out

Now that the React Native example app is up and running, it's time to try it out!

Check out our Quickstart Guide.

Troubleshooting

Not enough space on Android emulator

When the Android emulator has insufficient internal memory the installation may fail with the error:

android.os.ParcelableException: java.io.IOException: Requested internal only, but not enough space

The solution is to increase the internal memory. In Android Studio

• Open the Virtual Device Manager.
• Select the emulator which you want to make changes then click on the edit button associated to it.
• Click on Show Advanced Settings button to expose hidden things.
• Scroll down to the Memory and Storage section and increase the amount of Internal Storage.
• Finally, hit the Finish button to apply the changes. Reboot the Android emulator to ensure everything will work as expected.

Integration Notes

In this section you can find hints about how the Nevis Mobile Authentication SDK is integrated into the example app.

• All SDK invocations are implemented in the corresponding view model class.
• All SDK specific user interaction related protocol implementation can be found in the userInteraction folder.

Initialization

The HomeViewModel class is responsible for creating and initializing a MobileAuthenticationClient instance which is the entry point to the SDK. Later this instance can be used to start the different operations.

Registration

Before being able to authenticate using the Nevis Mobile Authentication SDK, go through the registration process. Depending on the use case, there are two types of registration: in-app registration and out-of-band registration.

In-app registration

If the application is using a backend using the Nevis Authentication Cloud, the AuthCloudApiRegistrationViewModel class will be used by passing the enrollment response or an appLinkUri.

When the backend used by the application does not use the Nevis Authentication Cloud the name of the user to be registered is passed to the UsernamePasswordLoginViewModel class. If authorization is required by the backend to register, provide an AuthorizationProvider. In the example app a CookieAuthorizationProvider is created from the cookies obtained by the login() function (see UsernamePasswordLoginViewModel).

Out-of-band registration

When the registration is initiated in another device or application, the information required to process the operation is transmitted through a QR code or a link. After the payload obtained from the QR code or the link is decoded the OutOfBandOperationHandler class starts the out-of-band operation.

Authentication

Using the authentication operation, you can verify the identity of the user using an already registered authenticator. Depending on the use case, there are two types of authentication: in-app authentication and out-of-band authentication.

In-app authentication

For the application to trigger the authentication, the name of the user is provided to the SelectAccountViewModel class.

Out-of-band authentication

When the authentication is initiated in another device or application, the information required to process the operation is transmitted through a QR code or a link. After the payload obtained from the QR code or the link is decoded the OutOfBandOperationHandler class starts the out-of-band operation.

Transaction confirmation

There are cases when specific information is to be presented to the user during the user verification process, known as transaction confirmation. The AuthenticatorSelectionContext and the AccountSelectionContext contain string with the information. In the example app it is handled in the AccountSelectorImpl class.

Deregistration

The HomeViewModel class is responsible for deregistering either a user or all of the registered users from the device.

Other operations

Change PIN

With the change PIN operation you can modify the PIN of a registered PIN authenticator for a given user. It is implemented in:

• in case of a single registered user see the HomeViewModel class.
• in case of multiple registered users see the SelectAccountViewModel class.

Decode out-of-band payload

Out-of-band operations occur when a message is delivered to the application through an alternate channel like a push notification, a QR code, or a deep link. With the help of the OutOfBandOperationHandler class the application can create an OutOfBandPayload either from a JSON or a Base64 URL encoded String. The OutOfBandPayload is then used to start an OutOfBandOperation, see chapters Out-of-Band Registration and Out-of-Band Authentication.

Change device information

During registration, the device information can be provided that contains the name identifying your device, and also the Firebase Cloud Messaging registration token. Updating both the name is implemented in the DeviceInformationChangeViewModel class.

Firebase Cloud Messaging is not supported in the example app.

License

Nevis Mobile Authentication Client SDK for React Native is released under a commercial license. See LICENSE for details.

© 2023 made with ❤ by Nevis