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 right Second Factor Server and Message Center. All other configuration values below are optional.
| Parameter | Mandatory | Description |
|---|---|---|
| config | Signed configuration string provided by nextAuth. | |
| alwaysRequireSecondFactorIfInactiveAppLogin | Always require a second factor for logging in (web) if there is no active AppLogin. | |
| allowedProtocolVersions | Allowed protocol versions for the nextAuth server, second factor server, message center. | |
| automaticallySelectSingleAccountWhenSecondFactorNeeded | Boolean indicating whether the user should confirm logging in when there is only one account to select from and a second factor will requested afterwards, default: true. |
|
| biometricsDisabled | Boolean indicating whether biometrics should be disabled for the app, default: false. |
|
| blockSecondFactorOnPINBlocked | When set to true users will not longer be able to input a second factor as soon as their gets blocked, default: false. |
|
| defaultNSURI | URI of the default nextAuth server (e.g., wss://[your domain]/ns/sigmai), only used for sending a NOACCOUNTS message over the WebSocket to the browser when the user scan a login QR code (or clicks on a login deep link) when there are no accounts for that server. |
|
| disallowPinChangeWithBiometric | Boolean indicating whether the user can change their pin, based on the verification of their biometrics, default: false. |
|
| expiryHistoryItems | Duration string1 to set the maximum time a history item is kept by the mobile SDK, default: 2160h (90 days). Having a large number of history items slows down initialisation. |
|
| legacyBioAddFlow | When set to true, in a add biometrics flow, the user will first be asked to set biometrics and then to verify their pin, default: false. |
|
| legacyUserInteraction | When set to true, keep the v2 (legacy) way of working, default: false. |
|
| maxNumberSecondFactorWithoutPIN | Integer indicating when the user must enter a PIN if second factor confirmation is requested after a number of second factor confirmations with a biometric, default: 0 (ignored). Note that this value only has effect if biometrics are enabled. |
|
| maxPushLoginAge | Duration string1 indicating when the maximum age of a push login to be still processed, default: 0 (ignored). |
|
| maxTimeSecondFactorWithoutPIN | Duration string1 indicating when the user must enter a PIN if second factor confirmation is requested, default: 0 (ignored). Note that this value only has effect if biometrics are enabled. |
|
| singleAccount | Boolean indicating whether the app can only have a single account, default: false. |
|
| timeoutAppLogin | Duration string1 indicating after which duration of AppLogins must be logged out, default: 0 (ignored). Note that this value only has effect if your app uses AppLogins. |
|
| timeoutInactivityAppLogin | Duration string1 indicating after which duration of user inactivity AppLogins must be logged out, default: 0 (ignored). 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 string1 to set the time frame within which the user's input (with the exception of confirming the enrolment) needs to be supplied to the Mobile SDK after being requested to do so, default: 2m (2 minutes). After this timeout, the second factor (and corresponding session, if any) is stopped. |
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 login. This done by sending a NOACCOUNTS 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 (different server identifiers at the same URI is fine), we do not recommend setting the defaultNSURI value.
Android⚓︎
The following 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 following configuration parameters listed below are only used by the iOS SDK. Note that the appGroup parameters 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 | Boolean indicating whether the SDK's data directory should be migrated, 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 you to manually pass the configuration. This can only be done once and has to happen before any other interactions with the SDK.
guard NextAuth.default.canBeConfigured else {
return
}
NextAuth.default.configure(withConstants: constants)