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

Registration

Before being able to authenticate using the Nevis Mobile Authentication SDK, go through the registration process. In the registration operation, FIDO UAF credentials aree created on both mobile and server side. The credentials are used during authentication to validate that the user provided valid authentication.

tip

To do a registration operation, configure and initialize the SDK to obtain a MobileAuthenticationClient java, swift, flutter.

Depending on the use case, there are two types of registration: in-app registration and out-of-band registration. For more information, see Registration.

In-app registration​

If the application triggers the registration, we are in the context of in-app registration.

Authentication Cloud​

If your application is using a backend relying on the Authentication Cloud, your application has to obtain an enroll response or an appLinkUri to start the registration. You can get the enroll response by your backend invoking the Authentication Cloud API enroll. If the request is successful, the JSON response looks something like this:

{
  "userId": "7e16ba00-92e2-4fcb-b30e-1af8fdc843aa",
  "username": "u12345",
  "status": "new",
  "createdAt": "2020-10-09T12:13:11.845958Z",
  "updatedAt": "2020-10-09T12:13:11.845958Z",
  "authenticators": [],
  "enrollment": {
    "transactionId": "67cae36e-e3d5-4d67-9aa6-ab7ae3050576",
    "statusToken": "eyJhbGciO...PxOZZYow",
    "qrCode": {
      "type": "image/png",
      "size": 300,
      "dataUri": "data:image/png;base64,iVBO...YII"
    },
    "appLinkUri": "https://{instance}.mauth.nevis.cloud/open?dispatchTokenResponse=eyJub...IxIn0"
  }
}

Provide the returned JSON response or the value of the appLinkUri attribute to an AuthCloudApiRegistration java, swift, flutter, and trigger an in-app registration.

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

Depending on the authenticators available to register, provide any of the following:

Authentication Cloud Registration

Identity Suite​

When the backend used by your application does not use the Nevis Authentication Cloud, provide the name of the user to be registered to Registration java, swift, flutter, and trigger an in-app registration.

If authorization is required by your backend to register, provide an AuthorizationProvider java, swift, flutter.

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

Depending on the authenticators availale to register, provide any of the following:

Registration

Out-of-band registration​

When the registration 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 registration is the case where the user provides credentials in a laptop to obtain a registration QR code, and then the user scans the QR code in your application.

The out-of-band registration 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 get an OutOfBandPayload java, swift, flutter object. The payload to be provided is of the following type:
{
  "nma_data": {
    "token": "b4b07559-f934-4597-a1c5-44d89f691e8f",
    "redeem_url": "https://fido.siven.ch/nevisfido/token/redeem/registration"
  },
  "nma_data_content_type": "application/json",
  "nma_data_version": "1"
}

For mor information on how to get OutOfBandPayload, see Out-of-Band Payload Decode.

  1. Provide the OutOfBandPayload to an OutOfBandOperation java, swift object. When building the OutOfBandOperation, invoke the OutOfBandOperation.onRegistration method with an object taking an OutOfBandRegistration.
  2. Invoke OutOfBandOperation.execute. If the provided payload is successfully redeemed in the server, and it corresponds to a registration, the object provided in OutOfBandOperation.onRegistration is invoked with an OutOfBandRegistration java, swift, flutter.
  3. Provide an authenticator selector, a PinEnroller if a PIN can be registered in your application, and the user verifiers to the OutOfBandRegistration.
  4. Invoke OutOfBandRegistration.execute to continue with the operation.
Out-of-Band Registration

Lifecycle​

  1. When the execute method is invoked, the registration is started.
  2. The SDK invokes the Authenticator Selector.
  3. Depending on the selected authenticator, the SDK does the following:
  • Invoke the PIN enroller, if PIN is selected.
  • Invoke the biometric user verifier, only applicable when running on an Android device, if the biometric authenticator is selected.
  • Invoke the fingerprint user verifier, only applicable when running on an Android device, if the fingerprint authenticator is selected.
  1. When the operation completes, the SDK does the following:
  • Invoke the object provided to Registration.onSuccess java, swift, flutter, if the operation completes successfully.
  • Invoke the object provided to Registration.onErrorjava, swift, flutter, with the error, If the operation completes with an error.
note

The PIN authenticator is fully managed by the SDK: its contents are defined and modified through the SDK.

However, the other authenticators are enrolled by the operating system, thus the user has to authenticate at the end of the registration for these authenticators.

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 Enroller​

When a PIN authenticator is to be registered, a PIN is to be defined. The developer has to provide a PinEnroller java, swift, flutter when building the registration operation. The PinEnroller is in charge of providing the PIN to the SDK. The PinEnroller asks the user for the PIN and provides it to the SDK, which validates it against the PIN policy.

The PinEnroller can also define which is the PIN policy to be used through PinPolicyProvider interface java, swift, flutter.

Enroll PIN​

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

  1. The SDK calls the PinEnroller.enrollPin 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, and another textbox to confirm it.
  3. The user provides the PIN.
  4. The application provides the PIN invoking the PinEnrollmentHandler.pin java, swift, flutter method.
  5. The SDK validates whether the provided PIN is compliant with the PinPolicy java, swift, flutter.
  6. If the provided PIN is not compliant with the PIN policy, the SDK invokes PinEnroller.enrollPin again, and the PinEnrollmentContext java, swift, flutter contains a recoverable error.
  7. On Android and Flutter, if the provided credentials are valid, the PinEnroller.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.
Last updated on