Skip to main content
Version: 3.0.x.x

Quickstart Guide

info

The quickstart guide is currently only available for iOS and Flutter.

This guide shows you how to configure the Nevis Mobile Authentication SDK example applications to compile and run them against the Nevis Customer Authentication Cloud.

What you need

Before you can start compiling and using the example applications, ensure you have the following ready:

  1. An Authentication Cloud instance provided by Nevis.
  2. An access key to use with the Authentication Cloud. You need to enter this later in the Authentication Cloud testing page.
  3. For Flutter the archives containing the Nevis Mobile Authentication SDK binaries, plugins and tools.
  4. The example application sources cloned from GitHub for the platforms you want to try out.

The Flutter plugin archive consists of the native SDKs as well as an SDK installer tool and is named nevis-mobile-authentication-sdk-installer-flutter-FLUTTER_PLUGIN_VERSION.tar.gz)

info

More detailed information regarding the Flutter plugin archive can be found in the installation section. However it is not necessary if you follow the example application README.md.

Getting the example application

For each of the supported platforms, we provide an example application as source code. See the public Nevis GitHub Repositories to obtain the example apps you need.

You can simply clone an app of your choosing by using the command line:

Declarative architecture example application
git clone https://github.com/nevissecurity/nevis-mobile-authentication-sdk-example-app-ios.git
Reactive architecture example application
git clone https://github.com/nevissecurity/nevis-mobile-authentication-sdk-example-app-ios-rx.git
Difference between the example applications

We provide two kinds of iOS example applications: a declarative and a reactive one.

  • The implementation of the declarative version is as simple as it can be. The MVP presentation pattern is used and all SDK invocations can be found in the corresponding presenter.
  • The reactive version follows the principles of Clean Architecture with the help of reactive technologies (RxSwift) and uses the MVVM pattern in the Presentation layer (RxSwift and RxCocoa).

Choose the application based on your needs and mobile engineering experience, the functionalities provided by the apps are the same.

Build and run

Follow the information provided in the README.md file of the example application to build and run it.

Using the example application

The example application is intended to be used in conjunction with the Authentication Cloud testing page.

  1. Visit https://<your-cloud-instance>.mauth.nevis.cloud/test.html.
  2. Expand the Setup & Tokens panel, and provide your access key in the Access Token text field.
  3. Click Check + Continue. The message "Provided token and URL are valid, you are good to go!" appears.

You are now ready to continue.

All example applications have a similar look and feel. They demonstrate some features provided by the SDK, which are all exposed through the app's main screen:

Example application main screen

Registered accounts

In the top left corner you see the number of registered accounts. The example application is able to handle multiple accounts.

tip

This information can be retrieved with the local data object

Read Qr code

You typically start with this, as it allows you to register one or more accounts and authenticators.

Registration

  1. Open the Authentication Cloud testing page and select the Enroll a new authenticator tab.
  2. Provide a username in the Username text field.
  3. After clicking Enroll, a QR code is displayed. Scan this QR code with the example application.
  4. The example app asks you to pick one of the authenticators available on the device. While the PIN authenticator is always available, and prompts you to enter a 6-digit number, the biometric authenticators depend on the device capabilities.

Authentication

After registering at least one account, you can do an out-of-band authentication by scanning an authentication QR code generated by Authentication Cloud testing page.

  1. Click the App/Push + SMS tab, enter a previously registered username and select QR Code in the Approval Method drop down menu
  2. Click Send Approval. A QR code is displayed.
  3. Scan the QR code with the previously built application and proceed with the authentication. The app confirms a successful authentication with a simple screen.
info

You need to fit the authentication QR code into the transparent square or it may not be recognised.

tip

In-band authenticate

The in-band authentication simulates what you typically do, when using the SDK to authenticate your application to access authentication protected backend APIs.

  1. After clicking the button, the example application prompts you to select the user to authenticate. Note that only the technical UUID identifier is shown, and not the username entered in the Authentication Cloud testing page.
  2. The application prompts you to select an authenticator the user previously registered.
  3. The application shows the authentication result after you provide the necessary authentication credentials, taht is, PIN or biometric information.

Deregister

Deregister demonstrates client-initiated account and authenticator deregistration. Note that the example application deregisters all accounts at once, and does not allow you to select a specific account or authenticator for deregistration.

tip

For more information, see Deregistration.

PIN change

Changing the PIN is only available if one account has a registered PIN authenticator. You need to enter the old and a new PIN to successfully change the PIN. As the PIN is never stored on the backend, this operation is local.

Additional details can be found in the operations PIN Change chapter.

Change device information

You can change the device name registered with the backend using this feature. This information is propagated to the backend.

For more information, see Device information change.

Authentication Cloud API registration

You can use the Autentication Cloud API registration to simulate the registration process using links. You typically use this for starting a registration process on the same device, letting the user click a link on the mobile browser or inside your custom application.

  1. Open the Authentication Cloud testing page, and select the Enroll a new authenticator tab.

  2. Provide a username in the Username textbox.

  3. After clicking Enroll, you have two options to continue:

    1. Copy and paste the JSON enrollment response into the Enroll response text field in the example application.
    2. Copy the link of the Send to Access App button into the App Link Uri text field in the example application
  4. Push ok to select an authenticator for enrollment, and complete the process.

For more information, see Out-of-band registration.

In-band registration

info

Performing in-band registration is only available for the Identity Suite, as Authentication Cloud does not support the scenario.

Enter an existing username and password to start the in-band registration process. After logging in with existing credentials, you are prompted to select an authenticator for registering mobile authentication credentials.

For more information, see On-premise in-app registration.