Android SDK migration from 2.x to 3.x

Overview

The Android 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 and registrations continue to work after migrating the SDK from 2.x to 3.x.

SDK configuration

SdkConfiguration is renamed to Configuration.

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

See the Configuration chapter for more information.

Certificate pinning

The certificate pinning configuration is removed in 3.x.

SDK initialization

Sdk is renamed to MobileAuthenticationClient.

To create a MobileAuthenticationClient, a MobileAuthenticationClientInitializer is used, instead of an Sdk.Builder.

See the Initialization chapter for more information.

Operations

FidoUafOperations and OutOfBandOperation, are replaced by the Operations object. 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 which 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 FingerprintUserVerifier.verifyFingerprint
UserInteractionDelegate.onValidCredentialsProvided	PinUserVerifier.onValidCredentialsProvided BiometricUserVerifier.onValidCredentialsProvided FingerprintUserVerifier.onValidCredentialsProvided
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.

JSON Mapper

In 2.x, the JsonMapper interface was used to obtain an OutOfBandPayload object from a JSON String. In 3.x, JsonMapper is replaced with the OutOfBandPayloadDecode interface.

See Out-of-Band Payload Decode for more information.

Open settings

The open settings operations are replaced with PinEnroller and PinChange.

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

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

See PIN Change for more information.

Errors

The SDK no longer throws checked exceptions. Runtime exceptions are thrown, when the invoking code does not conform with the constraints imposed by the SDK. For example, if there is a missing parameter when building an operation.

The onOperationFailed methods of the service delegates (RegistrationServiceDelegate, AuthenticationServiceDelegate, etc.) are replaced by the Consumer objects that take error objects. These Consumer objects are provided during the build of the operation object, for example in Registration.onError.

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

2.x	3.x
SdkConfigurationException	InitializationError
AuthenticatorException	OperationError
ConfigurationFidoUafException	OperationError.DeviceProtectionError
FidoUafException	OperationError
NetworkFidoUafException	OperationError.NetworkError
ServerResponseException	OperationError
ConfigurationOutOfBandException	OutOfBandOperationError.DeviceProtectionError
NetworkTokenRedemptionException	OutOfBandOperationError.NetworkError
OutOfBandException	OutOfBandOperationError
ConfigurationDispatchTargetException	DeviceInformationChangeError.DeviceProtectionError
DispatchTargetException	DeviceInformationChangeError
NetworkDispatchTargetException	DeviceInformationChangeError.NetworkError

Local data

LocalDataManager is now LocalData.

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:

Kotlin

Delete Enrolled but not Registered PINs

Java

Delete Enrolled but not Registered PINs