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 (will be requested in next interactions of this 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)[flows.md#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 (on initial input validation), a FlowUpdate callback for a flow with State PROCESSING comes back from the nextAuth Mobile SDK. After this FlowUpdate, another FlowUpdate is guaranteed to follow, for a flow with either:

• State=WAIT_FOR_USER_INPUT, PreviousInteractionResult.Type=SUCCESS, PreviousInteractionResult.InteractionType=CONFIRM, and PreviousInteractionResult.InputType=CONFIRM;
• State=DONE;
• 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 (on initial input validation), a FlowUpdate callback for a flow with State PROCESSING comes back from the nextAuth Mobile SDK. After this FlowUpdate, another FlowUpdate is guaranteed to follow, for a flow with either:

• State=WAIT_FOR_USER_INPUT, PreviousInteractionResult.Type=SUCCESS, PreviousInteractionResult.InteractionType=CONFIRM_TRANSCATION, and PreviousInteractionResult.InputType=CONFIRM;
• State=DONE;
• 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), penalisedFor and penalisedUntil (depending on the second factor server pin policies, there can be threshold after which the user has to wait for a certain amount of time before being allowed again to enter their pin).

The PreviousInteractionResult can be used to give the user feedback on success or failure of the previous interaction. For example, if PreviousInteractionResult.Type is also VERIFY_SECOND_FACTOR and PreviousInteractionResult.InputType = PIN, but PreviousInteractionResult.Result is 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 biometric and optional userInput) or (cancel)[flows.md#cancel] method. See here for more information on how to pass a (PIN)[../second-factor-management#pin] or (biometrics)[../second-factor-management#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 (on initial input validation), a FlowUpdate callback for a flow with State PROCESSING comes back from the nextAuth Mobile SDK. After this FlowUpdate, another FlowUpdate is guaranteed to follow, for a flow with either:

• 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 continue;
• BIOMETRICS_REMOVED, meaning that the the biometric was removed from the account due to an error, but the flow can continue;
• State=DONE;
• State=ERROR and a specific error.

SET_SECOND_FACTOR

Ask the user to enter their second factor for registration purposes (i.e. first set or during a change of 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 biometric can be set.

User input should be provided to the nextAuth Mobile SDK by the inputSecondFactor (along with a PIN and/or biometric and optional user input) or (cancel)[flows.md#cancel] method.

Info

When setting the second factor it is possible to set both a pin AND biometrics at the same time. See (here)[../second-factor-management.md#initial-setting-of-second-factor] for more information.

Provided that the inputSecondFactor method does not throw an exception (on initial input validation), a FlowUpdate callback for a flow with State PROCESSING comes back from the nextAuth Mobile SDK. After this FlowUpdate, another FlowUpdate is guaranteed to follow, for a flow with either:

• 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

While on Android the current Flow can be fetched from the Mobile SDK, this is not possible on iOS.

Android

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

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

In principle 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 (transition between two interactions or termination of the flow);
• SecondFactorAccount and Session can change at any time and will reflect most recent values when fetching the flow. For simplicity, during user input and interaction, the developer can ignore changes to these fields (the current SDK will not broadcast updates for these fields anyway during an interaction).