Skip to main content
Version: 3.7.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​

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.

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.

Last updated on