Interactions

Interaction Structure

Field	Description
Type	Type of interaction: CONFIRM, CONFIRM_TRANSACTION, VERIFY_SECOND_FACTOR, or SET_SECOND_FACTOR.
SecondFactorInfo	In case the interaction is related to a second factor (Type: VERIFY_SECOND_FACTOR, or SET_SECOND_FACTOR), this contains the relevant data for rendering.
ConfirmSessionInfo	In case the interaction is asking for user confirmation for a login/enrol (Type: CONFIRM), this contains the relevant data for rendering.
InputTypes	Types of input that were provided (only when input was provided and State of the flow is PROCESSING): PIN, BIOMETRICS and/or CONFIRM.

Second Factor Info Structure

Field	Description
AllowedSecondFactors	Which second factor types are allowed (PIN and/or BIOMETRICS).
RequiredSecondFactors	Which second factor types are required (PIN and/or BIOMETRICS).

Confirm Session Info Structure

Field	Description
Accounts	For LOGIN interactions: list of accounts to select one from to log in with; For Interaction Type ENROL: list of pre-existing accounts in the Mobile SDK.
SecondFactorNeeded	True if a second factor is required to complete the current action; it will be requested during the interactions of the current flow.

Interaction Result Structure

Field	Description
Type	Result of the previous interaction: SUCCESS, PIN_FAIL, or BIOMETRICS_REMOVED.
InteractionType	Type of the (previous) interaction: CONFIRM, CONFIRM_TRANSACTION, VERIFY_SECOND_FACTOR, or SET_SECOND_FACTOR.
InputTypes	Types of input that were provided: PIN, BIOMETRICS and/or CONFIRM.

Note that the InteractionResult Type BIOMETRICS_REMOVED was introduced specifically for iOS, since there are no APIs to validate the constraints of a keychain item. For instance, we can only detect that the user changed their set of enrolled biometrics when attempting to use the item. The Mobile SDK handles this type of error internally and disables biometrics without user interaction.

Interaction Types

CONFIRM

Ask the user for confirmation of a session (login or enrol). Details in CurrentInteraction.ConfirmSessionInfo should be rendered to the user, asking to the user to confirm or reject the login or enrol.

Info

In case of an enrol, additional information can be found in Session.EnrolInfo, i.e. the existing accounts at the nextAuth Server for the given user and the displayName under which this account will be registered.

Info

If set by the server for this specific login or enrol, additional information can be found in Session.AnnounceInfo.

User input should be provided to the nextAuth Mobile SDK by the confirmSession or cancel method.

Info

In case of a login, confirmSession requires the account for which the user is logging in. The list of accounts to choose form can be found in CurrentInteraction.ConfirmSessionInfo.Accounts.

AndroidiOS

// enrol
NextAuth.getNextAuth().getFlowManager().confirmSession();
// login: specify for which account the user is logging in
NextAuth.getNextAuth().getFlowManager().confirmSession(account);

// enrol
flowService.confirmSession()
// login: specify for which account the user is logging in
flowService.confirmSession(with: account)

Provided that the confirmSession method does not throw an exception during initial input validation, the nextAuth Mobile SDK responds with a FlowUpdate callback with a flow State = PROCESSING. After this FlowUpdate, the next FlowUpdate is guaranteed to have one of the following States:

• State = WAIT_FOR_USER_INPUT, PreviousInteractionResult.Type = SUCCESS, PreviousInteractionResult.InteractionType = CONFIRM, and PreviousInteractionResult.InputType = CONFIRM;
• State = DONE; or
• State = ERROR and a specific error.

CONFIRM_TRANSACTION

Ask the user for confirmation of a transaction. Details in Transaction should be rendered to the user, asking the user to confirm or reject the transaction.

User input should be provided to the nextAuth Mobile SDK by the confirmTransaction or cancel method.

Provided that the confirmTransaction method does not throw an exception during initial input validation, the nextAuth Mobile SDK responds with a FlowUpdate callback with a flow State = PROCESSING. After this FlowUpdate, the next FlowUpdate is guaranteed to have one of the following States:

• State = WAIT_FOR_USER_INPUT, PreviousInteractionResult.Type = SUCCESS, PreviousInteractionResult.InteractionType = CONFIRM_TRANSACTION, and PreviousInteractionResult.InputType = CONFIRM;
• State = DONE; or
• State = ERROR and a specific error.

VERIFY_SECOND_FACTOR

Ask the user to enter their second factor, for validation purposes. Type gives information about the purpose of the entire flow. Details in CurrentInteraction.SecondFactorInfo should be used to determine which factors are allowed and should be offered to the user. The information in SecondFactorAccount gives additional context about the state the second factor account is in, such as how many PIN attempts remain.

The SecondFactorAccount contains more information on the current status of the user’s second factor account:

• isBlocked: whether the user is blocked from entering a PIN;
• failedAttempts and maxAttempts: number of failed PIN verifications and the maximum number before being blocked; and
• penalisedFor and penalisedUntil: depending on the second factor server PIN policies, there can be a threshold after which the user has to wait for a certain amount of time before being allowed to enter their PIN again.

The PreviousInteractionResult can be used to give the user feedback on success or failure of the previous interaction. For example, if PreviousInteractionResult.Type = VERIFY_SECOND_FACTOR and PreviousInteractionResult.InputType = PIN, but PreviousInteractionResult.Result = PIN_FAIL, the user can be informed that their previously entered PIN was incorrect.

User input should be provided to the nextAuth Mobile SDK by the inputSecondFactor (along with a PIN or biometrics and optional userInput) or cancel method. See here for more information on how to pass a PIN or biometrics to the nextAuth Mobile SDK.

AndroidiOS

// provide either pin or biometrics
NextAuth.getNextAuth().getFlowManager().inputSecondFactor(pin);
NextAuth.getNextAuth().getFlowManager().inputSecondFactor(cryptoObject);

// optionally, include userInput
NextAuth.getNextAuth().getFlowManager().inputSecondFactor(pin, userInput);
NextAuth.getNextAuth().getFlowManager().inputSecondFactor(cryptoObject, userInput);

// provide either pin or biometrics
flowService.inputSecondFactor(pin: pin)
flowService.inputSecondFactor(context: context)

Provided that the inputSecondFactor method does not throw an exception during initial input validation, a FlowUpdate callback for a flow with State = PROCESSING is generated by the nextAuth Mobile SDK. After this FlowUpdate, the next FlowUpdate is guaranteed to have one of the following States:

• State = WAIT_FOR_USER_INPUT, and PreviousInteractionResult.Type =
• SUCCESS, meaning that the verification was successful and the flow can continue;
• PIN_FAIL, meaning that the verification was not successful, but the flow can still continue;
• BIOMETRICS_REMOVED, meaning that biometrics were removed from the account due to an error, but the flow can still continue;
• State = DONE;
• State = ERROR and a specific error.

SET_SECOND_FACTOR

Ask the user to enter their second factor for registration purposes. This is done when the user first sets the second factor or when there is a change in that factor. Type gives information about the purpose of the entire flow. Details in CurrentInteraction.SecondFactorInfo should be used to determine which factors are allowed and should be offered to the user. For example, during enrolment both a PIN and biometrics can be set at the same time.

User input should be provided to the nextAuth Mobile SDK by the inputSecondFactor (along with a PIN and/or biometrics and optional user input) or cancel method.

Info

When setting the second factor it is possible to set both a PIN and biometrics at the same time. See here for more information.

Provided that the inputSecondFactor method does not throw an exception during initial input validation, a FlowUpdate callback for a flow with State = PROCESSING is generated by the nextAuth Mobile SDK. After this FlowUpdate, the next FlowUpdate is guaranteed to have one of the following States:

• State = WAIT_FOR_USER_INPUT, and PreviousInteractionResult.Type = SUCCESS, meaning that the setting the second factor was successful and the flow can continue;
• State = DONE;
• State = ERROR and a specific error.

Possible Interactions in Flows

Interactions that can occur in a specific flow (order not guaranteed):

Flow / Interaction	CONFIRM	CONFIRM_TRANSACTION	VERIFY_SECOND_FACTOR	SET_SECOND_FACTOR
ENROL
LOGIN
SIGN_TRANSACTION
CHANGE_PIN
ADD_BIOMETRICS
REMOVE_BIOMETRICS
HEADLESS_UPGRADE

Receiving Flow Updates

On Android, the current Flow can be fetched from the Mobile SDK. On iOS, this feature is not available.

Android

NextAuth.getNextAuth().getFlowManager().getFlow();

The Mobile SDK also broadcasts updates to the Flow, which the app can listen to.

In general, FlowUpdates can arrive at any time and can change any element, with a few constraints:

• the basic flow lifecycle is respected, with DONE and ERROR being final states;
• the fields inside CurrentInteraction (with the exception of CurrentInteraction.InputTypes) and PreviousInteractionResult will not change, unless the interaction is changed in its entirety (e.g. transition between two interactions or termination of the flow);
• SecondFactorAccount and Session can change at any time and always reflect the most recent values at the time of fetching the flow. For simplicity, during user input and interactions, you can assume that these fields will not change. (In the current implementation of the SDK, updates to these fields will not be broadcasted during an interaction.)