The Mobile SDK has a concept of authenticated sessions. Each login and enrolment has a session associated with it.
Starting a Session⚓︎
A session can be started in several ways. It can be started externally, by scanning a QR code, clicking on a deep link inside a browser or other app installed on the same mobile device, or by a push message to the app. It can also be started from the app itself, for logging in into the app itself and accessing backend resources in a strongly authenticated way.
Scan QR Code⚓︎
The scanned QR code is passed to the nextAuth Mobile SDK with a call to start a session for the given QR code. The nextAuth Mobile SDK has a built-in QR code reader that can handle binary QR codes (smaller in size than regular base64 encoded QR codes).
The data contained in the deep link is passed to the nextAuth Mobile SDK with a call to start a session for the given data.
The app receives an encrypted push message which is passed along to the nextAuth Mobile SDK. If the decrypted push message is a login, the login process will be triggered automatically.
The app starts an app login with a special call to the nextAuth Mobile SDK. When an app login succeeds, the session associated with the app login will contain the necessary information for securely accessing backend resources.
The diagram below shows the session lifecycle.
Each session has a state of its own. The main states are
ACTIVE. After terminating, the session goes to the
DONE state. The Mobile SDK communicates to the app in which state (or pseudo state) it is through callbacks (depicted in blue).
Every session starts in the
STARTING state, after which it goes almost immediately to
READY_FOR_USER_INTERACTION. During the
STARTING state the necessary information is fetched from the server.
In this state, the Mobile SDK expects a confirmation from the app that it is ready for user interaction. This state can be used to temporarily put a session on hold, while waiting for the app to become active again or to allow the user to wait. The Mobile SDK can also be configured to always skip this step. Upon receiving confirmation with (startUserInteraction) that it can start the user interaction, the Mobile SDK goes to the state
This state is skipped in case of an app login.
In this state, the Mobile SDK expects feedback from the user, be it in the form of a confirmation or the input of a second factor (PIN or biometric). It is possible that multiple rounds of user input are required.
There are two pseudo states within
WAIT_FOR_CONFIRMATION pseudo state, the Mobile SDK expects the user to select the account to continue with (setAccount) or their indication to abort this session (stopSession). For an enrolment, the account will be the newly created account. For login, this will be one of the accounts that the user can use to log in with for this session. Often there will only be one account to choose from.
The Mobile SDK can be configured to bypass the
WAIT_FOR_CONFIRMATION state, given that a second factor is needed. As such, the user will still need to interact for each session, at least in the form of confirming their intent. For the specific case of an app login, the Mobile SDK will go straight from the
STARTING state to the
WAIT_FOR_SECOND_FACTOR state and always expect a second factor from the user.
The process for a login and an enrolment is very similar (apart from receiving a confirmLogin or confirmEnrol callback). The Mobile SDK will determine which process it is by the data passed along in the startSession (which is coming from, e.g., a QR code or a deep link) or processPush (which is coming from an encrypted push message). At the first enrolment, the user will be asked to provide an (app-specific) PIN and/or biometric. At subsequent enrolments and logins, the user will be asked to confirm their identity by providing the same PIN or biometric.
WAIT_FOR_SECOND_FACTOR pseudo state, the Mobile SDK expects the user's second factor (setPinBiometric) or their indicating to abort this session (inputCancel). Depending on the nextAuth server configuration, the session specific configuration, the Mobile SDK configuration and the time since the last input of a second factor, the second factor may not be needed.
The result of a second factor verification is always communicated back to the app through another SecondFactor callback. Depending on the event contained in this callback, the Mobile SDK might expect user input.
After the user interaction, the state becomes
DONE (no more interaction possible with this session) or
ERROR (there has been an error, no more interaction possible with this session).
ACTIVE state indicates the session is active and no user input is expected anymore. It does not imply in any way that the login process is finished. The app can always stop the session by calling stopSession.
ERROR state is a final state, indicating an error occurred during authentication. The session should be considered terminated.
DONE state is a final state, indicating the session finished in a normal way. It does not imply that the login was successful.
Sessions that are not in the
ERROR state will automatically go the
DONE state after a configurable timeout.
Each session has a status (which indicates in which of the five states the session currently is) and a history status. It also indicates whether or not it concerns a registration flow and/or an app login. In case of an app login, the session also contains the necessary information for starting an authenticated web session towards the associated backend, directly from inside the app.
Furthermore, sessions can contain announce info (information meant to be displayed towards the user when confirming or inputting a second factor) and session info (information meant to be displayed towards the user after being logged in) if this was supplied during the setup of the external authentication (i.e., the provided
UserContext in getQRLogin, for example).
Each session also has a history status. It starts with the default
FAIL status. Upon successful login, the history status changes to
LOGGED_IN (for continuous sessions, i.e. sessions where
pingTime > 0) or
LOGGED_IN_ONE_SHOT (for one shot authentications, i.e. a pingTime = 0) status. When there is no successful login, either because the user denied this action or the login has timed out, the history status changes to
ABORTED. When the user logs out of a continuous session (
pingTime > 0), the history status changes to
LOGGED_OUT. If the Mobile SDK encountered an error during authentication, its status will be set to
When the account that corresponds to the given history status is deleted, the history status is changed to