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

Authentication

Using the authentication operation, you can verify the identity of the user using an already registered authenticator.

tip

To do an authentication operation, configure and initialize the SDK to obtain a MobileAuthenticationClient java, swift, objc, flutter, react native.

Depending on the use case, there are two types of authentication: in-app authentication and out-of-band authentication.

For more information, see Authentication.

In-app authentication

For the application to trigger the authentication, provide the name of the user to authenticate to an Authentication java, swift, objc, flutter, react native, and trigger an in-app authentication.

info

In Authentication Cloud, the name is the technical username, that is, the userId attribute of the Authentication Cloud API.

The LocalData.accounts java, swift, objc, flutter, react native method can be used to get the registered accounts, and the Account.username() java, swift, objc, flutter, react native method to get the user name of each account.

Provide an authenticator selector, which returns the authenticator to be used.

Depending on the authenticator used to authenticate, provide any of the corresponding user verifiers: PIN user verifier, password user verifier, biometric user verifier, device passcode user verifier, or fingerprint user verifier.

Authentication

Out-of-band authentication

When the authentication is initiated in another device or application, the information required to process the operation is transmitted through a QR code or a link. An example of out-of-band authentication is the case where the user wants to do a bank transfer using a web application in a laptop, and the server sends a push notification to the application asking for authentication.

The out-of-band authentication is done in three phases:

  1. The payload obtained from the QR code or the link is provided to an OutOfBandPayloadDecode java, swift, objc, flutter, react native to obtain an OutOfBandPayload java, swift, objc, flutter, react native object. The payload to be provided is of type:
{
"nma_data" : {
"token" : "b4b07559-f934-4597-a1c5-44d89f691e8f",
"redeem_url" : "https://fido.siven.ch/nevisfido/token/redeem/authentication"
},
"nma_data_content_type" : "application/json",
"nma_data_version" : "1"
}

For more information on how to obtain the OutOfBandPayload, see Obtain an out-of-band payload.

  1. Provide the OutOfBandPayload to an OutOfBandOperation java, swift, objc, flutter, react native. When building the OutOfBandOperation, invoke the OutOfBandOperation.onAuthentication method with an object taking an OutOfBandAuthentication.

  2. Invoke OutOfBandOperation.execute. If the provided payload is successfully redeemed in the server, and it corresponds to an authentication, the object provided in OutOfBandOperation.onAuthentication is invoked with an OutOfBandAuthentication java, swift, objc, flutter, react native.

  3. Provide an authenticator selector, and the required user verifiers to the OutOfBandAuthentication.

  4. Invoke OutOfBandAuthentication.execute to continue with the operation.

Out-of-Band Authentication

Usernameless authentication

You can start an out-of-band authentication without a username in the initial request. In this scenario, the operation allows to authenticate with different accounts. To support the scenario, provide an Account Selector.

tip

If you do not need to support usernameless authentication, or if your application only supports one account, you do not need to provide the AccountSelector.

Transaction confirmation

There are cases when specific information is to be presented to the user during the user verification process, known as transaction confirmation in the FIDO UAF protocol.

In case of transaction confirmation, the AuthenticatorSelectionContext java, swift, objc, flutter, react native and the AccountSelectionContext java, swift, objc, flutter, react native contain a byte array with the transaction information. The byte array corresponds to the content attribute.

Transaction Confirmation

Lifecycle

  1. The authentication is started by calling the execute method.
  2. In case of out-of-band authentication, where an Account Selector is to be provided, the SDK invokes the account selector. If the AccountSelectionContext contains transaction confirmation information, the contents of the transaction confirmation are presented to the user for validation.
  3. The SDK invokes the Authenticator Selector. If the AuthenticatorSelectionContext contains transaction confirmation information and the contents are not presented previously, the contents of the transaction confirmation are presented to the user for validation. Depending on the selected authenticator, the SDK does the following:
  4. When the operation is completed, the SDK does the following:

In-app authentication

Out-of-band authentication

Account selector

To support usernameless authentication and multiple accounts, define an AccountSelector java, swift, objc, flutter, react native, and if using the OutOfBandAuthentication.accountSelector java, swift, objc, flutter, react native method.

Select an account

The AccountSelector is called by the SDK to select an account used for the out-of-band authentication. It is the responsibility of the application to decide whether to ask the user to perform the selection, or to do it directly without user intervention.

  1. The user initiates an action that requires to select an account, like scanning an authentication QR code.
  2. The application invokes Operations java, swift, objc, flutter, react native to build the operation. The application provides the AccountSelector to the operation built.
  3. The SDK calls the AccountSelector.selectAccountjava, swift, objc, flutter, react native method. The AccountSelectionContext java, swift, objc, flutter, react native contains a list of accounts and authenticator objects to identify which accounts can be used with which authenticator.
  4. The application shows the list of available accounts to the user.
    1. The user selects an account.
    2. The application provides the username of the account invoking the AccountSelectionHandler.username java, swift, objc, flutter, react native method.

The SDK can now continue the out-of-band authentication using the selected account.

Authenticator selector

The Nevis Mobile Authentication SDK needs to know which is the authenticator used for the operation. The developer has to provide an AuthenticatorSelector java, swift, objc, flutter, react native when building the operation.

Performing authenticator "eligibility" checks

It is very important that the authenticator selector performs the necessary checks to determine whether an authenticator is "usable" or not, otherwise the operation will fail.

Checks that need to be done are:

  • Is the authenticator policy compliantjava, swift, objc, flutter, react native
  • Is the authenticator supported by the mobile device hardware
  • Is the authenticator not registered (registration) or registered (authentication) for the given user

The JavaDoc contains example code of these checks.

Select an authenticator

The AuthenticatorSelector is called by the SDK to select an authenticator used for the operation. It is the responsibility of the application to decide whether to ask the user to perform the selection, or to do it directly without user intervention.

  1. The user initiates an action that requires to select an authenticator, like registration or authentication.
  2. The application invokes Operations java, swift, objc, flutter, react native to build the operation. The application provides the AuthenticatorSelector to the operation being built.
  3. The SDK calls the AuthenticatorSelector.selectAuthenticatorjava, swift, objc, flutter, react native method. The AuthenticatorSelectionContext java, swift, objc, flutter, react native contains a list of authenticator objects, including AAIDs, which uniquely identify each authenticator.
  4. The application shows the list of available authenticators to the user.
    1. The user selects an authenticator.
    2. The application provides the AAID of the authenticator invoking the AuthenticatorSelectionHandler.aaid java, swift, objc, flutter, react native method.

The SDK can now continue the operation started by using the selected authenticator.

PIN user verifier

When authentication with PIN is required, the developer has to provide a PinUserVerifier java, swift, objc, flutter, react native when building the operation. The PinUserVerifier is in charge of displaying a user interface asking the user to provide the PIN and to display the recoverable errors during authentication, for example, if the user provided an invalid PIN.

PIN user verification

The PinUserVerifier is called by the SDK to ask the user to provide a PIN.

  1. The SDK calls the PinUserVerifier.verifyPin java, swift, objc, flutter, react native method.
  2. The application asks the user to provide a PIN. For example, the application displays a textbox where the user provides a PIN.
  3. The user provides the PIN.
  4. The application provides the PIN invoking the PinUserVerificationHandler.verifyPin java, swift, objc, flutter, react native method.
  5. The SDK validates whether the provided PIN is valid.
  6. If the provided PIN is not valid, and the PIN authenticator is not locked, the SDK invokes PinUserVerifier.verifyPin again and the PinUserVerificationContext java, swift, objc, flutter, react native contains a recoverable error.
  7. If the provided PIN is not valid, and too many failed attempts occurred, the PIN authenticator is locked, and the operation fails. 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.
  8. On Android, Flutter and React Native, if the provided credentials are valid, the PinUserVerifier.onValidCredentialsProvided java, flutter, react native method is invoked.
Cool-down Mode

After certain number of failed attempts, the PIN authenticator will enter the cool-down mode. When in cool-down mode, providing a PIN (valid or invalid) will be ignored, and the SDK will invoke again PinUserVerifier.verifyPin 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 a PIN when in cool-down mode will just generate unnecessary processing, and it is recommended to avoid it.

Password user verifier

When authentication with password is required, the developer has to provide a PasswordUserVerifier java, swift, objc, flutter, react-native when building the operation. The PasswordUserVerifier is in charge of displaying a user interface asking the user to provide the password and to display the recoverable errors during authentication, for example, if the user provided an invalid password.

Password user verification

The PasswordUserVerifier is called by the SDK to ask the user to provide a password.

  1. The SDK calls the PasswordUserVerifier.verifyPassword java, swift, objc, flutter, react-native method.
  2. The application asks the user to provide a password. For example, the application displays a textbox where the user provides a password.
  3. The user provides the password.
  4. The application provides the password invoking the PasswordUserVerificationHandler.verifyPassword java, swift, objc, flutter, react-native method.
  5. The SDK validates whether the provided password is valid.
  6. If the provided password is not valid, and the password authenticator is not locked, the SDK invokes PasswordUserVerifier.verifyPassword again and the PasswordUserVerificationContext java, swift, objc, flutter, react-native contains a recoverable error.
  7. If the provided password is not valid, and too many failed attempts occurred, the password authenticator is locked, and the operation fails. 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.
  8. On Android, Flutter and React Native, if the provided credentials are valid, the PasswordUserVerifier.onValidCredentialsProvided java, flutter, react-native method is invoked.
Cool-down Mode

After certain number of failed attempts, the password authenticator will enter the cool-down mode. When in cool-down mode, providing a password (valid or invalid) will be ignored, and the SDK will invoke again PasswordUserVerifier.verifyPassword 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 a password when in cool-down mode will just generate unnecessary processing, and it is recommended to avoid it.

Biometric user verifier

info

The biometric authenticator is specific to Android devices. For iOS please refer to the FaceID or TouchID authenticator.

When authentication using the biometric authenticator is required, the developer has to provide a BiometricUserVerifier java, swift, objc, flutter, react native when building the operation. The BiometricUserVerifier does not need to implement the user interface asking for biometric credentials, as this is handled by the SDK.

Biometric user verification

The BiometricUserVerifier is called by the SDK to ask the user to provide fingerprint credentials.

  1. The SDK calls the BiometricUserVerifier.verifyBiometric java, swift, objc, flutter, react native method.
  2. On Android Flutter and React Native, the application invokes BiometricUserVerificationHandler.listenForOsCredentials java, flutter, react native so that the SDK starts listening for biometric credentials.
  3. On iOS, the application invokes the BiometricUserVerificationHandler.verify swift, objc method.
  4. The SDK displays a user interface asking the user to provide credentials.
  5. The user provides biometric credentials.
  6. The operating system validates the provided credentials.
  7. If the provided biometric credentials are not valid, the operating system displays an error to inform the user. If supported by the OS version and enabled during registration, it also proposes the user to provide device credentials as fallback: PIN, gestures, or password.
  8. If the provided biometric information 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.
  9. On Android, Flutter and React Native, if the provided credentials are valid, the BiometricUserVerifier.onValidCredentialsProvided java, flutter, react native method is invoked.

Device passcode user verifier

When authentication using the device passcode authenticator is required, the developer has to provide a DevicePasscodeUserVerifier java, swift, objc, flutter, react native when building the operation. The DevicePasscodeUserVerifier does not need to implement the user interface asking for device passcode credentials, as this is handled by the SDK.

Device passcode user verification

The DevicePasscodeUserVerifier is called by the SDK to ask the user to provide device passcode credentials.

  1. The SDK calls the DevicePasscodeUserVerifier.verifyDevicePasscode java, swift, objc, flutter, react native method.
  2. On Android, Flutter and React Native, the application invokes DevicePasscodeUserVerificationHandler.listenForOsCredentials java, flutter, react native so that the SDK starts listening for device passcode credentials.
  3. On iOS, the application invokes the DevicePasscodeUserVerificationHandler.verify swift, objc method.
  4. The SDK invokes the operating system to display a user interface asking the user to provide credentials.
  5. The user provides device passcode credentials.
  6. The operating system validates the provided credentials.
  7. If the provided device passcode credentials are not valid, the operating system displays an error to inform the user.
  8. If the provided device passcode information 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.
  9. On Android, Flutter and React Native, if the provided credentials are valid, the DevicePasscodeUserVerifier.onValidCredentialsProvided java, flutter, react native method is invoked.

Fingerprint user verifier

info

The fingerprint authenticator is supported only on Android devices. The SDK supports the fingerprint authenticator to handle older Android OS versions that do not support the biometric authentication. If the biometric authenticator is supported by the operating system, we recommend to use that authenticator, and not to allow class 2 sensors for maximum security. This means that only the fingerprint will be available as an authentication method of the biometric authenticator.

When authentication with fingerprint is required, the developer has to provide a FingerprintUserVerifier java, flutter, react native when building the operation. The FingerprintUserVerifier is in charge of displaying a user interface asking the user to provide fingerprints, and to display the recoverable errors during authentication. For example, if the user moved the finger too quickly.

Fingerprint user verification

The FingerprintUserVerifier is called by the SDK to ask the user to provide fingerprint credentials.

  1. The SDK calls the FingerprintUserVerifier.verifyFingerprint java, flutter, react native method.
  2. The application invokes FingerprintUserVerificationHandler.listenForOsCredentials java, flutter, react native so that the SDK starts listening for fingerprint credentials. The SDK does not automatically display relevant UI.
  3. The application asks the user to provide fingerprint credentials, for example, by displaying a screen with an image of a fingerprint.
  4. The user provides fingerprint credentials.
  5. The SDK validates that the provided fingerprints are valid.
  6. If the provided fingerprints are not valid, the SDK invokes FingerprintUserVerifier.verifyFingerprint again, and the FingerprintUserVerificationContext java, flutter, react native contains a recoverable error.
  7. If the provided fingerprints are not valid, and too many failed attempts occurred, then the operation fails and the object managing the error that was provided in the onError method when building the operation is invoked.
  8. If the provided credentials are valid, the FingerprintUserVerifier.onValidCredentialsProvided java, flutter, react native method is invoked.