SDK Configuration⚓︎

The Mobile SDK needs a signed configuration string provided by nextAuth. In order to obtain this configuration string, please follow the instructions here. It contains the parameters for connecting to the correct Second Factor Server and Message Center. All other configuration values below are optional.

Parameter	Mandatory	Description
config		Signed configuration string provided by nextAuth.
alwaysRequireSecondFactorIfInactiveAppLogin		When set to `true`, a second factor will always be required when logging in (web) if there is no active AppLogin.
allowedProtocolVersions		Allowed protocol versions for the nextAuth Server, Second Factor Server and Message Center.
automaticallySelectSingleAccountWhenSecondFactorNeeded		When set to `true`, if there is only one account to select from and if a second factor is requested, then the user will be logged in to that account after the second factor is verified. Default: `true`.
biometricsDisabled		When set to `true`, biometrics will be disabled for the app. Default: `false`.
blockSecondFactorOnPINBlocked		When set to `true`, users will no longer be able to input a second factor when their PIN is blocked. Default: `false`.
defaultNSURI		URI of the default nextAuth Server (e.g. wss://[your domain]/ns/sigmai). The default server is only used for sending a `NOACCOUNTS` message over the WebSocket to the browser when the user scans a login QR code (or clicks on a login deep link) when there are no accounts for that server.
disallowPinChangeWithBiometric		By default, users are allowed to change their PIN after verifying their biometrics (instead of verifying their old PIN). When this setting is set to true, then the use of biometrics for this purpose will be disabled. Default: `false`.
expiryHistoryItems		Duration string¹ which specifies the maximum amount of time a history item is kept by the Mobile SDK. An expiry duration which is too high may lead to a large number of history items, slowing down SDK initialisation as a result. Default: `2160h` (90 days).
legacyBioAddFlow		By default, users in the add biometric flow are first asked to verify their PIN, and afterwards to provide their biometric. When this setting is set to `true`, the order is reversed: users are first asked to provide their biometric, and then to verify their PIN. Default: `false`.
legacyUserInteraction		When set to `true`, the Mobile SDK will use the v2 (legacy) way of working with user interactions. Default: `false`.
maxNumberSecondFactorWithoutPIN		When set to an integer value greater than 0, this setting specifies the maximum number of second factor confirmations that can be performed (using biometrics) without entering a PIN; when the limit is reached, the user must enter a PIN if a second factor confirmation is requested. Default: `0` (no limit). Note that this value only has effect if biometrics are enabled.
maxPushLoginAge		Duration string¹ that specifies the maximum age of a push login that is allowed to be processed. Default: `0` (no maximum age).
maxTimeSecondFactorWithoutPIN		Duration string¹ that specifies the maximum amount of time during which second factor confirmations can be performed (using biometrics) without entering a PIN; when the time limit is reached, the user must enter a PIN if a second factor confirmation is requested. Default: `0` (no time limit). Note that this value only has effect if biometrics are enabled.
singleAccount		When set to true, the app is only permitted to have a single account. Default: `false`.
timeoutAppLogin		Duration string¹ that specifies how long an AppLogin is permitted to remain logged in, regardless of user activity. After the time limit is reached, the AppLogin is logged out. Default: `0` (no timeout). Note that this value only has effect if your app uses AppLogins.
timeoutInactivityAppLogin		Duration string¹ that specifies how long the user is permitted to be inactive during an AppLogin. After the inactivity time limit is reached, the AppLogin is logged out. Default: `0` (no inactivity timeout). Note that this value only has effect if your app uses AppLogins.
universalLinkPathPrefix		The prefix that should be removed from the path component of deep links. Default: `/`. For instance, if your deep link is `https://app.nextauth.com/authenticate/<data>`, you would set this parameter to `/authenticate/`.
universalLinkReferrerURLKey		The query parameter key that should be used to extract the referrer URL from deep links. Default: `referrer_url`.
userInputTimeout		Duration string¹ that specifies how long the Mobile SDK waits for the user’s input, excluding the time for confirming the enrolment. After the timeout expires, the second factor (and corresponding session, if any) is stopped. Default: `2m` (2 minutes).

Info

It might be useful to also alert users in the web frontend that they need to enrol an account first before being able to log in. This is done by sending a NOACCOUNTS message over the WebSocket to the browser. Since the login QR code (or deep link) only contains your server’s identifier but not its URI, this will need to be specified by setting the defaultNSURI.

If your app can be used to authenticate to multiple nextAuth servers at different URIs (or different server identifiers at the same URI), we do not recommend setting the defaultNSURI value.

Android⚓︎

The configuration parameters listed below are only used by the Android SDK.

Parameter	Mandatory	Description
automaticallyRetrieveMessagesWhenComingToForeground		Automatically retrieve messages from the Message Center when the app comes to the foreground, default: `true`.
automaticallyProcessPushLoginWhenInForeground		Automatically start a session for a received (push) login message when the app comes to the foreground, default: `true`.

The Mobile SDK configuration is specified as a JSON string that must contain all mandatory parameters. For the non-specified parameters, the SDK will take the default values.

{
  "config": ""
}

By default, the SDK looks for a nextauth.json file in the assets folder of the app. You can also manually pass the configuration as a JSON string or initialise the nextAuth Constants object.

// Default, looks for a nextauth.json file in the assets folder
NextAuth.init(getApplicationContext());

// Manually pass configuration
NextAuth.init(getApplicationContext(),"{\"config\": \"\"}");

// Initialise an instance of the nextAuth Constants object to pass the configuration
Constants constants = new Constants();
constants.config = "";
...
NextAuth.init(getApplicationContext(), constants);

iOS⚓︎

The configuration parameters listed below are only used by the iOS SDK. Note that the appGroup parameter is required for on-device builds, as detailed in our quick-start guide.

Parameter	Mandatory	Description
appGroup		The App Group you provisioned in the Apple Developer Portal, which is required for on-device builds (see here).
migrateDataDirectory		When this setting is true, the SDK’s data directory will be migrated to the current format. Default: `false`. This parameter should only be enabled for legacy applications.

The Mobile SDK configuration can be specified by initialising an instance of the NextAuth.Constants struct. Alternatively, it can be specified as a JSON or Property List string that must contain all mandatory parameters.

let constants = NextAuth.Constants(
    config: "",
    appGroup: ""
)

The Mobile SDK requires that you manually pass the configuration to it as an argument. This must be done only once and must happen before any other interactions with the SDK.

guard NextAuth.default.canBeConfigured else {
    return
}

NextAuth.default.configure(withConstants: constants)

A duration string consists of a number with a letter suffix to indicate the time unit. Supported units are “s” for seconds, “m” for minutes and “h” for hours. For example, “720h” means 30 days. ↩↩↩↩↩↩