Getting Started

Requirements

This section describes the requirements to be able to use the SDK inside a mobile application.

  • Minimum supported OS version is iOS 12
  • Xcode 15.0.1 is required; this includes Swift 5.9

Flavors

To satisfy customers with the highest security requirements, the Nevis Mobile Authentication SDK is hardened with state-of-the-art protection mechanisms. Due to these restrictive protection mechanisms, the SDK is available in two build flavors:

  • release flavor: used for production purpose, where all protection mechanisms are activated. This is the only build flavor which is allowed to be used in a production environment.
  • debug flavor: used during the development phase of the mobile application where only a subset of the protection mechanisms are available. The simulator architecture is also included for convenience. > ⚠️ WARNING: It is PROHIBITED to use the debug flavor in a production environment.

Installation

To integrate the Nevis Mobile Authentication SDK for iOS into your application:

  1. Rename the framework as follows.

    nevis-mobile-authentication-sdk-ios-debug.xcframework     ------>   NevisMobileAuthentication.xcframework
    nevis-mobile-authentication-sdk-ios-release.xcframework   ------>   NevisMobileAuthentication.xcframework
    
  2. Move or copy the framework to your project files.

  3. Open your application’s Xcode project or workspace.

  4. Drag and drop the framework into your project.

  5. Make sure it is listed under General > Linked Frameworks and Libraries.

  6. Set ENABLE_BITCODE to No as the Nevis Mobile Authentication SDK doesn’t contain bitcode.

Modify your application’s Info.plist file to add a description for the NSFaceIDUsageDescription key. Ideally, this value should be localized.

<key>NSFaceIDUsageDescription</key>
<string>Enabling Face ID allows you to use the Face Recognition authenticator.</string>

The Basics

Configuration

First, make sure to import the framework by adding the following line to your code:

import NevisMobileAuthentication

The NevisAuthenticationSession class represents the entry point to the SDK. Your app should generally create one NevisAuthenticationSession instance, by passing a configuration that specifies the SDK behavior. The configuration defines the URLs used to perform operations with a NEVIS Mobile Authentication backend (see NevisAuthenticationSession.Configuration). In case the instance creation failed, the instantiation throws NevisError which represents an underlying SdkInitializationError (See SDK Initialization Errors).

let configuration = NevisAuthenticationSession.Configuration(
    userInteractionTimeoutInSeconds: 240,
    baseURL: URL(string: "https://host.ch")!,
    registrationRequestPath: "/nevisfido/uaf/1.1/request/registration/",
    registrationResponsePath: "/nevisfido/uaf/1.1/registration/",
    deregistrationRequestPath: "/nevisfido/uaf/1.1/request/deregistration/",
    authenticationRequestPath: "/auth/fidouaf",
    authenticationResponsePath: "/auth/fidouaf/authenticationresponse/",
    authenticationMaxRetries: 3,
    authenticationRetryIntervalInSeconds: 1.0,
    dispatchTargetResourcePath: "/nevisfido/token/dispatch/targets/",
    pinningPolicy: .pinCertificates(hashes: ["<value>"]),
    timeoutIntervalForNetworkRequestInSeconds: 60.0
)

do {
    let session = try NevisAuthenticationSession(configuration: configuration)
}
catch {
    let sdkInitializationError = (error as? NevisError)?.underlying as? SdkInitializationError
}

Note
The configuration type conforms to Codable in order to be easily decoded from JSON or a property list. Make sure to use the proper representation for types like URL or NevisServerPinningPolicy.

Using a User Interaction Delegate

The operations performed by the NevisAuthenticationSession, use a separate delegate that lets you deal with user interaction and provide information when various events occur. For information about how to implement such a user interaction delegate, see User Interaction Delegation.

let session = try? NevisAuthenticationSession(configuration: configuration)
let uiDelegate: UserInteractionDelegate = ...

session.register(username: Username, dispatchTargetConfiguration: nil, authorizationProvider: nil, userInteractionDelegate: uiDelegate, completion) { _ in }

Asynchronicity

The API is highly asynchronous; it returns data to your app by calling a completion handler when an operation finishes successfully or with an error. The NevisAuthenticationSession performs operations on its own private queue. By default, completion handlers are executed on the main queue, but you can pass the queue of your choice to the NevisAuthenticationSession object; this queue will then be used by the NEVIS authentication session.

let queue = DispatchQueue(label: "completion.queue")
let session = try? NevisAuthenticationSession(configuration: configuration, delegate: delegate, completionQueue: queue)

Accessing Protected HTTP APIs

In order to use the SDK for accessing protected backend APIs, please follow chapter Accessing Protected HTTP APIs

Out-of-Band Operations Prerequisites

Push Notifications using Google Firebase Cloud Messaging

In order to receive out-of-band messages, the application is responsible for registering itself as a dispatch target with the NEVIS Mobile Authentication backend, including a token issued by Firebase. The application is as well responsible for updating this dispatch target when a new token is available. Google Firebase Cloud Messaging (FCM) is used as a cross-platform messaging solution and the application must be configured accordingly.

For information about how to perform out-of-band operations, see Operations.

FIDO Authenticators

The SDK exposes the following first factor bound authenticators:

  • application PIN authenticator (F1D0#1001)
  • fingerprint authenticator based on Touch ID (F1D0#1002)
  • face recognition authenticator based on Face ID (F1D0#1003)

Note
All authenticators require a device passcode to be set, otherwise they won’t be available for FIDO operations. Disabling the device passcode will also imply all valid registrations to be removed.

From version 2.0.0, all biometric authenticators are configured to enable device passcode fallback option.
In case of failing biometric verification the device offers an alternative (fallback) way for verification to the user, which is entering the device passcode.
This feature will only be available for registrations made with >= 2.0.0 version.
Enabling this feature for existing registrations made with < 2.0.0 is not possible. To be able to use this feature the aforementioned registrations have to be deregistered, and new ones have to be created using >= 2.0.0 version.

The relying party can specify a policy for supporting various FIDO Authenticator types. Since the FIDO UAF Client will only register existing authenticators in accordance with that policy, make sure that the NEVIS Mobile Authentication backend defines the proper metadata.

Note
When using a non-system authenticator (like application PIN authenticator), and this authenticator is already successfully enrolled and/or registered, the SDK doesn’t remove the enrollment upon a contingent de-installation of the host application. Therefore it is the responsibility of the host application to clean up the superfluous stored information about enrolled/registered of these authenticators by removing all keychain items.

It is also the responsibility of the host application to check the existence of the enrolled authenticators when the application is entering foreground and act accordingly. This might be necessary after a contingent disabling of the device passcode which causes all registered authenticator to be invalidated.

Logging and analytics

HTTP User-Agent based Logging and Analytics

The Nevis Mobile Authentication SDK uses a custom HTTP User-Agent to report client information to the backend. This information can be used to gather statistical information about app/SDK usage but also to block access for specific devices or app/SDK versions.

Information in header

The following information is contained in the header:

  1. Name of the SDK (fixed to NMASDK)
  2. SDK version including build number.
  3. Mobile device model
  4. Operating System
  5. OS Version
  6. Application The Bundle ID
  7. Application version including build number.

Information Order

The header is using the following information order and format:

<1>/<2> (<3>; <4> <5>) <6>/<7>

Example User-Agent Header

NMASDK/1.6.0.5 (iPhone12,8; iPhoneOS 14.0) ch.nevis.accessapp/1.6.0.5

Parsing

The following regular expression can be used to easily extract individual parts of the User-Agent header:

User-Agent parsing RegEx

^([\w\d\s]*)\/([\d.]*)\s\((.*);\s(.*)\)\s(.*)\/(.*)

Internationalization

The SDK provides certain features which require user-facing texts to be displayed by the implementing application. These texts are not localized, and only provided in English. An example for this is the PIN brute force attack prevention mechanism.

To provide localizations for these texts is in the responsibility of the mobile application. The localization can be achieved by providing the keys for the translations and their values in the appropriate Localizable.strings file in the project of the application which implements the SDK.

If these keys are not provided in the application, the default English value provided by the SDK are used.

The following keys and values are offered by the SDK:

Key Value
application_pin_authenticator_title PIN
application_pin_authenticator_description Authentication using a PIN
application_pin_authenticator_enroll_user_action Set a PIN
application_pin_authenticator_change_credential_action Change PIN
fingerprint_authenticator_title Touch ID
fingerprint_authenticator_description Authentication based on Touch ID
face_recognition_authenticator_title Face ID
face_recognition_authenticator_description Authentication based on Face ID.
device_passcode_authenticator_title Passcode Authenticator
device_passcode_authenticator_description An authenticator based on the device passcode used to authenticate to a NEVIS relying party server.
fingerprint_authenticator_register_operation_prompt_message Provide your fingerprint to register for Mobile Authentication
face_recognition_authenticator_register_operation_prompt_message Use Face ID to register for Mobile Authentication
fingerprint_authenticator_authenticate_operation_prompt_message Authenticate with your fingerprint
face_recognition_authenticator_authenticate_operation_prompt_message Authenticate using Face ID
pin_protection_status_description_retries_without_cooldown Invalid PIN. You have %d tries left.
pin_protection_status_description_retries_with_cooldown Invalid PIN. You have %d tries left.\nPlease retry in %.0f seconds.
pin_protection_status_description_last_retry_with_cooldown Invalid PIN. You have %d try left.\nPlease retry in %.0f seconds.\nAfter that your PIN will be blocked.
pin_protection_status_description_last_retry_without_cooldown Invalid PIN. You have %d try left.\nAfter that your PIN will be blocked.
unknown_authenticator_title Unknown Authenticator
unknown_authenticator_description