Getting Started
- Requirements
- Flavors
- Installation
- The Basics
- Out-of-Band Operations Prerequisites
- FIDO Authenticators
- Logging and Analytics
- Internationalization
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:
Rename the framework as follows.
nevis-mobile-authentication-sdk-ios-debug.xcframework ------> NevisMobileAuthentication.xcframework nevis-mobile-authentication-sdk-ios-release.xcframework ------> NevisMobileAuthentication.xcframework
Move or copy the framework to your project files.
Open your application’s Xcode project or workspace.
Drag and drop the framework into your project.
Make sure it is listed under General > Linked Frameworks and Libraries.
Set
ENABLE_BITCODE
toNo
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 toCodable
in order to be easily decoded from JSON or a property list. Make sure to use the proper representation for types likeURL
orNevisServerPinningPolicy
.
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:
- Name of the SDK (fixed to NMASDK)
- SDK version including build number.
- Mobile device model
- Operating System
- OS Version
- Application The Bundle ID
- 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 |