iOS SDK Migration from 3.0.x to 3.1.x

Structs eliminated from user interaction contexts

Motivation

In the version 3.0.x, the context of the user interactions were provided as structs. As these structs were not created on the application level, the initializers of the structs were not public. This could cause difficulties for you in case of unit tests on the code parts implementing the user interactions from the SDK.

Solution

All affected structs in user interaction contexts (including their properties) are transformed to protocols. Namely the followings:

• AccountSelectionContext_{swift, objc}
• AuthenticatorSelectionContext_{swift, objc}
• PinEnrollmentContext_{swift, objc}
• BiometricUserVerificationContext_{swift, objc}
• PinUserVerificationContext_{swift, objc}
• Account_{swift, objc}
• Authenticator_{swift, objc}
• RegistrationInfo_{swift, objc}

Benefit

You can now mock protocols up on the application level, and conveniently simulate the behavior of the SDK when writing unit tests.

Side effects

As a side effect, the API has to provide Arrays instead of Sets for the protocols from now on.

LocalData

public protocol LocalData {
  var accounts: [any Account] { get }
  var authenticators: [any Authenticator] { get }
  ...
}

Authenticator

public protocol Authenticator: Encodable, Equatable {
  ...
  var registration: (any RegistrationInfo)? { get }
  var userEnrollment: (any UserEnrollment)? { get }
  ...
}

Another side effect is that the AAIDs of the authenticators needed to be moved out from the Authenticator protocol to a new enum called AuthenticatorAaid_{swift, objc}. The mapping is as follows:

Old static property	Swift enum case	Objective-C class
Authenticator.pinAuthenticatorAaid	AuthenticatorAaid.Pin	NMAAuthenticatorAaid.pin
Authenticator.fingerprintAuthenticatorAaid	AuthenticatorAaid.Fingerprint	NMAAuthenticatorAaid.fingerprint
Authenticator.faceRecognitionAuthenticatorAaid	AuthenticatorAaid.FaceRecognition	NMAAuthenticatorAaid.faceRecognition

iOS SDK Migration from 2.x to 3.x

Overview

The iOS Mobile SDK 3.x is not compatible with previous versions of the SDK, thus it is not possible to do an upgrade of the SDK version without major code changes. This chapter provides some tips on migrating the code from the 2.x versions of the SDK to version 3.x.

Existing Credentials

Existing user credentials/registrations will continue to work after migrating the SDK from 2.x to 3.x.

SDK configuration

NevisAuthenticationSession.Configuration is extracted and renamed to Configuration.

Configuration has a new initializer, which can be used when your application interacts with a backend relying on the Nevis Authentication Cloud.

See Configuration for more information.

Certificate pinning

The certificate pinning configuration is removed in 3.x.

SDK initialization

NevisAuthenticationSession is renamed to MobileAuthenticationClient.

To create a MobileAuthenticationClient, a MobileAuthenticationClientInitializer is used, instead of NevisAuthenticationSession(configuration:).

See Initialization for more information.

Operations

The following protocols are replaced by the Operation object.

• NevisOperations
• NevisOperationsMultiAccount
• InBandOperations
• InBandOperationsMultiAccount
• OutOfBandOperations
• OutOfBandOperationsMultiAccount

Operations returns operation objects that use a builder pattern to provide parameters. Once the operation is built, the execute method must be invoked to start the operation.

The MobileAuthenticationClient.operations method returns an Operations object.

User interaction delegate

The UserInteractionDelegate is split into different interfaces that the developer must implement. This leads to a clearer separation of implementation code. These interfaces must be provided to the registration and authentication operations when they are being built.

The following table shows the user interaction delegate methods in 2.x and their equivalents in 3.x.

2.x	3.x
UserInteractionDelegate.selectAuthenticator	AuthenticatorSelector.selectAuthenticator
UserInteractionDelegate.verifyUser	PinUserVerifier.verifyPin BiometricUserVerifier.verifyBiometric
AuthenticationUserInteractionDelegate.selectAccount	AccountSelector.selectAccount

Registration

In 2.x the PIN enrollment and the registration were two separate operations. In 3.x the PIN enrollment is done during registration. When creating the registration operation, if a PIN authenticator can be registered, provide a PinEnroller.

See Registration for more information.

Authentication

In 2.x the username was an optional parameter. In 3.x the username of the account to be used to authenticate must be provided when building the Authentication object.

See Authentication for more information.

Deregistration

Both the AAID of the authenticator and the username of the account to be deregistered must be provided when building the Deregistration object. The DeregistrationUserInteractionDelegate defined in 2.x is removed in 3.x.

See Deregistration for more information.

Out-of-band

In 2.x, when executing an out-of-band operation, all the parameters, for both registration and authentication, are provided when running OutOfBandOperations.process. So, when triggering the operation, the 2.x API asks for parameters that might not be relevant for the operation:

• The DispatchTarget is not relevant for authentication.
• The account selection part (managed through the AccountUserInteractionDelegate.selectAccount method) is not relevant for registration.

This is why the out-of-band operation is chained in 3.x:

1. The user starts the out-of-band operation creating an OutOfBandOperation object.
2. An OutOfBandPayload is provided to the OutOfBandOperation.
3. Three callbacks are defined:
   1. A callback to handle the potential error that can occur when managing the OutOfBandPayload.
   2. A callback invoked if the operation is a registration operation.
   3. A callback invoked if the operation is an authentication operation.

The operation callbacks receive either an OutOfBandRegistration or an OutOfBandAuthentication object. These objects are handled similarly to the Registration and the Authentication objects.

See Out of Band Registration and Out of Band Authentication for more information.

Instantiating OutOfBandPayload

In 2.x the OutOfBandPayload struct was directly used to initialize itself from a JSON object by using OutOfBandPayload(from:). In 3.x the OutOfBandPayloadDecode operation is used to fetch the OutOfBandPayload.

See Obtain an out-of-band payload for more information.

Open settings

The open settings operations are replaced with PinEnroller and with PinChange.

The PinEnroller is in charge of defining the PIN. The PIN enrollment is now integrated into the registration operation.

The PinChange allows you to modify the PIN that was defined during registration.

See PIN Change for more information.

Errors

From 3.x, the SDK throws fatal errors when the invoking code dos not conform with the constraints imposed by the SDK. For example, if there is a missing parameter when building an operation.

The NevisErrors provided through the Result values of the completion handlers of each operation, are replaced by the .onError() methods. The closures provided through these methods are taking specific errors, which correspond to the operations.

For example, Registration.onError receives an OperationError.

The following table shows the errors in 2.x and their equivalent errors in 3.x:

2.x	3.x
NevisError.failedSdkInitialization (SdkInitializationError)	InitializationError
NevisError.fidoError (FIDOError)	OperationError.FidoError
NevisError.networking	OperationError.NetworkError
NevisError.invalidDispatchTarget (DispatchTargetError)	DeviceInformationChangeError OutOfBandPayloadError AuthCloudApiError
NevisError.malformedNmaData	OutOfBandPayloadError.MalformedPayload AuthCloudApiError.MalformedPayload
NevisError.decryptingOutOfBandPayloadError	OutOfBandPayloadError.DecryptionError AuthCloudApiError.DecryptionError

Local data

LocalDataManager is LocalData from version 3.x.

DispatchTarget is renamed to DeviceInformation.

LocalData does not allow you to remove the DeviceInformation explicitly. When all the information for a given account is removed, either through deregistration or invoking LocalData.deleteAuthenticator, the associated DeviceInformation is removed automatically.

LocalData requires you to provide the username associated with the account when deleting authenticator information.

Known limitations

When migrating from a 2.x version of the SDK, guarantee that all the enrolled PINs are also registered. If this is not the case, the registration operation of the already enrolled PIN fails.

note

In this context, registered means that the PIN is not only defined or set, but also the FIDO UAF registration process has completed successfully, making the PIN authenticator usable in the client and storing the necessary information in the backend.

The following code snippet allows you to delete the enrolled PIN authenticators that are not registered:

iOS/Swift

Delete Enrolled but not Registered PINs

iOS/Objective-C

Delete Enrolled but not Registered PINs