Skip to main content
Version: 3.1.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, 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.

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.

  1. Provide the OutOfBandPayload to an OutOfBandOperation java, swift, flutter. 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, flutter.

  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, flutter and the AccountSelectionContext java, swift, flutter 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:
    • Invoke the object provided to Authentication.onSuccess java, swift, flutter, if the operation is completed successfully.
    • Invoke the object provided to Authentication.onErrorjava, 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.selectAccountjava, 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.selectAuthenticatorjava, 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.