Skip to main content
Version: 3.8.x.x RR

Other operations

tip

Before being able to execute any of the operations described, configure and initialize the SDK to obtain a MobileAuthenticationClient java, swift, objc, flutter, react native.

Change PIN​

Using the change PIN operation, you can modify the PIN of a registered PIN authenticator for a given user.

To change the PIN of a registered authenticator, provide the name of the user whose PIN is to be changed and a PinChanger java, swift, objc, flutter, react native.

PIN Change

The PinChanger is in charge of providing the old and new PINs to the SDK.

The PinChanger can also define which is the PIN policy to be used for the new PIN, see PinChanger.pinPolicy java, swift, objc, flutter, react native.

Change PIN​

The PinChanger is called by the SDK to obtain the value of the PIN to be registered.

  1. The application builds a PinChange operation and invokes PinChange.execute java, swift, objc, flutter, react native
  2. The SDK calls the PinChanger.changePin java, swift, objc, flutter, react native method.
  3. The application asks the user to provide the old and the new PIN. For example, the application displays a textbox where the user provides the old PIN and another textbox to define the new one.
  4. The user provides the PINs.
  5. The application provides the PINs invoking the PinChangeHandler.pins java, swift, objc, flutter, react native method.
  6. The SDK validates that the old PIN is valid, and that thew new PIN is compliant with the PinPolicy java, swift, objc, flutter, react native.
  7. If the provided new PIN is not compliant with the PIN policy, the SDK invokes PinChanger.changePin again and the PinChangeContext java, swift, objc, flutter, react native contains a recoverable error. The same occurs if the provided old PIN is not valid, but the PIN authenticator is not locked yet.
  8. If the provided old PIN is not valid, and too many failed attempts occurred, then the operation fails and the object managing the error provided in the onError method when building the operation is invoked. For more information on PIN lockout, see Brute force attack prevention.
  9. If the provided PINs are valid, and the modification is successful, the object provided in the onSuccess method when building the registration operation is invoked.
Cool-down Mode

After certain number of failed attempts providing the old PIN, the PIN authenticator will enter the cool-down mode. When in cool-down mode, providing PINs again (valid or invalid) will be ignored, and the SDK will invoke again PinChanger.changePin without changing the number of remaining retries. This implies that the PIN authenticator cannot be locked when it is in cool-down mode.

Thus, providing PINs when in cool-down mode will just generate unnecessary processing, and it is recommended to avoid it.

Change password​

Using the change password operation, you can modify the password of a registered password authenticator for a given user.

To change the password of a registered authenticator, provide the name of the user whose password is to be changed and a PasswordChanger java, swift, objc, flutter, react-native.

Password Change

The PasswordChanger is in charge of providing the old and new passwords to the SDK.

The PasswordChanger also defines which is the PasswordPolicy java, swift, objc, flutter, react-native to be used, see PasswordChanger.passwordPolicy java, swift, objc, flutter, react-native. The PasswordPolicy is the object that determines whether the new password is valid or not. For example the password policy can enforce that the password has at least 10 characters and contains at least one capital letter and a number.

Change Password​

The PasswordChanger is called by the SDK to obtain the value of the password to be registered.

  1. The application builds a PasswordChange operation and invokes PasswordChange.execute java, swift, objc, flutter, react-native
  2. The SDK calls the PasswordChanger.changePassword java, swift, objc, flutter, react-native method.
  3. The application asks the user to provide the old and the new password. For example, the application displays a textbox where the user provides the old password and another textbox to define the new one.
  4. The user provides the passwords.
  5. The application provides the passwords invoking the PasswordChangeHandler.passwords java, swift, objc, flutter, react-native method.
  6. The SDK validates that the old password is valid, and that the new password is different than the new password.
  7. If the provided old password is not valid (or is valid and equal to the new password) and the password authenticator is not locked, the SDK invokes PasswordChanger.changePassword again and the PasswordChangeContext java, swift, objc, flutter, react-native contains a recoverable error.
  8. If the provided old password is not valid, and too many failed attempts occurred, the password authenticator is locked, the operation fails, and the object managing the error provided in the onError method when building the operation is invoked. For more information on password lockout, see Brute force attack prevention.
  9. If the old password is valid the PasswordPolicy.validatePasswordForPasswordChange java, swift, objc, flutter, react-native method is invoked.
  10. The application (through the PasswordPolicy) informs the SDK of whether the new password is valid or not.
  11. If the provided new password is not compliant with the password policy, the SDK invokes PasswordChanger.changePassword again and the PasswordChangeContext java, swift, objc, flutter, react-native contains a recoverable error.
  12. If the provided passwords are valid, and the modification is successful, the object provided in the onSuccess method when building the registration operation is invoked.
Cool-down Mode

After certain number of failed attempts providing the old password, the password authenticator will enter the cool-down mode. When in cool-down mode, providing passwords again (valid or invalid) will be ignored, and the SDK will invoke again PasswordChanger.changePassword without changing the number of remaining retries. This implies that the password authenticator cannot be locked when it is in cool-down mode.

Thus, providing passwords when in cool-down mode will just generate unnecessary processing, and it is recommended to avoid it.

Obtain an out-of-band payload​

Out-of-band operations occur when a message is delivered to the application through an alternate channel like a push notification, a QR code, or a deep link. The application is responsible to create an OutOfBandPayload java, swift, objc, flutter, react native object from the data contained in such a message.

The OutOfBandPayload is then used to start an OutOfBandOperation java, swift, objc, flutter, react native, see chapters Out-of-Band Registration and Out-of-Band Authentication.

Out-of-band payload from QR code​

An example to get an OutOfBandPayload after scanning a Nevis mobile authentication registration QR code looks something like this:

OutOfBandPayload from Scanned QR Code

Out-of-band payload from push notification​

In case of push notifications, the OutOfBandPayload is provided in a platform-specific object:

  • Android: com.google.firebase.messaging.RemoteMessage
  • iOS: UNNotificationResponse
note

The code uses a com.google.gson.Gson object to generate JSON for Android.

OutOfBandPayload from Push Notification

Out-of-band payload from pending operations (fetch channel)​

The SDK offers the PendingOutOfBandOperations java, swift, objc, flutter react native API to retrieve the out-of-band operations that have not been processed, nor have timed-out.

This API can be helpful to handle the case where a push notification does not reach the mobile application.

Concept

Refer to our concept guide for additional conceptual information regarding this fetch channel.

Experimental API
  • This API is experimental and can be modified or dropped in future releases without notice.
  • The Nevis Authentication Cloud supports this API.
  • The Nevis Identity Suite requires nevisFIDO version 7.2402.1.2 or later.
User registrations done with Android SDK 3.6.0 / 3.6.1

Due to an issue affecting users whose first registration was done with Android SDK 3.6.1 or 3.6.2. This operation does not call the Get Device Out-of-band Operations endpoint for affected users. Instead, the operation will return an empty result.

The following example shows how to get an OutOfBandPayload after scanning a Nevis Mobile Authentication registration QR code:

OutOfBandPayload from Pending Operation

Change device information​

During registration, DeviceInformation java, swift, objc, flutter, react native must be provided. The DeviceInformation contains the name identifying your device and optionally the Firebase Cloud Messaging registration token Android, iOS, Flutter, React Native used by the backend to send authentication push notifications to your application.

You can update both the name and the Firebase Cloud Messaging token using DeviceInformationChange java, swift, objc, flutter, react native.

Device Information Change

Handle changes in the Firebase registration token​

If the Firebase token changes, the application has to inform the server about that change, otherwise future dispatching does not work.

In case of Android, changes in the Firebase registration token update are identified inside the implementation of the com.google.firebase.messaging.FirebaseMessagingService class of your application. iOS identifies the changes using Firebase.MessagingDelegate. Flutter identifies the changes by subscribing to the FirebaseMessaging.instance.onTokenRefresh stream.

To avoid update errors more easily, the operation supports adding a retry strategy. In case of network failure, the operation gets retried up to the specified limit with the desired delay. Resolving any synchronization problems is the responsibility of the caller.

Update DeviceInformation from AppMessagingService

Disable push notifications​

If you want the backend to stop sending push notifications, you can use the DeviceInformationChange.disablePushNotifications java, swift, objc, flutter, react native method:

Push Notification Disable

tip

To re-enable sending of push notifications, execute a DeviceInformationChange, and provide the Firebase Cloud Messaging registration token using DeviceInformationChange.fcmRegistrationToken java, swift, objc, flutter, react native method.

Get information​

LocalData​

You can use the LocalData java, swift, objc, flutter, react native object to obtain the following information:

  1. LocalData.accounts java, swift, objc, flutter, react native to get the registered accounts.
  2. LocalData.deviceInformation java, swift, objc, flutter, react native to get the device information.
  3. LocalData.authenticators java, swift, objc, flutter, react native to get the authenticator information.

This information can be used to find out whether there is a registered authenticator or not, and thus if the user must register an authenticator or if authentication is possible right away.

To obtain a LocalData object, invoke the MobileAuthenticationClient.localData java, swift, objc, flutter, react native method.

SDK MetaData​

The SDK provides a static API to query the metadata of the SDK regardless the MobileAuthenticationClient is initialized or not. The information provided by the API is different for each platform to accommodate platform-specific important or useful information.

Android​

On Android the API provides the following information:

  • Nevis Mobile Authentication SDK version.
  • SHA-256 hash of signing certificate of the application that includes the SDK. This is useful for Android App Links.

Refer to the Android JavaDoc MetaData API reference for more details.

iOS​

On iOS the API provides the following information:

  • Nevis Mobile Authentication SDK version.
  • The FacetId used by the Nevis Mobile Authentication SDK.

Refer to the iOS Swift MetaData API reference for more details.

Remove local data​

You may need to delete the authenticator data stored by the SDK, for example, after a potential attack. Deregistration may not possible because deregistration is usually a protected operation that needs user intervention to obtain authorization.

To delete authenticator data locally, you can use the LocalData.deleteAuthenticator java, swift, objc, flutter, react native method.

Check and synchronize device information​

During registration, the SDK creates FIDO UAF credentials and creates device information in both the mobile device and the server.

This information can get out-of-sync in some scenarios; for example:

  • An administration tool allows updating the name of the device in the backend, but the mobile device is not aware of this change and retains the old device name.
  • An administration tool allows disabling push notifications in the backend by "unsetting" the Firebase registration token. The client may want to inform the end-user that push notifications are not enabled, or may decide to enable them again.
  • An administrator removes a FIDO UAF credential in the server because a suspicious activity was detected. The FIDO UAF credentials remain in the mobile device, even if they are rendered unusable due to the missing backend credentials.
  • A developer removes the PIN authenticator locally (see Remove local data) because the PIN is locked. The FIDO UAF credentials are still present in the server.

To be able to handle scenarios such as the ones outlined above, the SDK provides the DeviceInformationCheck java, swift, objc, flutter, react native and the DeviceInformationSync java, swift, objc, flutter, react native operations.

DeviceInformationCheck allows to identify whether there are configuration mismatches between the device information in the client (mobile device application) and the server.

The output of DeviceInformationCheck (see DeviceInformationCheckResult.mismatches() java, swift, objc, flutter, react native) can be used to address those mismatches. The API only reports the mismatches, it does not automatically address them giving the app developers more implementation flexibility.

Using the DeviceInformationSync API

Some of the changes result in removal of credentials on both the server and client side. Use DeviceInformationSync with caution and understanding its implications. The changes that will be applied are described in the documentation of each DeviceInformationMismatch java, swift, objc, flutter, react native

Device Information Check and Sync

Limitations​

The DeviceInformationCheckand DeviceInformationSync APIs come with important to know limitations:

  • The APIs of these operations are experimental and can change in the future without notice.
  • The operations are supported only with FIDO UAF registrations made against a backend with nevisFIDO 7.2408.** or later. With registrations made with earlier versions of nevisFIDO, the check operation can return DeviceInformationMismatch.MissingAuthenticatorInServer java, swift, objc, flutter, react native false positives, that is, it can report mismatches, when the credentials of backend and server are in sync.
  • The operations will work if there is at least one authenticator registered in the mobile device, and the associated device information (in nevisFIDO terminology, dispatch target) still exists in the server.
Last updated on