Concepts

Servers

The nextAuth Server (NS) allows you to set up multiple (virtual) servers running on a single NS. All virtual servers are separated and do not share any data (e.g., sessions, users, accounts), except that they run on the same NS and database. A server is identified by a random Server ID and is associated with a public/private key pair for server authentication. These are all automatically generated when creating a server through the API.

Every server can be configured separately with a different name, logo, and second factor settings.

Users

A User maps the account (public keys) that is used to authenticate with to a unique userid for your backend system. This userid can be any string and is determined by the user of the API. Obviously, a user can have multiple accounts (app instances, devices) linked to it. This way, it is possible for users to have multiple of their devices linked, e.g., a smart phone and a tablet.

Optionally, you can also define attributes for users, e.g., first name, last name, email, group membership... This way, your business applications can also learn specific attributes of the user that is currently logged in.

Accounts

An Account means an account inside a mobile app for a specific user at a specific server. Each account has its own public/private key pairs (these are not even shared among other accounts of the same user). Within the same app, there might be multiple accounts, corresponding to different users, potentially on different servers. On the server side, there might be multiple accounts which correspond to the same mobile device.

An account is considered headless when there is no second factor (PIN/biometric) associated with it.

Second Factor

nextAuth allows for the use of two types of second factors in the Mobile SDK: PIN and biometric. While a mobile app can have multiple accounts, it can only have one PIN code, which will be shared among all the accounts. For the biometric the hardware from the mobile device is used.

The verification of the second factor is handled by the SFS.

Secure Channel

A secure channel can be established between the Mobile SDK and the NS for transmitting arbitrary application data. The secure channel uses headless authentication, i.e. device authentication without any user interaction. When available, the hardware of the mobile device is used for authentication. Once the secure channel is established, arbitrary application data can be sent through it. The NS will deliver this application data, along with an identifier of the authenticated account, to a Data Service (DS) endpoint, where it can be handled further by application-specific software. The NS will also persist device data.

Account creation happens automatically when first using the secure channel from a mobile app. The account will be headless. Account upgrading allows adding a second factor to an existing headless account.

Transactions

A transaction is used to sign data. nextAuth does not impose any specific structure to the underlying data to be signed.

Transactions can be created both on the server side and directly in the Mobile SDK. Every transaction receives a unique identifier from the NS.

Signing a transaction always requires the entry of the second factor (PIN/biometric) of the user. When signed, the NS will store all the data to ensure non-repudiation of the transaction. Not only the signatures from the Mobile SDK are stored, but also the attestation from the SFS. Moreover, the signed data is wrapped, to include additional metadata (e.g. timestamps, additional application data, screenshots, device data).

Sessions (Login)

Whenever the mobile app performs a login, it does so with respect to a specific session. A Session Identifier, called Nonce in the API documentation, is an opaque string which can be arbitrarily chosen by the user of the API. We recommend using at least 16 random bytes (128 bit) and encoding these in hexadecimal or base64.

Based on the session identifier, one can check through the API whether a mobile app is authenticated for that specific session and, if so, which user (and account of the user) is logged in.

Internally, both the servers and nextAuth Mobile SDK do not use the session identifiers directly, but use derived identifiers.