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, flutter}.

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, flutter}, and trigger an in-app authentication.

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, biometric user verifier, or fingerprint user verifier.

Android/Kotlin

Authentication

Android/Java

Authentication

iOS/Swift

Authentication

Flutter/Dart

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, flutter} to obtain an OutOfBandPayload _{java, swift, flutter} 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 Out-of-Band Payload Decode.

2. Provide the OutOfBandPayload to an OutOfBandOperation _{java, swift, flutter}. When building the OutOfBandOperation, invoke the OutOfBandOperation.onAuthentication method with an object taking an OutOfBandAuthentication.

3. 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, flutter}.

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

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

Android/Kotlin

Out-of-Band Authentication

Android/Java

Out-of-Band Authentication

iOS/Swift

Out-of-Band Authentication

Flutter/Dart

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, flutter} and the AccountSelectionContext _{java, swift, flutter} contain a byte array with the transaction information. The byte array corresponds to the content attribute.

Android/Kotlin

Transaction Confirmation

Android/Java

Transaction Confirmation

iOS/Swift

Transaction Confirmation

Flutter/Dart

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:
   • Invoke the PIN user verifier, if PIN is selected.
   • Invoke the biometric user verifier, only applicable when running on an Android device, when the biometric authenticator is selected.
   • Invoke the fingerprint user verifier, only applicable when running on an Android device, when the fingerprint authenticator is selected.
4. When the operation is completed, the SDK does the following:
   • Invoke the object provided to Authentication.onSuccess _{java, swift, flutter}, if the operation is completed successfully.
   • Invoke the object provided to Authentication.onError_{java, swift, flutter} with the error, if the operation is completed with an error.

In-app authentication

Out-of-band authentication

Account selector

To support usernameless authentication and multiple accounts, define an AccountSelector _{java, swift, flutter}, and if using the OutOfBandAuthentication.accountSelector _{java, swift, flutter} 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, flutter} to build the operation. The application provides the AccountSelector to the operation built.
3. The SDK calls the AccountSelector.selectAccount_{java, swift, flutter} method. The AccountSelectionContext _{java, swift, flutter} 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, flutter} 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, flutter} when building the operation.

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, flutter} to build the operation. The application provides the AuthenticatorSelector to the operation being built.
3. The SDK calls the AuthenticatorSelector.selectAuthenticator_{java, swift, flutter} method. The AuthenticatorSelectionContext _{java, swift, flutter} 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, flutter} 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, flutter} 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, flutter} 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, flutter} 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, flutter} 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 and Flutter, if the provided credentials are valid, the PinUserVerifier.onValidCredentialsProvided _{java, flutter} method is invoked.

Biometric user verifier

caution

The biometric authenticator is specific to Android devices.

When authentication using the biometric authenticator is required, the developer has to provide a BiometricUserVerifier _{java, swift, flutter} 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, flutter} method.
2. The application invokes BiometricUserVerificationHandler.listenForOsCredentials _java so that the SDK starts listening for biometric credentials.
3. The SDK displays a user interface asking the user to provide credentials.
4. The user provides biometric credentials.
5. The SDK validates that the provided credentials are valid.
6. If the provided biometric credentials are not valid, the SDK displays an error informing the user that the provided credentials are not valid. If supported by the OS version, it also proposes the user to provide device credentials as fallback: PIN, gestures, or password.
7. 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.
8. On Android and Flutter, if the provided credentials are valid, the BiometricUserVerifier.onValidCredentialsProvided _{java, flutter} method is invoked.

Fingerprint user verifier

note

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 the fingerprint authenticator.

When authentication with fingerprint is required, the developer has to provide a FingerprintUserVerifier _{java, flutter} 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} method.
2. The application invokes FingerprintUserVerificationHandler.listenForOsCredentials _{java, flutter} 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} 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} method is invoked.