Nevis Mobile Authentication SDK Flutter Example App

This repository contains the example app demonstrating how to use the Nevis Mobile Authentication SDK Flutter plugin in a Flutter app. 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 & 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.

Getting Started

Before you can actually start compiling and using the example applications 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 or later
• Xcode 15.x, including Swift 5.7 or later
• Android 6 or later, with API level 23 -or-
• Android 10 or later, with API level 29, for the biometric authenticator to work
• Gradle 8.4 or later
• Android Gradle Plugin com.android.tools.build:gradle 8.3.0 or later
• Kotlin Gradle Plugin org.jetbrains.kotlin:kotlin-gradle-plugin 1.8.22 or later
• Dart SDK 3.3.0 or later
• Java 17

Initialization

Open a terminal and run the flutter pub get command in the root directory to get the 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. Synchronize your android project 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

Run pod install in your iOS directory.

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",
     ...
  }
}

Change configuration

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

Note

Only build-time configuration change is supported.

To change the configuration open the getit_root.dart file which describes the dependency injection related configuration using the get_it dart package. The environment parameter should be changed to one of the values already mentioned.

Android Manifest XML

The example applications handle deep links those contain a valid dispatchTokenResponse query parameter of an out-of-band operation. The related configuration located in the AndroidManifest.xml for MainActivity with action android.intent.action.VIEW.

Deep links

Change the nevisaccess scheme value in the following intent-filter with the right scheme information of your environment.

<intent-filter>
    <action android:name="android.intent.action.VIEW" />

    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />

    <data android:scheme="nevisaccess" />
</intent-filter>

Note

For more information about deep links, visit the official Android guide.

Build

Now you're ready to build the example app by running:

flutter build ios --no-codesign

flutter build apk --debug

Run

In order to run the Flutter example app, you'll need a running emulator or simulator instance or a phone connected to your computer.

You start the application by running:

flutter run

Note

Running the app on an iOS device required codesign setup.

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.

Try it out

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

Check out our Quickstart Guide.

Used Components, Concepts

Nevis Mobile Authentication SDK Flutter Plugin

The most important component/dependency of the example application is the Nevis Mobile Authentication SDK Flutter Plugin. It provides the Flutter/Dart API for the native Nevis Mobile Authentication SDK implementations.

Flutter Bloc

Flutter Bloc is used to implement BLoC Design Pattern (Business Logic Component).

GetIt

GetIt Service Locator is used to ease accessing use-cases/providers/BLoCs from Flutter Views.

Integration Notes

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

• MobileAuthenticationClient initialization (which is the entry point to the SDK) is implemented in ClientProvider class.
• All SDK operation invocation is implemented in the corresponding use-case class in usecase folder.
• All SDK specific user interaction related interface implementation can be found in the interaction folder.

Initialization

The HomeBloc class is responsible for creating and initializing a MobileAuthenticationClient instance (which is the entry point to the SDK) by calling the init method of ClientProvider class. Later this MobileAuthenticationClient instance can be used to start the different operations, it is accessible as the client property of the ClientProvider class. The default implementation of ClientProvider is ClientProviderImpl, it is injected into all use-case, user interaction related interface implementation where it is needed.

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 AuthCloudApiRegisterUseCase class will be used by passing the enrollResponse response or an appLinkUri.

When the backend used by the application does not use the Nevis Authentication Cloud the RegistrationUseCase class will be used. If authorization is required by the backend to register, provide an AuthorizationProvider.
In the example app a CookieAuthorizationProvider is used from the Credentials object returned by the execute method of LoginUseCase. Behind the scenes it is created from the cookies obtained by the LoginDataSource class.
To see the whole process check LegacyLoginBloc implementation.

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 the OobProcessUseCase is used to start the out-of-band operation. Behind the scenes before calling the out-of-band operation OobPayloadDecodeUseCase is used to decode the OutOfBandPayload object from the received payload data.

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 AuthenticateUseCase 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 the OobProcessUseCase is used to start the out-of-band operation. Behind the scenes before calling the out-of-band operation OobPayloadDecodeUseCase is used to decode the OutOfBandPayload object from the received payload data.

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 a byte array with the information. In the example app it is handled in the AccountSelectorImpl class.

Deregistration

The DeregisterUseCase and DeregisterAllUseCase classes 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 the ChangePinUseCase 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 OobPayloadDecodeUseCase 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 and the token is implemented in the ChangeDeviceInformationUseCase class.

© 2024 made with ❤ by Nevis